Chapter 2. How to develop content for JBoss DocBook
Prev |  | Next

## Chapter 2. How to develop content for JBoss DocBook

## 2.1. Setup the directories

Each top-level JBoss project (`projectname/`) in the public CVS stores its documentations in the `projectname/docs` directory. The `projectname/docs` directory can contain any number of subdirectories for API references, sample code, user guide etc. But each DocBook should be placed in its own directory directly under `projectname/docs`. For example, the user's guide DocBook for a project could be placed in `projectname/docs/userguide`. The easiest way to setup this DocBook directory is to copy the `docbook-support/docs/guide` directory to your target project and use it as a template. The `userguide` DocBook structure for the JBoss AOP project is shown in Figure 2.1, “The user guide DocBook in the AOP project ”.

Figure 2.1. The user guide DocBook in the AOP project

Inside the DocBook directory, there are typically several sub-directories, each corresponding to a specific lanuguage version of the document. The English version resides in the `en/` sub-directory. Inside each language directory, there are typically two sub-directories for contents:

- The `images/` directory stores images.
- The `modules/` directory stores DocBook text modules for each chapter.

## 2.2. Author the content

Now you can write your content in DocBook format. Make sure that the master file of your DocBook (i.e., the file that contains the `book` element) in the `master.xml` file directly under the language directory (see Figure 2.1, “The user guide DocBook in the AOP project ”). You can either put the entire content in `master.xml` or divide up the chapters and place them in the `modules/` directory. If you do the latter, you should reference the chapter files from the `master.xml` file via entity reference. Please see the `docbook-support/docs/guide/en/master.xml` file to see how it is done.

## 2.3. Build the documents

To build the deliverable documents, just run ANT against the `build.xml` file in the DocBook directory. The `build.xml` file is really simple and its content is shown below. It delegates most of the tasks to the `support.xml` file mainatined by the `docbook-support` project.

    <project name="Documentation" default="all.doc" basedir=".">

        <property name="pdf.name" value="jboss-mybook.pdf" />
        <import file="../../../docbook-support/support.xml" />

        <target name="all.doc" depends="clean">
            <antcall target="lang.all">
                <param name="lang" value="en"/>
            </antcall>
        </target>

    </project>

After the build is finished, you have three output documents for each language edition in the following places:

- The `build/en/html` directory contains the HTML version of the document. Each chapter is broken into a separate HTML file and they are linked by the `index.html` file.
- The `build/en/html_signle` directory contains a big `index.html` file which holds the entire document.
- The `build/en/pdf` directory contains the PDF version of the document.

Prev | Up | Next
Chapter 1. Introduction to DocBook proceessing | Home | Chapter 3. Maintain the JBoss DocBook system