<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

<!-- Include macros -->
<!entity conventions SYSTEM "conventions.sgml">
<!entity example-article SYSTEM "example-article.sgml">
<!entity example-book SYSTEM "example-book.sgml">
<!entity example-compile-sgml SYSTEM "compiles-sgml.sgml">
<!entity example-table SYSTEM "example-table.sgml">
<!entity dsl-example SYSTEM "dsl-example.sgml">
<!entity glossary SYSTEM "glossary.sgml">

<!-- Inserting the index -->
<!entity index SYSTEM "index.sgml">

<!-- Text Macros -->
<!entity conectivasa '<ulink url="http://www.conectiva.com">Conectiva S.A.</ulink>'>
<!entity conectiva "Conectiva">

]>

<article class="whitepaper" id="using-docbook" lang="en">

  <artheader>
    <title>DocBook HOWTO</title>
    <author>
      <firstname>Jorge</firstname>
      <surname>Godoy</surname>
      <affiliation>
        <orgname>&conectivasa;</orgname>
        <orgdiv>Publishing Department</orgdiv>
        <address><email>godoy@conectiva.com</email></address>
        <address><email>godoy@metalab.unc.edu</email></address>
      </affiliation>
    </author>
    <revhistory>
      <revision>
        <revnumber>1.3</revnumber>
        <date>February, 17th 2000</date>
        <authorinitials>godoy</authorinitials>
        <revremark>Initial version.</revremark>
      </revision>
      <revision>
        <revnumber>1.4</revnumber>
        <date>June, 24th 2000</date>
        <authorinitials>godoy</authorinitials>
        <revremark>English corrections and added some more
        explanation on DocBook usage. I've added CSS to my stylesheets
        and if you have a CSS enabled browser you'll see a lot of
        difference from the previous version. I've corrected and added
        information based on all feedback I received since the first
        version of it.</revremark>
      </revision>
      <revision>
        <revnumber>1.5</revnumber>
        <date>June, 26th 2000</date>
        <authorinitials>godoy</authorinitials>
        <revremark>English corrections made by Horylka. Thanks.</revremark>
      </revision>
    </revhistory>

    <legalnotice>
      <para>This document can be freely distributed and translated under the  
      terms of the LDP License.</para>
    </legalnotice>

    <keywordset>
      <keyword>SGML</keyword>
      <keyword>DocBook</keyword>
      <keyword>DTD</keyword>
      <keyword>XML</keyword>
      <keyword>catalogues</keyword>
      <keyword>documents</keyword>
      <keyword>Publishing</keyword>
      <keyword>Conectiva</keyword>
      <keyword>configurations</keyword>
      <keyword>usage</keyword>
      <keyword>tools</keyword>
      <keyword>HOWTO</keyword>
    </keywordset>

  </artheader>


  <abstract>
    <para>This document's sole purpose is to provide basic knowledge
    about DocBook and explain how to use DocBook to write several
    types of documents; not all of DocBook's functions aren't explained.</para>
    <para>This document will emphasize how to create books, guides, and articles
    that will be published over the Internet.</para>
    <para>Any suggestions, corrections and comments regarding this document can  
    be sent to the author: <ulink url="mailto:godoy@conectiva.com">Jorge
    Godoy</ulink>.</para>
    <para>An original copy of this document can be obtained by the copy of the
    files <ulink url="sgml/using-docbook.sgml">using-docbook.sgml</ulink>,
    <ulink url="sgml/example-book.sgml">example-book.sgml</ulink>, <ulink
    url="sgml/example-article.sgml">example-article.sgml</ulink>, <ulink
    url="sgml/example-table.sgml">example-table.sgml</ulink>, <ulink
    url="sgml/compiles-sgml.sgml">compiles-sgml.sgml</ulink>, <ulink
    url="sgml/dsl-example.sgml">dsl-sample.sgml</ulink> and <ulink   
    url="sgml/glossary.sgml">glossary.sgml</ulink>.</para> 
    <para>You can find this document as a one page HTML file <ulink
    url="using-docbook.html">here</ulink>. This should easy
    downloading and/or printing this document.</para>
  </abstract>

  <section id="introduction">
    <title>Introduction</title>

    <para>DocBook defines a set of markup elements useful for marking
    up text so that the text can then be transformed into several
    different formats.</para>

    <para>It's possible to create documents in different formats
    <acronym>HTML</acronym>, <acronym>XML</acronym>, <acronym>RTF</acronym>,
    TeX, and others.</para>

    <para>The idea is to write just once and reach the largest possible number
    of people with the information.</para>

    <para>Digital information not stored properly tends to get lost. Due to the
    fact that not containing uncommon characters (such as binary formats) it's
    possible to index and search directly on the documents written on 
    <acronym>SGML</acronym> and
    consequently on DocBook.</para>

    <para>The <acronym>SGML</acronym> systems use markups to make their
    description. DocBook holds over 300 markup elements each one with several
    attributes which can assume several values, these can be fixed or defined
    by the document / style that the author has used.</para>

    <para>Just to remind if any changes are made on the DocBook's definitions
    <acronym>DTD</acronym>, it's no longer DocBook.</para> 

  </section>

&conventions;

  <section id="configurations">
    <title>Configuration needed </title>
    <indexterm zone="configurations">
      <primary>configurations</primary>
    </indexterm>

    <para>The identifier systems used by the SGML and by some tools
    are based on catalogues which perform the translation of these
    identifiers over to files holding the necessary definitions.</para>

    <para>The section on tailoring a catalogue (see <xref
    linkend="making-catalogues">) will give more details about these
    files.</para> 

    <para>For such tools to be able to find the necessary catalogue(s)
    the value of the environment variable <envar>SGML_CATALOG_FILES</envar>
    should be configured, as shown in the following example:</para> 

    <informalexample id="var-sgml-catalog-files">
      <para>
      <screen><prompt>$</prompt> <command>export</command> <envar>SGML_CATALOG_FILES="/usr/lib/sgml/catalog"</envar></screen></para>
    </informalexample>

    <indexterm zone="var-sgml-catalog-files">
      <primary>configurations</primary>
      <secondary>variables</secondary>
      <tertiary>SGML_CATALOG_FILES</tertiary>
    </indexterm>

    <para>This is the only necessary additional configuration for the DocBook,
    tools and the like to work correctly on your platform.</para>

  </section>

  <section id="making-catalogues">
    <title>Creating and modifying catalogues</title>

    <indexterm zone="making-catalogues">
      <primary>catalogues</primary>
      <secondary>creating</secondary>
    </indexterm>

    <indexterm zone="making-catalogues">
      <primary>catalogue</primary>
      <secondary>modifying</secondary>
    </indexterm>

    <para>A catalogue is a text file containing the translation rules of the
    public identifier to system's files.</para>

    <para>They make easy to use the DocBook, for they allow each user to have
    their files installed in a different place (e.g. your home directory, 
    <filename class="directory">/usr/local/sgml</filename> or in any other
    place) though no other change on the document is necessary to be processed
    and <quote>compiled</quote>.</para>

    <example id="example-catalogue">
      <title>Example of catalogue</title>
      <programlistingco>
        <areaspec>
          <area coords="1" id="ex.catalogue.comment">
          <area coords="5" id="ex.catalogue.definition">
          <area coords="11" id="ex.catalogue.eof">
        </areaspec>
        <programlisting>
