[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>
  &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>
  
  
  
  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