mirror of https://github.com/tLDP/LDP
1491 lines
61 KiB
Plaintext
1491 lines
61 KiB
Plaintext
<chapter id="usingdocbooktags">
|
|
<title>Using DocBook Tags</title>
|
|
|
|
<section id="docbookintro">
|
|
<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.TEST</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>
|
|
|
|
<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="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 may 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>Save<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>File<sgmltag class="endtag">guimenu</sgmltag>
|
|
<sgmltag class="starttag">guimenuitem</sgmltag>Save<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">
|
|
<example id="sample-catalog">
|
|
<title>Catalog Sample</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>
|
|
-- 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 --
|
|
</programlisting>
|
|
<calloutlist>
|
|
<callout arearefs="ex.catalogue.comment">
|
|
<to> Comment. Comments begin with <quote>--</quote>
|
|
and follows to the end of the line. </to>
|
|
</callout>
|
|
<callout arearefs="ex.catalogue.definition">
|
|
<to> 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/estilos</filename>. </para>
|
|
</callout>
|
|
<callout arearefs="ex.catalogue.eof">
|
|
<para> Comment informing the end of the file. </para>
|
|
</callout>
|
|
</calloutlist>
|
|
</programlistingco>
|
|
</example>
|
|
</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="crediting">
|
|
<title>Crediting Translators and Converters</title>
|
|
|
|
<para>When someone else assists in the production of an LDP document,
|
|
you should give them proper attribution, and there are DocBook tags
|
|
designed to do this. This section will show you the tags you should
|
|
use, as well as other ways of giving credit where credit is due.
|
|
Crediting editors is easy - there is already an
|
|
<sgmltag class="starttag">editor</sgmltag>tag in DocBook.
|
|
But there are two special cases where you need to credit someone,
|
|
but DocBook doesn't provide a special tag. These are <emphasis>translators</emphasis>
|
|
and <emphasis>converters</emphasis>.</para>
|
|
|
|
<para>A <emphasis>converter</emphasis> is someone
|
|
who performs a source code conversion, e.g., from HTML to DocBook SGML.
|
|
Source code conversions help the LDP achieve long term goals for meta-data,
|
|
and allow us to produce documentation in many different output formats.</para>
|
|
|
|
<para>Translators take your original document and translate it into other
|
|
human-readable languages, e.g., from English to Japanese, or from German
|
|
to English. Each translation allows many more people all over the world
|
|
to make use of your document, and helps Linux achieve the ultimate goal -
|
|
Total World Domination(tm)!</para>
|
|
|
|
<para>As you will see in the following
|
|
sections, there are several ways that these folks, as well as other
|
|
contributors to your document, can be given some recognition for the
|
|
help they've given you.</para>
|
|
|
|
<section id="crediting-othercredit">
|
|
<title>The <sgmltag class="starttag">othercredit</sgmltag> Tag</title>
|
|
|
|
<para>All translators and converters should be credited with an
|
|
<sgmltag class="starttag">othercredit</sgmltag> tag entry.
|
|
To properly credit a translator or converter, use the
|
|
<sgmltag class="starttag">othercredit</sgmltag> tag with the <sgmltag class="starttag">role</sgmltag>
|
|
attribute set to <quote>converter</quote> or <quote>translator</quote>,
|
|
as indicated in the example below:</para>
|
|
|
|
<programlisting>
|
|
<sgmltag class="starttag">othercredit role='converter'</sgmltag>
|
|
<sgmltag class="starttag">firstname</sgmltag>David<sgmltag class="endtag">firstname</sgmltag>
|
|
<sgmltag class="starttag">surname</sgmltag>Merrill<sgmltag class="endtag">surname</sgmltag>
|
|
<sgmltag class="starttag">contrib</sgmltag>Conversion from HTML to DocBook v3.1 (SGML).<sgmltag class="endtag">contrib</sgmltag>
|
|
<sgmltag class="endtag">othercredit</sgmltag></programlisting>
|
|
</section>
|
|
|
|
<section id="crediting-ack">
|
|
<title>The <quote>Acknowledgements</quote> section</title>
|
|
|
|
<para>Your document should have a section titled <quote>Acknowledgements</quote>,
|
|
in which you mention everyone who has contributed to your document in
|
|
any meaningful way. You should include translators and converters, as well as
|
|
people who have sent you lots of good feedback, perhaps the person who taught
|
|
you the knowledge you are now passing on, and anybody else who was instrumental
|
|
in making the document what it is. Most authors put this section at the end
|
|
of their document.</para>
|
|
</section>
|
|
|
|
<section id="crediting-version">
|
|
<title>The <sgmltag class="starttag">revremark</sgmltag> tag</title>
|
|
|
|
<para>Within the <sgmltag class="starttag">revision</sgmltag> tag hierarchy is
|
|
a tag called <sgmltag class="starttag">revremark</sgmltag>. Within this tag,
|
|
you can make any brief notes you wish about each particular revision of your
|
|
document. We recommend that you acknowledge converters in the comment for the
|
|
initial version released in the new format, and we recommend that you credit
|
|
translators in each version which they have translated.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="tools-hints">
|
|
<title>Tools & 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" [
|
|
|
|
<!-- Insertion of the index -->
|
|
<!entity index SYSTEM "index.sgml">
|
|
]</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;[
|
|
<para>This paragrph will be included on the draft when the entity
|
|
"review" is defined with the value "INCLUDE". </para>
|
|
]]</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 the 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>
|
|
</chapter>
|