-- Catalogue for the Conectiva Styles -- 

OVERRIDE YES
 
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN" 
       "/home/ldp/styles/books.dtd" 

DELEGATE "-//OASIS" 
         "/home/ldp/SGML/dtds/catalog.dtd"

DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
 
-- EOF -- 
        </programlisting>
        <calloutlist>
          <callout arearefs="ex.catalogue.comment">
            <para> Comment. Comments start with <quote>--</quote> and
            follow to the end of the line. </para> 
          </callout>
          <callout arearefs="ex.catalogue.definition">
            <para> The public type association <parameter class="option">"-//Conectiva SA//DTD books V1.0//EN"</parameter>
            with the file <filename>books.dtd</filename> on the directory <filename
            class="directory">/home/ldp/styles</filename>. </para> 
          </callout>
          <callout arearefs="ex.catalogue.eof">
            <para> Comment informing the end of the file.</para>
          </callout>
        </calloutlist>
      </programlistingco>
      <indexterm zone="example-catalogue">
        <primary>catalogue</primary>
        <secondary>creating</secondary>
        <tertiary>example</tertiary>
      </indexterm>
      <indexterm zone="example-catalogue">
        <primary>catalogue</primary>
        <secondary>modifying</secondary>
        <tertiary>sample</tertiary>
      </indexterm>
    </example>

    <para>As in the example above, to associate an identifier to a file just 
    follow the sequence shown:</para>

    <orderedlist>
      <listitem>
        <para>Copy the identifier <emphasis>PUBLIC</emphasis></para>
      </listitem>
      <listitem>
        <para>Type the identifying text </para>
      </listitem>
      <listitem>
        <para>Indicate the path to the associated file</para>
      </listitem>
    </orderedlist>

    <section id="catalogue-explaining-terminology">
      <title>Explaining the terminology system </title>

      <indexterm zone="catalogue-explaining-terminology">
        <primary>catalogue</primary>
        <secondary>creating</secondary>
        <tertiary>terminology</tertiary>
      </indexterm>
      <indexterm zone="catalogue-explaining-terminology">
        <primary>catalogue</primary>
        <secondary>modifying</secondary>
        <tertiary>terminology</tertiary>
      </indexterm>

      <para>Notice the identifier</para>

      <programlisting>"-//Conectiva SA//DTD books V1.0//EN"</programlisting>

      <para>Its formation is not random and follows some pre-defined
      conditions.</para>

      <para>The token <quote>-</quote> indicates that the used identfier isn't a 
      registered type. Only a few identifiers are registered and those usualy
      belong to entities like <acronym>ISO</acronym>, <acronym>IEEE</acronym>, 
      and others.</para>

      <para>The second part of the identfier defines the name of the 
      organization that created it. On the example above, &conectiva; S.A.</para>

      <para>The one before the last defines the contents (in this case a 
      <acronym>DTD</acronym><footnote>
          <para>Here are valid: <acronym>DTD</acronym>, DOCUMENT, ELEMENTS,
      ENTITIES and NONSGML.</para> </footnote>) and the name of the identified
      text.</para>

      <para>The last element indicates the language in which the document was
      written. Since DocBook is a DTD written in English, the language is
      <literal>EN</literal>. The two letter code recommended is the 
      <acronym>ISO</acronym> identification of the language.</para>

      <para>More information can be obtained at <ulink
      url="http://www.oasis-open.org/html/a401.htm">OASIS Technical Resolution
      9401:1997 (Amendment 2 to TR 9401)</ulink>.</para> 
    </section>

    <section id="making-catalogues-commands">
      <title>Useful command for catalogues</title>

      <para>The most common commands to be used on catalogues are:</para>

      <variablelist>
        <varlistentry>
          <term><literal>PUBLIC</literal></term>
          <listitem>
            <para>The keyword <literal>PUBLIC</literal> maps
            public identifiers for identifiers on the system.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>SYSTEM</literal></term>
          <listitem>
            <para>The keyword<literal>SYSTEM</literal> maps
            system identifiers for files on the system.</para>
            <informalexample>
              <para>
SYSTEM "http://nexus.conectiva/utilidades/publicacoes/livros.dtd" 
              "publicacoes/livros.dtd"</para>
            </informalexample>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>SGMLDECL</literal></term>
          <listitem>
            <para>The keyword <literal>SGMLDECL</literal> designates the
            system identifier of the SGML statement that should be used.
            </para>
            <informalexample>
              <para>
SGMLDECL "publishings/books.dcl"</para>
            </informalexample>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>DTDDECL</literal></term>
          <listitem>
            <para>Similar to the <literal>SGMLDECL</literal> the
            keyword <literal>DTDDECL</literal> identifies the SGML statement
            that should be used. <literal>DTDDECL</literal> makes the 
            association of the statement with a public identifier to a
            <acronym>DTD</acronym>. Unfortunately this association isn't 
            supported by the charge free tools available. The benefits of this
            statement can be achieved somehow with multiple catalogue files.
            </para>
            <informalexample>
              <para>
DTDDECL "-//Conectiva SA//DTD livros V1.0//EN" "publicacoes/livros.dcl"</para>
            </informalexample>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>CATALOG</literal></term>
          <listitem>
            <para>The keyword <literal>CATALOG</literal> allows a catalogue
            to be included inside another. This is a way to make use of several
            different catalogues without the need to alter them.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>OVERRIDE</literal></term>
          <listitem>
            <para>The keyword <literal>OVERRIDE</literal> informs whether an 
            identifier has priority over a system identifier.
            The standard on most systems is that the system identifier
            has priority over the public one.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>DELEGATE</literal></term>
          <listitem>
            <para>The keyword <literal>DELEGATE</literal> allows the 
            association of a catalogue to a specific type of public identifier.
            The clause <literal>DELEGATE</literal> is very similar to the
            <literal>CATALOG</literal>, except by the fact that it doesn't do
            anything until a specific pattern is specified.<para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>DOCTYPE</literal></term>
          <listitem>
            <para>In case of a document starts with a type of document, but
            has no public identifier and no system identifier the clause 
            <literal>DOCTYPE</literal> makes the association of this document
            with an specific DTD.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

  </section>

  <section id="tools-edition">
    <title>Tools for Document Edition Using DocBook</title>

    <indexterm zone="tools-edition">
      <primary>edition</primary>
      <secondary>tools</secondary>
    </indexterm>

    <para>Several tools are available to facilitate the edition work of  
    documents on the DocBook format. Due to the complexity of its rules and 
    the large variety of element options and attributes to them, the use of 
    these automatic tools are recommended.</para>

    <para>A comprehensive list can be found at <ulink
    url="http://www.oasis-open.org/docbook/tools/index.html">the OASIS
    tools list</ulink>.</para>

    <para>Particularly and without the intention to start any religious 
    <quote>war</quote> among editors, I think the solution
    <application>emacs</application> +
    <application>psgml</application> is the best solution at hands,
    regarding either the open source or the free of charge
    issue.</para>

    <para>The tool used is according to each author's 
    preference, however, it's recomended to have at least the 
    following features:</para>

    <itemizedlist>
      <listitem>
        <para>Analysis of the <acronym>DTD</acronym> dynamically</para>
      </listitem>
      <listitem>
        <para>Insertion of elements based on <acronym>DTD</acronym>
        analyzed</para> 
      </listitem>
      <listitem>
        <para>Visual highlight of the text either in color or any other 
        possible attributes. This helps to differentiate the text from constant
        processing elements and instructions on it.</para>
      </listitem>
    </itemizedlist>

  </section>

  <section id="writing-docbook">
    <title>Writing with DocBook elements</title>

    <indexterm zone="writing-docbook">
      <primary>edition</primary>
      <secondary>using DocBook</secondary>
    </indexterm>

    <para>An editor capable of inserting an element according with
    <acronym>DTD</acronym> analisys helps a lot since it can allow or
    not the element to be used at the position where the cursor is
    in. This way you can be sure that no invalid element was added
    anywhere in your document.</para>

    <para>In order to ensure future changes are as easy as possible,
    authors should try to keep as much compatibility as possible with
    the<acronym>XML</acronym> version of the DocBook DTD.  This means
    keeping element names in upper case, using double quotes in all
    attributes, not using <quote>markup minimizations</quote>
    (explained below), and not omitting end tags. Most tools that
    automatically insert elements (like psgml+emacs) follow these
    rules automatically or with some fine tuning.</para> 

    <para id="markup-minimization">There are several forms of markup 
    minimization. These include empty tags.  One example of tag
    minimization is that instead of
    typing the end tag you simply type <sgmltag
    class="endtag"></sgmltag>. Another example, as said before, is
    ommiting tags. You can see both examples below:</para>

    <informalexample>
      <programlisting format="linespecific">
