[jboss-cvs] jboss-profiler/docbook/docbook-support/docs/guide/en/modules ...
Clebert Suconic
csuconic at jboss.com
Fri Nov 10 12:40:18 EST 2006
User: csuconic
Date: 06/11/10 12:40:18
Added: docbook/docbook-support/docs/guide/en/modules styles.xml
howto.xml introduction.xml
Log:
Adding docbook under jboss-profiler tree
Revision Changes Path
1.1 date: 2006/11/10 17:40:18; author: csuconic; state: Exp;jboss-profiler/docbook/docbook-support/docs/guide/en/modules/styles.xml
Index: styles.xml
===================================================================
<chapter id="styles">
<title>Maintain the JBoss DocBook system</title>
<para> The structure of the <literal>docbook-support</literal> module is
illustrated in <xref linkend="docbook.fig"/>. The contents are as follows. </para>
<figure id="docbook.fig">
<title>The docbook-support module </title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/docbook.png"/>
</imageobject>
</mediaobject>
</figure>
<itemizedlist>
<listitem> The <literal>support</literal> directory contains Java
libraries and executables for XML processors. It also contains
standard DocBook XSL stylesheets. This is the place for "system" software.</listitem>
<listitem> The <literal>styles</literal> directory contains DocBook
styles we developed in-house for JBoss. Each language would have a
separate set of styles.</listitem>
<listitem> The <literal>docs</literal> directory contains this guide to
serve as a template for other projects. </listitem>
<listitem> The <literal>support.xml</literal> file contains all the
necessary ANT tasks to build DocBooks. It is referenced from the
<literal>build.xml</literal> file for each individual DocBook
project. </listitem>
</itemizedlist>
</chapter>
1.1 date: 2006/11/10 17:40:18; author: csuconic; state: Exp;jboss-profiler/docbook/docbook-support/docs/guide/en/modules/howto.xml
Index: howto.xml
===================================================================
<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>
<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>
</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>
1.1 date: 2006/11/10 17:40:18; author: csuconic; state: Exp;jboss-profiler/docbook/docbook-support/docs/guide/en/modules/introduction.xml
Index: introduction.xml
===================================================================
<chapter id="introduction">
<title>Introduction to DocBook proceessing</title>
<para> DocBook is an XML format to write documents. It allows the author to
focus on the content itself during the writing process instead of
worrying about the presentation. </para>
<para> Using the standard DocBook tags, we can tag the content according to
their syntax structure. The DocBook document is then processed against
XSL style sheets. Each tagged element in the DocBook is transformed to a
presentation element with the style (e.g., margin, font etc.) specified
in the XSL. Using different XSL stylesheets, we can generate different
output documents. For example, we can generate HTML and PDF outputs from
a single DocBook source. We can also generate multiple versions of PDF
(or HTML) files each with a different formatting style. </para>
<para> In the JBoss DocBook system, we provide XSL stylesheets to build HTML
and PDF outputs from the DocBook source. The build process is
illustrated in <xref linkend="build.fig"/>. </para>
<figure id="build.fig">
<title>The DocBook build process </title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/build.png"/>
</imageobject>
</mediaobject>
</figure>
</chapter>
More information about the jboss-cvs-commits
mailing list