[seam-dev] Module documentation

[Shane Bryzak]

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