[seam-dev] Module documentation

[Jason Porter]

Another great reference to look at is
http://hudson.jboss.org/hudson/job/JBoss_Documentation_Guide/lastSuccessfulBuild/artifact/JBoss_Documentation_Guide/target/docbook/publish/en-US/html/index.html

On Tue, Feb 15, 2011 at 14:56, Shane Bryzak <sbryzak at redhat.com> wrote:
> To assist with the bundled documentation build, could everyone please
> ensure that you prefix your docbook id tags with the name of your
> module.  This is unfortunately necessary as docbook requires unique ID
> values and will fail otherwise.  To illustrate what I mean, let's
> pretend that two of our modules, faces and security both have
> introduction chapters:
>
> <chapter id="introduction">
> <title>Seam Faces - Introduction</title>
> ...
>
>
>
> <chapter id="introduction">
> <title>Seam Security - Introduction</title>
> ...
>
>
> Since both chapters have an id of "introduction", docbook fails when
> attempting to build the bundled docs.  To workaround this restriction,
> we can simply add the module name:
>
>
> <chapter id="faces-introduction">
> <title>Seam Faces - Introduction</title>
> ...
>
>
>
> <chapter id="security-introduction">
> <title>Seam Security - Introduction</title>
> ...
>
>
> Can you also please apply the same naming standard to the docbook source
> files, and chapter titles (this will help to keep the bundled
> documentation more consistent).
>
> Lastly, if you need to add a new chapter to your module documentation
> (or rename an existing one), can you please let one of the core team
> devs know.  Our bundled documentation build has its own master.xml file
> containing all the individual chapters from each module, and new
> chapters need to be manually added to this file [1].  Alternatively, you
> can make the modification yourself and send a pull request.
>
> Thanks,
> Shane
>
> [1]
> https://github.com/seam/dist/blob/master/docs/src/main/docbook/en-US/master.xml
>
> _______________________________________________
> seam-dev mailing list
> seam-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/seam-dev
>



-- 
Jason Porter
http://lightguard-jp.blogspot.com
http://twitter.com/lightguardjp

Software Engineer
Open Source Advocate

PGP key id: 926CCFF5
PGP key available at: keyserver.net, pgp.mit.edu