<sgmltag class="starttag">para</sgmltag>I'm using <sgmltag class="starttag">emphasis</sgmltag>here<sgmltag class="endtag"></sgmltag>, normal text here, 
and <sgmltag class="starttag"></sgmltag>here<sgmltag class="endtag"></sgmltag> I emphasized the text again, with empty tags.<sgmltag class="endtag">para</sgmltag>
</programlisting>
    </informalexample>

    <para>Each type of document created has a specific structure and example of
    documents can found afterwards on this document. (see
    <xref linkend="examples-documents">).</para>

    <para>Considering the explanation above we can proceed to instructions on 
    how to write a document using DocBook.</para>

    <section id="writing-docbook-commands">
      <title>Useful commands</title>

      <indexterm>
        <primary>edition</primary>
        <secondary>using DocBook</secondary>
        <tertiary>commands</tertiary>
      </indexterm>

      <para>The <xref linkend="table-useful-commands"> shows some commands which 
      are useful to generate generic documents. Remember that some elements are
      valide only on some contexts.</para>

      <tip>
        <para>Sometimes the appearance of a particular tag changes
        from one format to another. As a beginner in DocBook writing,
        you ay wish to see how your document looks in several formats
        before you publish them.</para>
      </tip>

      <note>
        <para>Since the formatting depends on the output style chosen, it's
        recommended to use as much markup as possible. Even if the appearance
        of the output doesn't seem to change with the standard output
        style, there may be specific output formats that will make
        these tags stand out.</para>
      </note>

      <table id="table-useful-commands">
        <title>Useful commands</title>
        <tgroup cols="3">
          <thead>
            <row>
              <entry>Description</entry>
              <entry>Command</entry>
              <entry>Result</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>E-mail address</entry>
              <entry><sgmltag class="starttag">email</sgmltag>address@domain<sgmltag
              class="endtag">email</sgmltag></entry>
              <entry><email>address@domain</email></entry>
            </row>
            <row>
              <entry>About the author</entry>
              <entry><sgmltag class="starttag">author</sgmltag>...<sgmltag
              class="endtag">author</sgmltag></entry>
              <entry>(see example below)</entry>
            </row>
            <row>
              <entry>Author's name</entry>
              <entry><programlisting>
<sgmltag class="starttag">firstname</sgmltag>First_Name<sgmltag class="endtag">firstname</sgmltag>
<sgmltag class="starttag">othername</sgmltag>Middle_Name<sgmltag class="endtag">othername</sgmltag>
<sgmltag class="starttag">surname</sgmltag>Surname<sgmltag class="endtag">surname</sgmltag>
              </programlisting></entry> 
              <entry><author>
                  <firstname>First Name</firstname>
                  <othername>Middle Name</othername>
                  <surname>Surname</surname>
                </author></entry>
            </row>
            <row>
              <entry>Keys' name (printings on the keyboard)</entry>
              <entry><sgmltag class="starttag">keycap</sgmltag>F1<sgmltag
              class="endtag">keycap</sgmltag></entry>
              <entry><keycap>F1</keycap></entry>
            </row>
            <row>
              <entry>Symbol represented by the keys</entry>
              <entry><sgmltag class="starttag">keysym</sgmltag>KEY_F1<sgmltag
              class="endtag">keysym</sgmltag></entry>
              <entry><keysym>KEY_F1</keysym></entry>
            </row>
            <row>
              <entry>Key's code</entry>
              <entry><sgmltag class="starttag">keycode</sgmltag>0x3B<sgmltag
              class="endtag">keycode</sgmltag></entry>
              <entry><keycode>0x3B</keycode></entry>
            </row>
            <row>
              <entry>Combinations or sequences of keys</entry>
              <entry><programlisting>
<sgmltag class="starttag">keycombo</sgmltag>
   <sgmltag class="starttag">keycap</sgmltag>Ctrl<sgmltag class="endtag">keycap</sgmltag>
   <sgmltag class="starttag">keycap</sgmltag>S<sgmltag class="endtag">keycap</sgmltag>
<sgmltag class="endtag">keycombo</sgmltag>
              </programlisting></entry> 
              <entry><keycombo>
                  <keycap>Ctrl</keycap>
                  <keycap>S</keycap>
                </keycombo></entry>
            </row>
            <row>
              <entry>Programs Menu</entry>
              <entry><sgmltag class="starttag">guimenu</sgmltag>File<sgmltag
              class="endtag">guimenu</sgmltag></entry>
              <entry><guimenu>File</guimenu></entry>
            </row>
            <row>
              <entry>Menu Items</entry>
              <entry><sgmltag
              class="starttag">guimenuitem</sgmltag>Salvar<sgmltag
              class="endtag">guimenuitem</sgmltag></entry> 
              <entry><guimenuitem>Save</guimenuitem></entry>
            </row>
            <row>
              <entry>Menu Sequences</entry>
              <entry><programlisting>
<sgmltag class="starttag">menuchoice</sgmltag>
   <sgmltag class="starttag">shortcut</sgmltag>
      <sgmltag class="starttag">keycombo</sgmltag>
         <sgmltag class="starttag">keycap</sgmltag>Ctrl<sgmltag class="endtag">keycap</sgmltag>
         <sgmltag class="starttag">keycap</sgmltag>S<sgmltag class="endtag">keycap</sgmltag>
      <sgmltag class="endtag">keycombo</sgmltag>
   <sgmltag class="endtag">shortcut</sgmltag>
   <sgmltag class="starttag">guimenu</sgmltag>Arquivo<sgmltag class="endtag">guimenu</sgmltag>
   <sgmltag class="starttag">guimenuitem</sgmltag>Salvar<sgmltag class="endtag">guimenuitem</sgmltag>
