[seam-dev] Bundled distribution documentation
Marek Novotny
mnovotny at redhat.com
Fri Sep 2 06:52:01 EDT 2011
I guess, it could be done by scripting a Web service
https://issues.jboss.org/browse/ORG-1123
On Fri, 2011-09-02 at 20:43 +1000, Shane Bryzak wrote:
> This would need to be automated for the Seam distribution build though.
> Currently, all modules have their docbook sources published as Maven
> artifacts, which is what we use to construct the bundled documentation.
>
> On 02/09/11 19:35, Marek Novotny wrote:
> > What about using feature "Export to docbook" and then just generate
> > standard jdocbook output in release process?
> >
> > https://docs.jboss.org/author/display/AUTHGUIDE/Exporting+content+to
> > +DocBook+XML
> >
> > On Fri, 2011-09-02 at 00:15 -0400, Lincoln Baxter, III wrote:
> >> I don't know. I don't really have plans to include docbook in the dist
> >> until we get some better integration there from the .ORG team. I don't
> >> see that happening, though, so until then, online docs are the way
> >> people will be learning about forge. Our tools don't make this easy.
> >>
> >> I don't think the connectivity issue will be a problem. People can
> >> always print or download the site for later if they have connectivity
> >> issues. It might be nice (on confluence) to be able to have a 1-click
> >> download, though.
> >>
> >> ~Lincoln
> >>
> >> On Thu, Sep 1, 2011 at 11:51 PM, Shane Bryzak<sbryzak at redhat.com>
> >> wrote:
> >> Yeah, that's a good idea. Do you have plans to provide
> >> documentation as part of the Forge download? I'm thinking of
> >> the users who might have no/limited connectivity who won't be
> >> able to access the Forge docs online. Also, how does
> >> confluence work in conjunction with our documentation team?
> >> From my understanding all their tools for translating etc are
> >> based on Publican/Docbook.
> >>
> >>
> >>
> >> On 02/09/11 13:48, Lincoln Baxter, III wrote:
> >> > Actually, maybe the best thing to do is just to add a new
> >> > section to the Seam umbrella doc, with an HTML link to the
> >> > forge confluence space?
> >> >
> >> > On Thu, Sep 1, 2011 at 7:54 PM, Lincoln Baxter, III
> >> > <lincolnbaxter at gmail.com> wrote:
> >> > Ok. If you include beta1, the artifact for dist is:
> >> >
> >> > org.jboss.forge:forge-modules:1.0.0.Beta1
> >> >
> >> > --
> >> > Lincoln Baxter's Droid
> >> > http://ocpsoft.com
> >> > "Keep it Simple"
> >> >
> >> >
> >> > On Sep 1, 2011 7:52 PM, "Shane Bryzak"
> >> > <sbryzak at redhat.com> wrote:
> >> > > Yep, I planned on extracting it in the forge
> >> > folder.
> >> > >
> >> > > On 02/09/11 09:43, Lincoln Baxter, III wrote:
> >> > >>
> >> > >> Also, if forge is unzipped. It should be done so
> >> > in its own subfolder.
> >> > >>
> >> > >> Ill try to catch you online tonight and make sure
> >> > you've got the right
> >> > >> artifact. (it moved temporarily during the jboss
> >> > modules transition.
> >> > >>
> >> > >> --
> >> > >> Lincoln Baxter's Droid
> >> > >> http://ocpsoft.com
> >> > >> "Keep it Simple"
> >> > >>
> >> > >> On Sep 1, 2011 7:41 PM, "Lincoln Baxter, III"
> >> > <lincolnbaxter at gmail.com
> >> >
> >> > >> <mailto:lincolnbaxter at gmail.com>> wrote:
> >> >
> >> > >> > Well. The forge distribution doesn't contain
> >> > docs either. They are
> >> > >> purely
> >> > >> > online at this point. So I think just don't
> >> > worry about it. This
> >> > >> confluence
> >> > >> > thing is a bit of a pain in that regard.
> >> > >> >
> >> > >> > --
> >> > >> > Lincoln Baxter's Droid
> >> > >> > http://ocpsoft.com
> >> > >> > "Keep it Simple"
> >> > >> > On Sep 1, 2011 6:05 PM, "Shane Bryzak"
> >> > <sbryzak at redhat.com
> >> >
> >> > >> <mailto:sbryzak at redhat.com>> wrote:
> >> > >> >> Unless an export could be automated as part of
> >> > the build process, I
> >> > >> >> don't think that's a good idea. How about we
> >> > just include the Forge
> >> > >> >> distribution extracted inside the Seam
> >> > distribution? The documentation
> >> > >> >> won't be combined with the main Seam docs, but
> >> > as long as it's in the
> >> > >> >> Forge distribution then a user should be able
> >> > to find it without too
> >> > >> >> much effort.
> >> > >> >>
> >> > >> >> On 02/09/11 01:22, Lincoln Baxter, III wrote:
> >> > >> >>>
> >> > >> >>> I'm not really sure how to do this, then.
> >> > There are no sources since
> >> > >> >>> the docs are in confluence.
> >> > >> >>>
> >> > >> >>> I suppose an export could work?
> >> > >> >>>
> >> > >> >>> --
> >> > >> >>> Lincoln Baxter's Droid
> >> > >> >>> http://ocpsoft.com
> >> > >> >>> "Keep it Simple"
> >> > >> >>>
> >> > >> >>> On Aug 31, 2011 5:09 PM, "Shane Bryzak"
> >> > <sbryzak at redhat.com
> >> > >> <mailto:sbryzak at redhat.com>
> >> >
> >> > >> >>> <mailto:sbryzak at redhat.com
> >> > <mailto:sbryzak at redhat.com>>> wrote:
> >> >
> >> > >> >>> > The source artifact for the Forge docs were
> >> > being pulled in like
> >> > >> this:
> >> > >> >>> >
> >> > >> >>> > <dependency>
> >> > >> >>> > <groupId>org.jboss.seam.forge</groupId>
> >> > >> >>> >
> >> > <artifactId>forge-reference-guide</artifactId>
> >> > >> >>> > <version>1.0.0-SNAPSHOT</version>
> >> > >> >>> > <classifier>sources</classifier>
> >> > >> >>> > <type>jar</type>
> >> > >> >>> > </dependency>
> >> > >> >>> >
> >> > >> >>> > When I update the version to 1.0.0.Beta1,
> >> > it can't find the source -
> >> > >> >>> was
> >> > >> >>> > the Beta1 source artifact published to
> >> > Maven?
> >> > >> >>> >
> >> > >> >>> >
> >> > >> >>> >
> >> > >> >>> > On 01/09/11 03:02, Lincoln Baxter, III
> >> > wrote:
> >> > >> >>> >>
> >> > https://docs.jboss.org/author/display/SEAMFORGE/Home
> >> > >> >>> >>
> >> > >> >>> >> On Wed, Aug 31, 2011 at 1:02 PM, Lincoln
> >> > Baxter, III
> >> > >> >>> >> <lincolnbaxter at gmail.com
> >> > <mailto:lincolnbaxter at gmail.com>
> >> > >> <mailto:lincolnbaxter at gmail.com
> >> > <mailto:lincolnbaxter at gmail.com>>
> >> > >> >>> <mailto:lincolnbaxter at gmail.com
> >> > <mailto:lincolnbaxter at gmail.com>
> >> > >> <mailto:lincolnbaxter at gmail.com
> >> > <mailto:lincolnbaxter at gmail.com>>>> wrote:
> >> > >> >>> >>
> >> > >> >>> >> Just checking - the Forge docs are no
> >> > longer in SVN / are in
> >> > >> >>> >> Confluence; have you taken this into
> >> > account?
> >> > >> >>> >>
> >> > >> >>> >> Also, the which distribution are you
> >> > including? You could choose
> >> > >> >>> >> either Beta1 or the latest SNAPSHOT (which
> >> > is actually in a new
> >> > >> >>> >> location - moved back to the original
> >> > >> >>> >> org.jboss.forge:forge-distribution -
> >> > though it looks like the
> >> > >> >>> >> build hasn't deployed artifacts in a
> >> > little while - looking in to
> >> > >> >>> >> that)
> >> > >> >>> >>
> >> > >> >>> >> ~Lincoln
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >> On Wed, Aug 31, 2011 at 12:14 AM, Shane
> >> > Bryzak
> >> > >> <sbryzak at redhat.com<mailto:sbryzak at redhat.com>
> >> > >> >>> <mailto:sbryzak at redhat.com
> >> > <mailto:sbryzak at redhat.com>>
> >> > >> >>> >> <mailto:sbryzak at redhat.com
> >> > <mailto:sbryzak at redhat.com>
> >> > >> <mailto:sbryzak at redhat.com
> >> > <mailto:sbryzak at redhat.com>>>> wrote:
> >> > >> >>> >>
> >> > >> >>> >> Module leads,
> >> > >> >>> >>
> >> > >> >>> >> Can you please review the list below and
> >> > confirm that the
> >> > >> >>> >> documentation
> >> > >> >>> >> chapters are correct for your module.
> >> > Also, I would like
> >> > >> >>> >> everyone to
> >> > >> >>> >> take a moment to review the module
> >> > documentation guidelines,
> >> > >> >>> >> as there
> >> > >> >>> >> were a number of breakages in the bundled
> >> > documentation build
> >> > >> >>> >> because
> >> > >> >>> >> the guidelines weren't adhered to,
> >> > particularly in the new
> >> > >> >>> >> modules for
> >> > >> >>> >> Seam 3.1:
> >> > >> >>> >>
> >> > >> >>> >> 1) Always prefix the filenames of your
> >> > documentation chapters
> >> > >> >>> >> with the
> >> > >> >>> >> name of your module. E.g.
> >> > security-authentication.xml,
> >> > >> >>> >> security-authorization.xml, etc.
> >> > >> >>> >>
> >> > >> >>> >> 2) Whenever you assign an ID to a docbook
> >> > element, such as a
> >> > >> >>> >> <chapter>
> >> > >> >>> >> or<section>, ALWAYS prefix the id with
> >> > your module name. For
> >> > >> >>> >> example,
> >> > >> >>> >> <chapter id="security-introduction"> or
> >> > <section
> >> > >> >>> >> id="security-getting-started">. As all of
> >> > the chapters for
> >> > >> >>> >> all modules
> >> > >> >>> >> are combined when building the bundled
> >> > documentation, all IDs
> >> > >> >>> >> must be
> >> > >> >>> >> unique. This is a particularly time
> >> > consuming problem to fix
> >> > >> >>> >> because
> >> > >> >>> >> the error output from the Maven docbook
> >> > plugin doesn't tell
> >> > >> >>> >> you which
> >> > >> >>> >> files are the problem ones.
> >> > >> >>> >>
> >> > >> >>> >> 3) When adding, renaming or deleting a
> >> > chapter of your
> >> > >> >>> >> documentation,
> >> > >> >>> >> please notify me of the changes so that I
> >> > can update
> >> > >> >>> >> bundled_master.xml. This file must be
> >> > manually kept up to
> >> > >> >>> >> date whenever
> >> > >> >>> >> any documentation changes are made.
> >> > >> >>> >>
> >> > >> >>> >> Thanks,
> >> > >> >>> >> Shane
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >> <?xml version='1.0' encoding="utf-8"?>
> >> > >> >>> >> <!DOCTYPE book PUBLIC "-//OASIS//DTD
> >> > DocBook XML V4.5//EN"
> >> > >> >>> >>
> >> > "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
> >> > >> >>> >> <book lang="en"
> >> > xmlns:xi="http://www.w3.org/2001/XInclude">
> >> > >> >>> >>
> >> > >> >>> >> <toc />
> >> > >> >>> >>
> >> > >> >>> >> <title>Seam 3</title>
> >> > >> >>> >> <subtitle>Bundled Reference
> >> > Guide</subtitle>
> >> > >> >>> >>
> >> > >> >>> >> <xi:include href="bundled_credits.xml"/>
> >> > >> >>> >> <xi:include href="bundled_intro.xml"/>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Forge</title>
> >> > >> >>> >> <xi:include href="forge-preface.xml" />
> >> > >> >>> >> <xi:include
> >> > href="forge-installation.xml" />
> >> > >> >>> >> <xi:include
> >> > href="forge-creating-basic-webapp.xml" />
> >> > >> >>> >> <xi:include href="forge-plugin-dev.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Solder</title>
> >> > >> >>> >> <xi:include href="solder-preface.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-gettingstarted.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-programmingmodel.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-annotationliterals.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-elextensions.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-resourceloading.xml"/>
> >> > >> >>> >> <xi:include href="solder-logging.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-typeutilities.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-beanmanagerprovider.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-beanutilities.xml"/>
> >> > >> >>> >> <xi:include href="solder-properties.xml"/>
> >> > >> >>> >> <xi:include href="solder-unwraps.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-defaultbeans.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-genericbeans.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="solder-servicehandler.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Configuration</title>
> >> > >> >>> >> <xi:include
> >> > href="config-introduction.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="config-xml-provider.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Persistence</title>
> >> > >> >>> >> <xi:include
> >> > href="persistence-general.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Transaction</title>
> >> > >> >>> >> <xi:include
> >> > href="transaction-general.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Servlet</title>
> >> > >> >>> >> <xi:include
> >> > href="servlet-introduction.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="servlet-installation.xml"/>
> >> > >> >>> >> <xi:include href="servlet-events.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="servlet-injectable_refs.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="servlet-exception_handling.xml" />
> >> > >> >>> >> <xi:include
> >> > href="servlet-beanmanager.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Security</title>
> >> > >> >>> >> <xi:include
> >> > href="security-introduction.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="security-authentication.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="security-identitymanagement.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="security-authentication-external.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="security-authorization.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam International</title>
> >> > >> >>> >> <xi:include
> >> > href="international-preface.xml" />
> >> > >> >>> >> <xi:include
> >> > href="international-installation.xml" />
> >> > >> >>> >> <xi:include
> >> > href="international-locales.xml" />
> >> > >> >>> >> <xi:include
> >> > href="international-timezones.xml" />
> >> > >> >>> >> <xi:include
> >> > href="international-messages.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Faces</title>
> >> > >> >>> >> <xi:include href="faces-preface.xml" />
> >> > >> >>> >> <xi:include
> >> > href="faces-installation.xml" />
> >> > >> >>> >> <xi:include href="faces-events.xml" />
> >> > >> >>> >> <xi:include href="faces-scopes.xml" />
> >> > >> >>> >> <xi:include href="faces-messages.xml" />
> >> > >> >>> >> <xi:include href="faces-artifacts.xml" />
> >> > >> >>> >> <xi:include href="faces-components.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Catch</title>
> >> > >> >>> >> <xi:include
> >> > href="catch-introduction.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="catch-installation.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="catch-client_usage.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="catch-advanced_usage.xml"/>
> >> > >> >>> >> <xi:include href="catch-integration.xml"/>
> >> > >> >>> >> <xi:include href="catch-glossary.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Reports</title>
> >> > >> >>> >> <xi:include href="reports-preface.xml" />
> >> > >> >>> >> <xi:include
> >> > href="reports-installation.xml" />
> >> > >> >>> >> <xi:include href="reports-usage.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Remoting</title>
> >> > >> >>> >> <xi:include href="remoting-general.xml"/>
> >> > >> >>> >> <xi:include href="remoting-model.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="remoting-validation.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam REST</title>
> >> > >> >>> >> <xi:include href="rest-preface.xml" />
> >> > >> >>> >> <xi:include
> >> > href="rest-installation.xml" />
> >> > >> >>> >> <xi:include
> >> > href="rest-exception-mapping.xml" />
> >> > >> >>> >> <xi:include href="rest-validation.xml" />
> >> > >> >>> >> <xi:include href="rest-templating.xml" />
> >> > >> >>> >> <xi:include href="rest-client.xml" />
> >> > >> >>> >> <xi:include
> >> > href="rest-dependencies.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam JCR</title>
> >> > >> >>> >> <xi:include href="jcr-introduction.xml" />
> >> > >> >>> >> <xi:include href="jcr-modeshape.xml"/>
> >> > >> >>> >> <xi:include href="jcr-jackrabbit.xml"/>
> >> > >> >>> >> <xi:include href="jcr-event-mapping.xml"/>
> >> > >> >>> >> <xi:include href="jcr-ocm.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam JMS</title>
> >> > >> >>> >> <xi:include href="jms-intro.xml" />
> >> > >> >>> >> <xi:include href="jms-installation.xml" />
> >> > >> >>> >> <xi:include
> >> > href="jms-resource-injection.xml" />
> >> > >> >>> >> <xi:include href="jms-messaging.xml" />
> >> > >> >>> >> <xi:include href="jms-routing.xml" />
> >> > >> >>> >> <xi:include
> >> > href="jms-mapping-interfaces.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Validation</title>
> >> > >> >>> >> <xi:include
> >> > href="validation-introduction.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="validation-installation.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="validation-dependency-injection.xml"/>
> >> > >> >>> >> <xi:include
> >> > href="validation-method-validation.xml"/>
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> <part>
> >> > >> >>> >> <title>Seam Wicket</title>
> >> > >> >>> >> <xi:include href="wicket-preface.xml" />
> >> > >> >>> >> <xi:include
> >> > href="wicket-installation.xml" />
> >> > >> >>> >> <xi:include href="wicket-features.xml" />
> >> > >> >>> >> </part>
> >> > >> >>> >>
> >> > >> >>> >> </book>
> >> > >> >>> >>
> >> > _______________________________________________
> >> > >> >>> >> seam-dev mailing list
> >> > >> >>> >> seam-dev at lists.jboss.org
> >> > <mailto:seam-dev at lists.jboss.org>
> >> > >> <mailto:seam-dev at lists.jboss.org
> >> > <mailto:seam-dev at lists.jboss.org>>
> >> > >> >>> <mailto:seam-dev at lists.jboss.org
> >> > <mailto:seam-dev at lists.jboss.org>
> >> > >> <mailto:seam-dev at lists.jboss.org
> >> > <mailto:seam-dev at lists.jboss.org>>>
> >> > >> >>> >>
> >> > https://lists.jboss.org/mailman/listinfo/seam-dev
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >> --
> >> > >> >>> >> Lincoln Baxter, III
> >> > >> >>> >> http://ocpsoft.com
> >> > >> >>> >> http://scrumshark.com
> >> > >> >>> >> "Keep it Simple"
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >>
> >> > >> >>> >> --
> >> > >> >>> >> Lincoln Baxter, III
> >> > >> >>> >> http://ocpsoft.com
> >> > >> >>> >> http://scrumshark.com
> >> > >> >>> >> "Keep it Simple"
> >> > >> >>> >
> >> > >> >>
> >> > >
> >> >
> >> >
> >> >
> >> >
> >> > --
> >> > Lincoln Baxter, III
> >> > http://ocpsoft.com
> >> > http://scrumshark.com
> >> > "Keep it Simple"
> >>
> >>
> >>
> >>
> >>
> >> --
> >> Lincoln Baxter, III
> >> http://ocpsoft.com
> >> http://scrumshark.com
> >> "Keep it Simple"
> >> _______________________________________________
> >> seam-dev mailing list
> >> seam-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/seam-dev
>
--
Marek Novotny
--
Seam and WFK Product Lead
Red Hat Czech s.r.o.
Purkynova 99
612 45 Brno
Email: mnovotny at redhat.com
Office phone: +420 532 294 287, ext. 82-62 087
mobile: +420 608 509 230
More information about the seam-dev
mailing list