From sbryzak at redhat.com Tue Feb 15 16:56:33 2011
Content-Type: multipart/mixed; boundary="===============5013664292414523163=="
MIME-Version: 1.0
From: Shane Bryzak <sbryzak at redhat.com>
To: seam-dev at lists.jboss.org
Subject: [seam-dev] Module documentation
Date: Wed, 16 Feb 2011 07:56:30 +1000
Message-ID: <4D5AF68E.60006@redhat.com>

--===============5013664292414523163==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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=3D"introduction">
<title>Seam Faces - Introduction</title>
...



<chapter id=3D"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=3D"faces-introduction">
<title>Seam Faces - Introduction</title>
...



<chapter id=3D"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 =



--===============5013664292414523163==--