<sgmltag class="endtag">menuchoice</sgmltag>
              </programlisting></entry>
              <entry><menuchoice>
                  <shortcut>
                    <keycombo>
                      <keycap>Ctrl</keycap>
                      <keycap>S</keycap>
                    </keycombo>
                  </shortcut>
                  <guimenu>File</guimenu>
                  <guimenuitem>Save</guimenuitem>
                </menuchoice></entry>
            </row>
            <row>
              <entry>Mouse Button</entry>
              <entry><sgmltag
              class="starttag">mousebutton</sgmltag>left<sgmltag
              class="endtag">mousebutton</sgmltag></entry> 
              <entry><mousebutton>left</mousebutton></entry>
            </row>
            <row>
              <entry>Command Names</entry>
              <entry><sgmltag class="starttag">command</sgmltag>comando<sgmltag
              class="endtag">command</sgmltag></entry>
              <entry><command>command</command></entry>
            </row>
            <row>
              <entry>Application Names</entry>
              <entry><sgmltag
              class="starttag">application</sgmltag>application<sgmltag
              class="endtag">application</sgmltag></entry> 
              <entry><application>application</application></entry>
            </row>
            <row>
              <entry>Text Bibliographical Reference</entry>
              <entry><sgmltag
              class="starttag">citation</sgmltag>reference<sgmltag
              class="endtag">citation</sgmltag></entry> 
              <entry><citation>reference</citation></entry>
            </row>
            <row>
              <entry>Quote</entry>
              <entry><programlisting>
<sgmltag class="starttag">blockquote</sgmltag>
   <sgmltag class="starttag">attribution</sgmltag>Text Author<sgmltag class="endtag">attribution</sgmltag>
   <sgmltag class="starttag">para</sgmltag>Quote Text.<sgmltag class="endtag">para</sgmltag>
<sgmltag class="endtag">blockquote</sgmltag>
              </programlisting></entry>
              <entry><para><blockquote>
                    <attribution>Text Author</attribution>
                    <para>Quote Text.</para>
                  </blockquote></para></entry>
            </row>
            <row>
              <entry>Index</entry>
              <entry>(NA)</entry>
              <entry>See <xref linkend="encoding-index">.</entry>
            </row>
            <row>
              <entry>File Names</entry>
              <entry><programlisting>
<sgmltag class="starttag">filename</sgmltag>file<sgmltag class="endtag">filename</sgmltag></programlisting></entry>
              <entry><filename>file</filename></entry>
            </row>
            <row>
              <entry>Directories</entry>
              <entry><programlisting>
<sgmltag class="starttag">filename id="directory"</sgmltag>directory<sgmltag class="endtag">filename</sgmltag></programlisting></entry>
              <entry><filename class="directory">directory/</filename></entry>
            </row>
            <row>
              <entry>Emphasize Text<footnote>
                  <para>The text can be enphasized in a few ways. The most 
                  common ways are italics and bold. DocBook, however, supports only
                  italics. The use of bold requires additional settings on the 
                  stylesheet used.</para>
                </footnote>
</entry>
              <entry><programlisting>
<sgmltag class="starttag">emphasis</sgmltag>text<sgmltag class="endtag">emphasis</sgmltag></programlisting></entry>
              <entry><emphasis>text</emphasis></entry>
            </row>
            <row>
              <entry>Footnotes</entry>
              <entry><programlisting>
<sgmltag class="starttag">footnote</sgmltag>
   <sgmltag class="starttag">to</sgmltag>Footnote text<sgmltag class="endtag">to</sgmltag>
<sgmltag class="endtag">footnote</sgmltag></programlisting></entry>
              <entry>(See note at the end of this table)</entry>
            </row>
            <row>
              <entry>URLs</entry>
              <entry><programlisting>
<sgmltag class="starttag">ulink url="http://www.conectiva.com</sgmltag>Conectiva S.A.<sgmltag class="endtag"></sgmltag></programlisting></entry> 
              <entry><ulink url="http://www.conectiva.com">Conectiva S.A.</ulink></entry>
            </row>
            <row>
              <entry>Markups List</entry>
              <entry><programlisting>
<sgmltag class="starttag">itemizedlist</sgmltag>
   <sgmltag class="starttag">listitem</sgmltag>
      <sgmltag class="starttag">to</sgmltag>item<sgmltag class="endtag">to</sgmltag>
   <sgmltag class="endtag">listitem</sgmltag>
   <sgmltag class="starttag">listitem</sgmltag>
      <sgmltag class="starttag">to</sgmltag>item<sgmltag class="endtag">to</sgmltag>
   <sgmltag class="endtag">listitem</sgmltag>
<sgmltag class="endtag">itemizedlist</sgmltag>
</programlisting></entry>
              <entry><itemizedlist>
                  <listitem>
                    <para>item</para>
                  </listitem>
                  <listitem>
                    <para>item</para>
                  </listitem>
                </itemizedlist></entry>
            </row>
            <row>
              <entry>Numbered List</entry>
              <entry><programlisting>
<sgmltag class="starttag">orderedlist</sgmltag>
   <sgmltag class="starttag">listitem</sgmltag>
      <sgmltag class="starttag">to</sgmltag>item<sgmltag class="endtag">to</sgmltag>
   <sgmltag class="endtag">listitem</sgmltag>
   <sgmltag class="starttag">listitem</sgmltag>
      <sgmltag class="starttag">to</sgmltag>item<sgmltag class="endtag">to</sgmltag>
   <sgmltag class="endtag">listitem</sgmltag>
<sgmltag class="endtag">orderedlist</sgmltag>
</programlisting></entry>
              <entry><orderedlist>
                  <listitem>
                    <para>item</para>
                  </listitem>
                  <listitem>
                    <para>item</para>
                  </listitem>
                </orderedlist></entry>
            </row>
            <row>
              <entry>Segmented List</entry>
              <entry><programlisting>
<sgmltag class="starttag">segmentedlist</sgmltag>
   <sgmltag class="starttag">title</sgmltag>Binary to decimal conversion<sgmltag class="endtag">title</sgmltag>
   <sgmltag class="starttag">segtitle</sgmltag>Binary<sgmltag class="endtag">segtitle</sgmltag>
   <sgmltag class="starttag">segtitle</sgmltag>Decimal<sgmltag class="endtag">segtitle</sgmltag>
   <sgmltag class="endtag">seglistitem</sgmltag><sgmltag class="starttag">seg</sgmltag>00<sgmltag class="endtag">seg</sgmltag><sgmltag class="starttag">seg</sgmltag>0<sgmltag class="endtag">seg</sgmltag>
   <sgmltag class="endtag">seglistitem</sgmltag>
   <sgmltag class="starttag">seglistitem</sgmltag><sgmltag class="starttag">seg</sgmltag>01<sgmltag class="endtag">seg</sgmltag><sgmltag class="starttag">seg</sgmltag>1<sgmltag class="endtag">seg</sgmltag>
   <sgmltag class="endtag">seglistitem</sgmltag>
   <sgmltag class="starttag">seglistitem</sgmltag><sgmltag class="starttag">seg</sgmltag>10<sgmltag class="endtag">seg</sgmltag><sgmltag class="starttag">seg</sgmltag>2<sgmltag class="endtag">seg</sgmltag>
