Each JBoss.org project stores its documentation in a docs directory, typically located at <projectName>/trunk/docs. By convention the source for each DocBook should be placed into subdirectories directly beneath this. For example, the DocBook source for a project's User Guide should be placed in
<projectName>/trunk/docs/userguide whilst the DocBook source for a Reference Guide should be placed in <projectName>/trunk/docs/reference. Alongside these DocBook subdirectories any number
of other subdirectories containing API references, code examples, and articles may also be created.
For example the docs directory for the JBoss Messaging project is shown in Figure 2.1, “The JBoss Messaging docs directory”.
To facilitate translation into other languages the original source of a DocBook is written in English and located in a directory named en. Within this there are typically two subdirectories for the content:
-
images- stores images -
modules- stores DocBook text modules, usually one per chapter
The master.xml file contains the top-level <book> element and is used to group all of the other text modules together. If you choose to use Ant to perform the build then a build.xml file is used to call the relevant tasks. Otherwise a pom.xml file can be called using Maven2.
The easiest way to
setup a DocBook subdirectory within your project is to copy the
docbook-support/docs/guide
directory (containing the DocBook source for this guide) and use it as a template.