<chapter id="howto">
    <title>How to develop content for JBoss DocBook</title>
    <section>
        <title>Setup the directories</title>
        <para> Each top-level JBoss project (<literal>projectname/</literal>) in
            the public CVS stores its documentations in the
            <literal>projectname/docs</literal> directory. The
            <literal>projectname/docs</literal> 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 <literal>projectname/docs</literal>. For example, the user's
            guide DocBook for a project could be placed in
            <literal>projectname/docs/userguide</literal>. The easiest way to
            setup this DocBook directory is to copy the
            <literal>docbook-support/docs/guide</literal> directory to your
            target project and use it as a template. The
            <literal>userguide</literal> DocBook structure for the JBoss AOP
            project is shown in <xref linkend="aop.fig"/>. </para>
        <figure id="aop.fig">
            <title>The user guide DocBook in the AOP project </title>
            <mediaobject>
                <imageobject>
                    <imagedata align="center" fileref="images/aop.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <para> 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
            <literal>en/</literal> sub-directory. Inside each language
            directory, there are typically two sub-directories for contents:</para>
        <itemizedlist>
            <listitem> The <literal>images/</literal> directory stores images. </listitem>
            <listitem> The <literal>modules/</literal> directory stores DocBook
                text modules for each chapter. </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>Author the content</title>
        <para> 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
            <literal>book</literal> element) in the
            <literal>master.xml</literal> file directly under the language
            directory (see <xref linkend="aop.fig"/>). You can either put the
            entire content in <literal>master.xml</literal> or divide up the
            chapters and place them in the <literal>modules/</literal>
            directory. If you do the latter, you should reference the chapter
            files from the <literal>master.xml</literal> file via entity
            reference. Please see the
            <literal>docbook-support/docs/guide/en/master.xml</literal> file to
            see how it is done. </para>
    </section>
    <section>
        <title> Build the documents </title>
        <para> To build the deliverable documents, just run ANT against the
            <literal>build.xml</literal> file in the DocBook directory. The
            <literal>build.xml</literal> file is really simple and its content
            is shown below. It delegates most of the tasks to the
            <literal>support.xml</literal> file mainatined by the
            <literal>docbook-support</literal> project. </para>
        <programlisting>
&lt;project name="Documentation" default="all.doc" basedir="."&gt;

    &lt;property name="pdf.name" value="jboss-mybook.pdf" /&gt;
    &lt;import file="../../../docbook-support/support.xml" /&gt;

    &lt;target name="all.doc" depends="clean"&gt;
        &lt;antcall target="lang.all"&gt;
            &lt;param name="lang" value="en"/&gt;
        &lt;/antcall&gt;
    &lt;/target&gt;

&lt;/project&gt;
        </programlisting>
        <para> After the build is finished, you have three output documents for
            each language edition in the following places:</para>
        <itemizedlist>
            <listitem> The <literal>build/en/html</literal> directory contains
                the HTML version of the document. Each chapter is broken into a
                separate HTML file and they are linked by the
                <literal>index.html</literal> file.</listitem>
            <listitem> The <literal>build/en/html_signle</literal> directory
                contains a big <literal>index.html</literal> file which holds
                the entire document. </listitem>
            <listitem> The <literal>build/en/pdf</literal> directory contains
                the PDF version of the document. </listitem>
        </itemizedlist>
    </section>
</chapter>