<sgmltag class="endtag">segmentedlist</sgmltag>
</programlisting></entry>
              <entry><segmentedlist>
                  <title>Binary to Decimal Conversion</title>
                  <segtitle>Binary</segtitle>
                  <segtitle>Decimal</segtitle>
                  <seglistitem>
                    <seg>00</seg>
                    <seg>0</seg>
                  </seglistitem>
                  <seglistitem>
                    <seg>01</seg>
                    <seg>1</seg>
                  </seglistitem>
                  <seglistitem>
                    <seg>10</seg>
                    <seg>2</seg>
                  </seglistitem>
                </segmentedlist></entry>
            </row>
            <row>
              <entry>Variable List</entry>
              <entry><programlisting>
<sgmltag class="starttag">variablelist</sgmltag>
   <sgmltag class="starttag">varlistentry</sgmltag>
      <sgmltag class="starttag">term</sgmltag>Entry 1<sgmltag class="endtag">term</sgmltag>
      <sgmltag class="starttag">listitem</sgmltag>
         <sgmltag class="starttag">to</sgmltag>Description<sgmltag class="endtag">to</sgmltag>
      <sgmltag class="endtag">listitem</sgmltag>
   <sgmltag class="endtag">varlistentry</sgmltag>
   <sgmltag class="starttag">varlistentry</sgmltag>
      <sgmltag class="starttag">term</sgmltag>Entry 2<sgmltag class="endtag">term</sgmltag>
      <sgmltag class="starttag">listitem</sgmltag>
         <sgmltag class="starttag">to</sgmltag>Description<sgmltag class="endtag">to</sgmltag>
      <sgmltag class="endtag">listitem</sgmltag>
   <sgmltag class="endtag">varlistentry</sgmltag>
<sgmltag class="endtag">variablelist</sgmltag>
</programlisting></entry>
              <entry><variablelist>
                  <varlistentry>
                    <term>Entry 1</term>
                    <listitem>
                      <para>Description</para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>Entry 2</term>
                    <listitem>
                      <para>Description</para>
                    </listitem>
                  </varlistentry>
                </variablelist></entry>
            </row>
            <row>
              <entry>Simple Lists</entry>
              <entry><programlisting>
<sgmltag class="starttag">simplelist type="horiz" columns="3"</sgmltag>
   <sgmltag class="starttag">member</sgmltag>1<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>2<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>3<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>4<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>5<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>6<sgmltag class="endtag">member</sgmltag>
<sgmltag class="endtag">simplelist</sgmltag>
<sgmltag class="starttag">simplelist type="inline"</sgmltag>
   <sgmltag class="starttag">member</sgmltag>A<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>B<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>C<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>D<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>E<sgmltag class="endtag">member</sgmltag>
   <sgmltag class="starttag">member</sgmltag>F<sgmltag class="endtag">member</sgmltag>
<sgmltag class="endtag">simplelist</sgmltag>
</programlisting></entry>
              <entry><simplelist columns="3" type="horiz">
                  <member>1</member>
                  <member>2</member>
                  <member>3</member>
                  <member>4</member>
                  <member>5</member>
                  <member>6</member>
                </simplelist><simplelist type="inline">
                  <member>A</member>
                  <member>B</member>
                  <member>C</member>
                  <member>D</member>
                  <member>E</member>
                  <member>F</member>
                </simplelist></entry>
            </row>
            <row>
              <entry>Pictures</entry>
              <entry>(NA)</entry>
              <entry>See <xref linkend="inserting-pictures"></entry>
            </row>
            <row>
              <entry>Table</entry>
              <entry>(NA)</entry>
              <entry>See <xref linkend="tables"></entry>
            </row>
            <row>
              <entry>Programs List</entry>
              <entry>(NA)</entry>
              <entry>See <xref linkend="listings"></entry>
            </row>
            <row>
              <entry>Glossary</entry>
              <entry><programlisting>
<sgmltag class="starttag">glossentry</sgmltag>
   <sgmltag class="starttag">glossterm</sgmltag>Term<sgmltag class="endtag">glossterm</sgmltag>
   <sgmltag class="starttag">glossdef</sgmltag>
      <sgmltag class="starttag">to</sgmltag>Definition<sgmltag class="endtag">to</sgmltag>
   <sgmltag class="endtag">glossdef</sgmltag>
<sgmltag class="endtag">glossentry</sgmltag></programlisting></entry>
              <entry>(See the glossary at the end of this document)</entry>
            </row>
            <row>
              <entry>Crossed References</entry>
              <entry><programlisting>
<sgmltag class="starttag">section id="secao"</sgmltag>
...
<sgmltag class="endtag">section</sgmltag>
<sgmltag class="starttag">section id="reference the other section"</sgmltag>
...
<sgmltag class="starttag">to</sgmltag>Please, see<sgmltag class="starttag">xref linkend="secao"</sgmltag> for more information.</programlisting></entry>
              <entry>(NA)</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

    </section>

  </section>

  <section id="encoding-index">
    <title>Encoding Indexes</title>

    <indexterm zone="encoding-index"> 
      <primary>edition</primary>
      <secondary>index</secondary>
    </indexterm>

    <para>The generation of indexes depends on the markups inserted in
    the text.</para>

    <para>Such markups will be processed afterwards by an external tool and 
    will generate the index. An example of such a tool is the 
    <filename>collateindex.pl</filename> script (see <xref
    linkend="tools-compile">). Details about the process used to generate
    these indexes are shown in <xref linkend="automatic-indexes">.</para>

    <para>The indexes have nesting levels. The markup of an index is done by the
    code <xref
    linkend="example-code-index">.</para>

    <example id="example-code-index">
      <title>Code for the generation of an index</title>
      <programlisting>
<sgmltag class="starttag">indexterm</sgmltag>
   <sgmltag class="starttag">primary</sgmltag>Main level<sgmltag class="endtag">primary</sgmltag>
   <sgmltag class="starttag">secondary</sgmltag>Second level<sgmltag class="endtag">secondary</sgmltag>
   <sgmltag class="starttag">tertiary</sgmltag>Third level<sgmltag class="endtag">tertiary</sgmltag>
<sgmltag class="endtag">indexterm</sgmltag>
      </programlisting>
    </example>

    <para>It's possible to refer to chapters, sections and other parts
    of the document using the <glossterm>attribute</glossterm> <sgmltag
    class="attribute">zone</sgmltag>.</para>

    <example id="index-zone">
      <title>Use of the attributte <sgmltag class="attribute">zone</sgmltag></title>
      <programlisting>
<sgmltag class="starttag">section id="encoding-index"</sgmltag>
    <sgmltag class="starttag">title</sgmltag>Encoding Indexes<sgmltag class="endtag">title</sgmltag>

    <sgmltag class="starttag">indexterm zone="encoding-index"</sgmltag>
      <sgmltag class="starttag">primary</sgmltag>edition<sgmltag class="endtag">primary</sgmltag>
      <sgmltag class="starttag">secondary</sgmltag>index<sgmltag class="endtag">secondary</sgmltag>
    <sgmltag class="endtag">indexterm</sgmltag>

    <sgmltag class="starttag">para</sgmltag>The generation of indexes depend on the inserted markups on the text. <sgmltag class="endtag">para</sgmltag>
      </programlisting>
    </example>

    <para>The <xref linkend="index-zone"> has the code used to generate the 
    entry of this edition on the index. In fact, since the attribute 
    <sgmltag class="attribute">zone</sgmltag> is used, the index statement 
    could be located anywhere in the document or even in a separate file.
    </para> 

    <para>However, to facilitate maintenance the entries for the index were all 
    placed after the text to which it refers.
    </para> 

    <example>
      <title>Usage of values <sgmltag class="attvalue">startofrange</sgmltag>and
      <sgmltag class="attvalue">endofrange</sgmltag> on the attribute<sgmltag
      class="attribute">class</sgmltag></title>
      <programlisting>
    <sgmltag class="starttag">PARA</sgmltag>Typing the text normally sometimes there's the need of 
   <sgmltag class="starttag">INDEXTERM CLASS="startofrange" ID="example-band-index"</sgmltag>
      <sgmltag class="starttag">PRIMARY</sgmltag>examples<sgmltag class="endtag">PRIMARY</sgmltag>
      <sgmltag class="starttag">SECONDARY</sgmltag>index<sgmltag class="endtag">SECONDARY</sgmltag>
   <sgmltag class="endtag">INDEXTERM</sgmltag>
   mark large amounts of text.<sgmltag class="endtag">para</sgmltag>

   <sgmltag class="starttag">para</sgmltag>Keep inserting the paragraphs normally.<sgmltag class="endtag">para</sgmltag>

   <sgmltag class="starttag">para</sgmltag>Until the end of the section intended
   to be indexed.
   <sgmltag class="starttag">INDEXTERM STARTREF="example-band-index" CLASS="endofrange"</sgmltag>.
   <sgmltag class="endtag">PARA</sgmltag></programlisting>
    </example>

  </section>

  <section id="inserting-pictures">
    <title>Inserting Pictures</title>

    <indexterm zone="inserting-pictures">
      <primary>graphics</primary>
      <secondary>inserting</secondary>
      <tertiary><sgmltag class="starttag">graphic</sgmltag></tertiary>
    </indexterm>
    <indexterm zone="inserting-pictures">
      <primary>figures</primary>
      <secondary>inserting</secondary>
      <tertiary><sgmltag class="starttag">figure</sgmltag></tertiary>
    </indexterm>


    <para>It's necessary to insert pictures for all types of media on which 
    the document will be published.</para>

    <para>If you use the TeX format you'll need the images as a
    PostScript file. For online publishing you can use any kind of
    common image file, such as <acronym>JPG</acronym>, 
    <acronym>GIF</acronym> or <acronym>PNG</acronym>.</para> 

    <para>The easiest way to insert pictures is the use of the attribute 
    <sgmltag class="attribute">fileref</sgmltag>. Usually pictures are generated
    in <acronym>JPG</acronym> and in PostScript (PS or EPS).</para>

    <example id="ex-picture-fileref">
      <title>Inserting a picture</title>
      <programlisting>
<sgmltag class="starttag">figure</sgmltag>
   <sgmltag class="starttag">title</sgmltag>Picture's Title<sgmltag class="endtag">title</sgmltag>
   <sgmltag class="starttag">graphic fileref="images/file"</sgmltag><sgmltag class="endtag">graphic</sgmltag>
<sgmltag class="endtag">figure</sgmltag>
</programlisting>
    </example>

    <para>Replacing <sgmltag class="starttag">figure</sgmltag> by
    <sgmltag class="starttag">informalfigure</sgmltag> eliminates the need to
    insert a title for the picture.</para>

    <para>There's still the <sgmltag class="attribute">float</sgmltag>
    attribute on which the value <literal>0</literal> indicates that the
    picture should be placed exactly where the text flux appears. The
    value <literal>1</literal> allows the picture to be moved to a more
    convenient location (this location can be described on the style
    sheet used or even can be controlled by the application being
    used).</para> 

    <section id="inserting-figures-mediaobject">
      <title>Alternative Methods</title>

      <indexterm zone="inserting-figures-mediaobject">
        <primary>graphics</primary>
        <secondary>inserting</secondary>
        <tertiary><sgmltag class="starttag">mediaobject</sgmltag></tertiary>
      </indexterm>
      <indexterm zone="inserting-figures-mediaobject">
        <primary>figures</primary>
        <secondary>inserting</secondary>
        <tertiary><sgmltag class="starttag">mediaobject</sgmltag></tertiary>
      </indexterm>

      <para>The first alternative to <xref linkend="ex-picture-fileref"> is
      the elimination of elements <sgmltag class="starttag">figure</sgmltag> or
      <sgmltag class="starttag">informalfigure</sgmltag>.</para>

      <para>Another interesting alternative when it's the decision to publish 
      the text on media and pictures aren't accepted, is the use of a
      wrapper <sgmltag class="starttag">imageobject</sgmltag>.</para>

      <example id="former-figure-imageobject">
        <title>Using <sgmltag class="starttag">imageobject</sgmltag></title>
        <programlisting>
<sgmltag class="starttag">figure</sgmltag>
   <sgmltag class="starttag">title</sgmltag>Title<sgmltag class="endtag">title</sgmltag>
   <sgmltag class="starttag">mediaobject</sgmltag>
      <sgmltag class="starttag">imageobject</sgmltag>
         <sgmltag class="starttag">imagedata fileref="images/file.eps" format="eps"</sgmltag>
      <sgmltag class="endtag">imageobject</sgmltag>
      <sgmltag class="starttag">imageobject</sgmltag>
         <sgmltag class="starttag">imagedata fileref="images/file.jpg" format="jpg"</sgmltag>
      <sgmltag class="endtag">imageobject</sgmltag>
      <sgmltag class="starttag">textobject</sgmltag>
         <sgmltag class="starttag">phrase</sgmltag>Here there's an image of this example<sgmltag class="endtag">phrase</sgmltag>
      <sgmltag class="endtag">textobject</sgmltag>
      <sgmltag class="starttag">caption</sgmltag><sgmltag class="starttag">para</sgmltag>Image Description. Optional. <sgmltag class="endtag">para</sgmltag><sgmltag class="endtag">caption</sgmltag>
   <sgmltag class="endtag">mediaobject</sgmltag>
<sgmltag class="endtag">figure</sgmltag>
</programlisting>
      </example>

      <para>Files on the following formats are available <simplelist type="inline">
        <member>BMP</member>
        <member>CGM-BINARY</member>
        <member>CGM-CHAR</member>
        <member>CGM-CLEAR</member>
        <member>DITROFF</member>
        <member>DVI</member>
        <member>EPS</member>
        <member>EQN</member>
        <member>FAX</member>
        <member>GIF</member>
        <member>GIF87A</member>
        <member>GIF89A</member>
        <member>IGES</member>
        <member>JPEG</member>
        <member>JPG</member>
        <member>LINESPECIFIC</member>
        <member>PCX</member>
        <member>PIC</member>
        <member>PS</member>
        <member>SGML</member>
        <member>TBL</member>
        <member>TEX</member>
        <member>TIFF</member>
        <member>WMF</member>
        <member>WPG</member>
      </simplelist>.</para>

      <para>This method presents an advantage: a better control of the 
      application. The elements <sgmltag class="starttag">imageobject</sgmltag>
      are consecutively tested until one of them is accepted. In case of the
      output format doesn't support images the element <sgmltag
      class="starttag">textobject</sgmltag> will be used. However, the biggest
      advantage in usage of the format <xref
      linkend="former-figure-imageobject"> is that on the release
      <literal>5.0</literal> of the DocBook the element <sgmltag
      class="starttag">graphic</sgmltag> will cease to exist.</para> 

      <para>As a disadvantage there's the need for more than one representation
      code of the same information. It's up to the author to decide which method
      he will implement illustrations and pictures on his or hers document, but
      for compatibility reasons with future versions <emphasis>I
      recommend</emphasis> the use of this method for pictures and
      graphics.</para> 

    </section>

  </section>

  <section id="tables">
    <title>Tables</title>

    <indexterm zone="ex-tables">
      <primary>tables</primary>
      <secondary>inserting</secondary>
    </indexterm>

    <para>Many information are best represented when formatted as tables.</para>
    
    <para>A primitive way to create tables was already presented on the <xref
    linkend="table-useful-commands"> with the use of <sgmltag
    class="starttag">simplelist</sgmltag>, however, the DocBook has more 
    sophisticated methods to deal with this information.</para>


    <example id="ex-tables">
      <title>Inserting tables</title>

      <programlisting>
&example-table;
      </programlisting>
    </example>

    <indexterm zone="ex-tables">
      <primary>tables</primary>
      <secondary>inserting</secondary>
      <tertiary>example</tertiary>
    </indexterm>

    <table frame="all">
      <title>Example Table</title>
      <tgroup cols="5">
        <colspec colname="column1">
        <colspec colname="column2">
        <colspec colname="column3">
        <colspec colnum="5" colname="column5">
        <spanspec namest="column1" nameend="column2" spanname="span-horiz" align="center">
        <spanspec namest="column2" nameend="column3" spanname="span-horiz-vert" align="center">
        <thead>
          <row>
            <entry spanname="span-horiz">Horizontal Span</entry>
            <entry>Heading 2</entry>
            <entry>Heading 3</entry>
            <entry>Heading 4</entry>
          </row>
        </thead>
        <tfoot>
          <row>
            <entry>Footing 1</entry>
            <entry>Footing 2</entry>
            <entry>Footing 3</entry>
            <entry>Footing 4</entry>
            <entry>Footing 5</entry>
          </row>
        </tfoot>
        <tbody>
          <row>
            <entry>Data11</entry>
            <entry>Data12</entry>
            <entry>Data13</entry>
            <entry>Data14</entry>
            <entry>Data15</entry>
          </row>
          <row>
            <entry>Data21</entry>
            <entry>Data22</entry>
            <entry>Data23</entry>
            <entry>Data24</entry>
            <entry morerows="1" valign="middle">Vertical Span</entry>
          </row>
          <row>
            <entry>Data31</entry>
            <entry spanname="span-horiz-vert" morerows="1" valign="bottom">Double Span</entry>
            <entry>Data34</entry>
          </row>
          <row>
            <entry>Data41</entry>
            <entry>Data44</entry>
            <entry>Data45</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

  </section>

  <section id="listings">
    <title>Listings and program codes</title>

    <indexterm zone="listings">
      <primary>listings</primary>
      <secondary>inserting</secondary>
    </indexterm>

    <para>An interesting feature is to show parts of code and the possibility to 
    comment on them. The DocBook allows the insertion of the program code and
    also callouts to specific lines of this code.</para> 
    
    <para>Such a feature was used, for example, to demonstrate how a catalogue
    file is configured (see <xref linkend="making-catalogues">).</para>

    <para>The used code was demonstrated below. In case the callout feature 
    isn't desired, it's possible to eliminate the areas between 
    <sgmltag class="starttag">areaspec</sgmltag> and <sgmltag
    class="starttag">calloutlist</sgmltag>.</para>

    <programlisting id="ex-listing">
&lt;example id="sample-catalog"&gt;
  &lt;title&gt;Catalog Sample&lt;/title&gt;
  &lt;programlistingco&gt;
    &lt;areaspec&gt;
      &lt;area coords="1" id="ex.catalogue.comment"&gt;
      &lt;area coords="5" id="ex.catalogue.definition"&gt;
      &lt;area coords="11" id="ex.catalogue.eof"&gt;
    &lt;/areaspec&gt;
        &lt;programlisting&gt;
-- Catalogues for the Conectiva S.A. Style --

OVERRIDE YES
 
PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd" 

DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd"

DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
 
-- EOF -- 
        &lt;/programlisting&gt;
    &lt;calloutlist&gt;
      &lt;callout arearefs="ex.catalogue.comment"&gt;
        &lt;to&gt; Comment. Comments begin with &lt;quote&gt;--&lt;/quote&gt; 
        and follows to the end of the line. &lt;/to&gt; 
      &lt;/callout&gt;
      &lt;callout arearefs="ex.catalogue.definition"&gt;
        &lt;to&gt; The public type association 
           &lt;parameter class="option"&gt;"-//Conectiva SA//DTD books V1.0//EN"&lt;/parameter&gt; 
           with the file &lt;filename&gt;books.dtd&lt;/filename&gt; on the directory
           &lt;filename class="directory"&gt;/home/ldp/estilos&lt;/filename&gt;. &lt;/para&gt; 
      &lt;/callout&gt;
      &lt;callout arearefs="ex.catalogue.eof"&gt;
        &lt;para&gt; Comment informing the end of the file. &lt;/para&gt;
      &lt;/callout&gt;
    &lt;/calloutlist&gt;
  &lt;/programlistingco&gt;
&lt;/example&gt;
    </programlisting>

    <indexterm zone="ex-listing">
      <primary>listings</primary>
      <secondary>inserting</secondary>
      <tertiary>example</tertiary>
    </indexterm>


    <para>The listings can be directly inserted on the document's body without 
    the need of the element <sgmltag class="starttag">example</sgmltag>
    or <sgmltag class="starttag">para</sgmltag>.</para>

    <para>The calling coordinates specifications are done with reference to the
    code line which will be commented.</para>

  </section>

  <section id="tools">
    <title>Tools &amp; Hints</title>

    <para>The process of producing output and generating indexes is
    repetitive and error prone. To make things easier some scripts are
    included here to facilitate this work. Customize and use them at
    will.</para>

    <section id="tools-compile">
      <title>Compiling the sources</title>

    <indexterm>
      <primary>tools</primary>
        <secondary>compiling the sources</secondary>
    </indexterm>

      <para>The script compiles-sgml is a set of grouped commands. As parameters
      the name of the document should be passed
      <glossterm><acronym>SGML</acronym></glossterm> and the output format
      expected.</para> 

      <para>The script version included below supports the formats
      <glossterm><acronym>XML</acronym></glossterm>,
      <glossterm><acronym>HTML</acronym></glossterm>, TeX,
      <glossterm><acronym>RTF</acronym></glossterm>,
      <glossterm>PS</glossterm>, <glossterm>DVI</glossterm> and mirrored PS,
      ideal for the creation of photolithographs.</para>

      <para>The generation of the indices is made automatically by the script
      <filename>collateindex.pl</filename><footnote>
          <para>More information about indexes are available at <ulink
      url="http://nwalsh.com/docbook/dsssl/doc/indexing.html">the page about
      index of Norman Walsh</ulink>.</para> </footnote>, which should be 
      installed in your system. </para>

      <para>Besides the commands below which generate the outputs in different 
      formats, there are other tools from<trademark>Cygnus</trademark> making
      the direct conversion. Such tools can be obtained in <ulink
      url="http://sourceware.cygnus.com/docbook-tools/">here</ulink>.</para>  

      <para>The list below is available <ulink
      url="compiles-sgml">here</ulink>.</para>

      <para>Here is also available a version of <ulink
      url="collateindex.pl"><filename>collateindex.pl</filename></ulink>.</para>

      <example id="listing-compile-sgml">
        <title>Script compiles-sgml</title>
        <programlisting>
&example-compile-sgml;
        </programlisting>
      </example>

      <indexterm>
        <primary>tools</primary>
        <secondary>compiling sources</secondary>
        <tertiary>compile-sgml</tertiary>
      </indexterm>


      <para>Obviously such script can be modified forming a
      <filename>Makefile</filename>, optimizing some functions.</para> 

    </section>

    <section id="toc-articles">
      <title>Inserting a summary on the initial articles page</title>

      <indexterm>
        <primary>tools</primary>
        <secondary>articles</secondary>
        <tertiary>summary</tertiary>
      </indexterm>

      <para>A feature that might be interesting in some cases is the insertion
      of a summary on the initial page of an article. The DocBook articles 
      does not include it as a standard feature.</para>

      <para>To enable this it's necessary to make a modification on
      the stylesheet file used.</para> 

      <para>The example below describes the process and it's use is shown
      in <xref linkend="listing-compile-sgml">.</para>

      <example>
        <title>Stylesheet to insert summaries in articles</title>
        <programlisting>
&dsl-example;
        </programlisting>
      </example>

    </section>

    <section id="automatic-indexes">
      <title>Inserting indexes automatically</title>

      <indexterm>
        <primary>tools</primary>
        <secondary>indexes</secondary>
        <tertiary>automatic generation</tertiary>
        <seealso>edition, index</seealso>
      </indexterm>

      <para>Although DocBook has markups for the composition of indexes, these
      are not generated automatically. The tool <ulink
      url="collateindex.pl">collateindex.pl</ulink> allows the indexes to be 
      generated automatically.</para>

      <para>The way to use this script is described bellow and a practical 
      example can be seen previously in this document (see <xref
      linkend="listing-compile-sgml">).</para> 

      <orderedlist>
        <listitem>
          <para>Process the document with <application>jade</application>
          using the style to <glossterm><acronym>HTML</acronym></glossterm>
          with the option <option>-V html-index</option>.</para>
          <informalexample>
            <screen><prompt>$</prompt> <command>jade</command> <option>-t sgml -d html/docbook.dsl -V html-index document.sgml</option></screen>
          </informalexample>
        </listitem>
        <listitem>
          <para>Generate the document <filename>index.sgml</filename> with  <ulink
          url="collateindex.pl">collateindex.pl</ulink>.</para>
          <informalexample>
            <screen><prompt>$</prompt> <command>perl</command> <option>collateindex.pl -o index.sgml HTML.index</option></screen>
          </informalexample>
        </listitem>
      </orderedlist>

      <para>For the above example to work, it's necessary to define an
      <glossterm>external entity</glossterm> by calling the file
      <filename>index.sgml</filename>.</para> 

      <example id="ex-entity-external-index">
        <title>Configuring an external entity to include the index</title>
         <programlisting>
<sgmltag class="starttag">!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

&lt;!-- Insertion of the index --&gt;
&lt;!entity index SYSTEM "index.sgml"&gt;
]</sgmltag>
        </programlisting>
      </example>
      
      <para>See also <xref linkend="encoding-index"> for information on how to
	  insert necessary information on the text.</para> 

      <note>
        <para>Remember that if you're trying to get Table of Contents
        or Indexes on PS or PDF output you'll need to run <application
        moreinfo="none">jadetex</application> or <application
        moreinfo="none">pdfjadetex</application> at least three
        times. This is a <application
        moreinfo="none">TeX</application> requirement and not a
        DocBook or related application one.</para>
      </note>

    </section>
    
    <section id="tools-writing">
      <title>Making notes on the text while it's being written</title> 
       <indexterm zone="tools-writing">
        <primary>entities</primary>
        <secondary>parameters</secondary>
        <tertiary>usage</tertiary>
      </indexterm>
      
      
      <para>An interesting feature while writing a text is to be able
      to check if such text will be presentable or not on the final
      draft. It's common to have several parts of the text marked as
      drafts, especially when we're updating an already existent
      document.</para> 
      
      <para>DocBook allows along with an entity of parameters to
      include or not the insertions of specific parts of text in
      several places on the document based on the context. Sometimes
      for an upgrading we need to see how the document looks like or
      just have sketches of a new session or chapter, but we don't
      want this sketch to appear on the final draft.</para> 
      
      <para>With the use of parameter entities we can include or eliminate
      these drafts altering only one line at the beginning of a
      document.</para> 
      
      <example id="ex-entity-parameters">
        <title>Use of parameter entities</title>
        <programlisting>
<sgmltag class="starttag">!entity % review "INCLUDE"</sgmltag>
...
<sgmltag class="starttag">![%review;[
&lt;para&gt;This paragrph will be included on the draft when the entity
"review" is defined with the value "INCLUDE". &lt;/para&gt;
]]</sgmltag>
        </programlisting>
      </example>
      
      <indexterm zone="ex-entity-parameters">
        <primary>entities</primary>
        <secondary>parameters</secondary>
        <tertiary>exemple</tertiary>
      </indexterm>

      <para>The entity <literal>review</literal> might have several
      texts defined as in <xref linkend="ex-entity-parameters">. When
      the changes on the text are considered final, it's necessary
      just to remove parts of the text relative to the
      3<superscript>rd.</superscript> and
      6<superscript>th.</superscript> lines.</para>

      <para>To keep the draft definitions and don't show the text on
      the final draft, just alter de specification of the entity from
      <literal>INCLUDE</literal> to <literal>IGNORE</literal>.</para> 

    </section>

    <section id="tools-reuse">
      <title>Re-using parts of documents</title>


      <indexterm zone="tools-reuse">
        <primary>documents</primary>
        <secondary>re-use</secondary>
      </indexterm>

      <para>An important characteristic about the <glossterm>external
      entities</glossterm> is about the re-using issue of text and
      documents.</para>

      <para>With those characteristics it's possible to create files with text
      used several times (e.g. licenses and company policies) and simply
      include those files in the appropriate place.</para>
     
      <para>An example and application of this characteistic was found 
      previously in <xref linkend="ex-entity-external-index">. Another example is
      the <glossterm>SGML</glossterm> code of this HOWTO.</para>  
    </section>

  </section>

  <section id="examples-documents">
    <title>Document samples</title>

    <indexterm zone="examples-documents">
      <primary>edition</primary>
      <secondary>examples</secondary>
    </indexterm>

    <para>As stated before each type of document has a particular heading
    and valid commands structure. The following sub-sections will provide
    heading and valid commands structures on articles and books.</para>
   
    <para>These examples do not cover all possibilities and they are
    available here only with the intention to serve as generic guides for
    what it's possible to do.</para>

    <section id="examples-documents-article">
      <title>Article example</title>

      <indexterm zone="examples-documents-article">
        <primary>edition</primary>
        <secondary>examples</secondary>
        <tertiary>article</tertiary>
      </indexterm>

      <programlisting>
&example-article;
      </programlisting>
    </section>

    <section id="examples-documents-book">
      <title>Book Example</title>

      <indexterm zone="examples-documents-book">
        <primary>edition</primary>
        <secondary>examples</secondary>
        <tertiary>book</tertiary>
      </indexterm>

      <programlisting>
&example-book;
      </programlisting>

    </section>

  </section>

&glossary;

&index;
  
</article>
