mirror of https://github.com/tLDP/LDP
1244 lines
55 KiB
XML
1244 lines
55 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
-->
|
|
|
|
<appendix id="using-docbook">
|
|
<title>DocBook: Sample Markup</title>
|
|
|
|
<section id="writing-docbook">
|
|
<title>General Tips and Tricks</title>
|
|
|
|
<indexterm zone="writing-docbook">
|
|
<primary>edition</primary>
|
|
<secondary>using DocBook</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
For a general overview of what markup is all about, please read <xref
|
|
linkend="ag-markup" />
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>An editor capable of inserting elements according to the
|
|
<acronym>DTD</acronym> will help a lot since it will enforce
|
|
the DTD.
|
|
This way you can be sure that no invalid elements were added
|
|
anywhere in your document.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>In order to ensure that future changes are as easy as possible,
|
|
authors should try to keep compatibility with
|
|
the <acronym>XML</acronym> version of the DocBook DTD. This means
|
|
keeping element names in lower case, using double quotes in all
|
|
attributes, and not omitting end tags. Most tools that
|
|
automatically insert elements (like psgml+emacs) follow these
|
|
rules automatically or with some fine tuning.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Each type of document created has a specific structure. This
|
|
document is in <quote>book</quote> format. Most authors, however, will
|
|
want to use the shorter <quote>article</quote> format instead.
|
|
Templates are available from <xref linkend="templates" />.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="useful-markup">
|
|
<title>Useful markup</title>
|
|
|
|
<indexterm>
|
|
<primary>edition</primary>
|
|
<secondary>using DocBook</secondary>
|
|
<tertiary>markup</tertiary>
|
|
</indexterm>
|
|
|
|
<para><xref linkend="table-useful-markup"/> shows some markup that
|
|
is useful for generating generic documents. Remember that some
|
|
elements are valid only on some contexts.</para>
|
|
|
|
<tip><title>Check several formats</title>
|
|
<para>Sometimes the appearance of a particular tag changes
|
|
from one conversion 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. You are advised to look at how your document is presented in HTML, PDF and PostScript, since these formats will be made available by TLDP once you publish your document.</para>
|
|
</tip>
|
|
|
|
<note><title>Better too much than not enough</title>
|
|
<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-markup">
|
|
<title>Useful markup</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Description</entry>
|
|
<entry>Sample markup</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>Mary<sgmltag class="endtag">firstname</sgmltag>
|
|
<sgmltag class="starttag">othername</sgmltag>Margaret<sgmltag class="endtag">othername</sgmltag>
|
|
<sgmltag class="starttag">surname</sgmltag>O'Hara<sgmltag class="endtag">surname</sgmltag>
|
|
</programlisting></entry>
|
|
<entry><author>
|
|
<firstname>Mary</firstname>
|
|
<othername>Margaret</othername>
|
|
<surname>O'Hara</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>Program Menus</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>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>Text can be emphasized 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
|
|
style sheet 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">para</sgmltag>Footnote text<sgmltag class="endtag">para</sgmltag>
|
|
<sgmltag class="endtag">footnote</sgmltag></programlisting></entry>
|
|
<entry>(See note at the end of this table for an example)</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>Itemized (unnumbered) List</entry>
|
|
<entry><programlisting>
|
|
<sgmltag class="starttag">itemizedlist</sgmltag>
|
|
<sgmltag class="starttag">listitem</sgmltag>
|
|
<sgmltag class="starttag">para</sgmltag>item<sgmltag class="endtag">para</sgmltag>
|
|
<sgmltag class="endtag">listitem</sgmltag>
|
|
<sgmltag class="starttag">listitem</sgmltag>
|
|
<sgmltag class="starttag">para</sgmltag>item<sgmltag class="endtag">para</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>Ordered (numbered) List</entry>
|
|
<entry><programlisting>
|
|
<sgmltag class="starttag">orderedlist</sgmltag>
|
|
<sgmltag class="starttag">listitem</sgmltag>
|
|
<sgmltag class="starttag">para</sgmltag>item<sgmltag class="endtag">para</sgmltag>
|
|
<sgmltag class="endtag">listitem</sgmltag>
|
|
<sgmltag class="starttag">listitem</sgmltag>
|
|
<sgmltag class="starttag">para</sgmltag>item<sgmltag class="endtag">para</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">seglistitem</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">para</sgmltag>Description<sgmltag class="endtag">para</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">para</sgmltag>Description<sgmltag class="endtag">para</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>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">para</sgmltag>Definition<sgmltag class="endtag">para</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">para</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="section">
|
|
<title><sgmltag class="starttag">section</sgmltag> and <sgmltag class="starttag">sectN</sgmltag>: what's the difference?</title>
|
|
|
|
<note><title>Acknowledgment</title><para>
|
|
These notes were provided by:
|
|
<ulink url="http://geekhavoc.com">John Daily</ulink> and
|
|
Saqib Ali (<email>saqib@seagate.com</email>).
|
|
</para></note>
|
|
|
|
<para>
|
|
<sgmltag class="starttag">section</sgmltag> versus <sgmltag class="starttag">sectN</sgmltag> is largely a
|
|
question of flexibility. The stylesheets can make a
|
|
<sgmltag class="starttag">section</sgmltag> in a <sgmltag class="starttag">section</sgmltag> look just
|
|
like a <sgmltag class="starttag">sect2</sgmltag> within a <sgmltag class="starttag">sect1</sgmltag>, so there's no output advantage.
|
|
</para>
|
|
|
|
<para>
|
|
But, a <sgmltag class="starttag">section</sgmltag> within a
|
|
<sgmltag class="starttag">section</sgmltag> can be extracted into its own
|
|
top-level section, nested even more deeply, or moved to an
|
|
entirely different part of the document, without it and its own
|
|
<sgmltag class="starttag">section</sgmltag> children being renamed. That is not true of the
|
|
numbered section tags, which are very sensitive to
|
|
rearrangements. This can be easier for authors who are new to
|
|
DocBook than using <sgmltag class="starttag">sectN</sgmltag>.
|
|
</para>
|
|
|
|
<para>
|
|
The main idea behind creating structured data is that it should be easy
|
|
to access and query. One should be able to retrieve a subsection of any
|
|
structured data, by using querying languages for XML (<application>XPath</application> and <application>XQuery</application>).
|
|
<sgmltag class="starttag">sectN</sgmltag> are useful when traversing a document using <application>XPath</application>/<application>XQuery</application>.
|
|
<sgmltag class="starttag">sectN</sgmltag> gives more flexibility, and control while writing an <application>XPath</application>
|
|
expression.
|
|
</para>
|
|
|
|
<para>
|
|
A well-defined, valid and well-structured document makes it easier for
|
|
one to write <application>XPath</application>/<application>Query</application> to retreive <quote>specific</quote> data from a document.
|
|
For example you can use <application>XPath</application> to retrieve information in the
|
|
<sgmltag class="starttag">sect3</sgmltag> block with certain attributes.
|
|
However if you just used <sgmltag class="starttag">section</sgmltag> for all subsections,
|
|
it becomes harder to retrieve the block of information that you need.
|
|
</para>
|
|
|
|
<para>
|
|
So which one should you use? The one you feel most
|
|
comfortable with is a good place to start. This document
|
|
is written with <sgmltag class="starttag">section</sgmltag>s. You may,
|
|
or may not, think this is a good idea. :)
|
|
</para>
|
|
|
|
</section> <!-- section and sectN -->
|
|
|
|
<section id="commandprompt">
|
|
<title>Command Prompts</title>
|
|
<para>
|
|
There are likely as many ways of doing this as there are DocBook
|
|
authors; however, here are two ways that you might find useful.
|
|
Thanks to <ulink url="http://www.appaji.net/">Y Giridhar Appaji Nag</ulink>
|
|
and
|
|
<ulink url="http://linux-ip.net/">Martin Brown</ulink>
|
|
for the markup used here.
|
|
</para>
|
|
<example id="ex-programlisting">
|
|
<title>Command Prompt with <sgmltag>programlisting</sgmltag></title>
|
|
<screen>
|
|
<sgmltag class="starttag">programlisting</sgmltag>
|
|
<sgmltag class="starttag">prompt</sgmltag># <sgmltag class="endtag">prompt</sgmltag><sgmltag class="starttag">userinput</sgmltag><sgmltag class="starttag">command</sgmltag>cd<sgmltag class="endtag">command</sgmltag> /some/dir<sgmltag class="endtag">userinput</sgmltag>
|
|
<sgmltag class="starttag">prompt</sgmltag># <sgmltag class="endtag">prompt</sgmltag><sgmltag class="starttag">userinput</sgmltag><sgmltag class="starttag">command</sgmltag>ls<sgmltag class="endtag">command</sgmltag> -l<sgmltag class="endtag">userinput</sgmltag>
|
|
<sgmltag class="endtag">programlisting</sgmltag>
|
|
</screen>
|
|
|
|
<para>Displays as:</para>
|
|
|
|
<programlisting>
|
|
<prompt># </prompt><userinput><command>cd</command> /some/dir</userinput>
|
|
<prompt># </prompt><userinput><command>ls</command> -l</userinput>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example id="ex-screen">
|
|
<title>Command Prompt with <sgmltag>screen</sgmltag></title>
|
|
<para>
|
|
First create a general entity in the internal subset at the very
|
|
beginning of your document. This entity will define a name for the
|
|
shortcut which you can use to display the full prompt at any point
|
|
in your document.
|
|
<literal><!ENTITY prompt "<prompt>[user@machine
|
|
~/dir]$</prompt>"></literal>
|
|
</para>
|
|
|
|
<para>
|
|
For more information about entities, read <xref
|
|
linkend="tools-entities" />.
|
|
</para>
|
|
|
|
<screen>
|
|
<sgmltag class="starttag">screen</sgmltag>
|
|
&prompt; <sgmltag class="starttag">userinput</sgmltag>cd /some/dir<sgmltag class="endtag">userinput</sgmltag>
|
|
&prompt; <sgmltag class="starttag">userinput</sgmltag>ls -l<sgmltag class="endtag">userinput</sgmltag> <sgmltag class="endtag">screen</sgmltag>
|
|
</screen>
|
|
|
|
<para>Displays as:</para>
|
|
|
|
<screen>
|
|
<prompt>[user@machine ~/dir]$ </prompt><userinput>cd /some/dir</userinput>
|
|
<prompt>[user@machine ~/dir]$ </prompt><userinput>ls -l</userinput>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>
|
|
If you would like to add the output of your commands you can add
|
|
<sgmltag class="starttag">computeroutput</sgmltag> text<sgmltag
|
|
class="endtag">computeroutput</sgmltag> within the
|
|
<sgmltag class="starttag">screen</sgmltag> or <sgmltag class="starttag">programlisting</sgmltag>
|
|
as appropriate.
|
|
</para>
|
|
</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="automatic-indexes"/>). 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 is 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 attribute <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 id="ex-index">
|
|
<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 is necessary to insert pictures formats for all possible
|
|
finished document types. For example: JPG files for web pages and EPS
|
|
for PostScript and PDF files.</para>
|
|
|
|
<para>If you use the TeX format you'll need the images as
|
|
a PostScript file. For on-line 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 to use the <sgmltag
|
|
class="attribute">fileref</sgmltag> attribute. 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 tag 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, or it can be controlled by the application).</para>
|
|
|
|
<section id="acceptedgfx">
|
|
<title>Graphics formats</title> <para> When
|
|
submitting graphics to the LDP, please submit one
|
|
set of graphics in <filename>.eps</filename>, and
|
|
another in <filename moreinfo="none">.gif</filename>,
|
|
<filename moreinfo="none">.jpg</filename> or <filename
|
|
moreinfo="none"> .png</filename>. The preferred format is
|
|
<filename moreinfo="none"> .png</filename> or <filename
|
|
moreinfo="none">.jpg</filename> due to patent problems with
|
|
<filename moreinfo="none">.gif</filename>. </para> <para>
|
|
You can use <filename moreinfo="none">.jpg</filename> files for
|
|
continuous-tone images such as photos or images with gradual
|
|
changes in color. Use <filename moreinfo="none">.png</filename>
|
|
for simple images like diagrams, some screen shots, and images
|
|
with a low number of colors. </para>
|
|
</section>
|
|
|
|
<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 to eliminate the <sgmltag class="starttag">figure</sgmltag> or
|
|
<sgmltag class="starttag">informalfigure</sgmltag> elements.</para>
|
|
|
|
<para>Another interesting alternative when you have
|
|
decided to publish the text on media where pictures
|
|
are not 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 using 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. If the output format does not
|
|
support images the <sgmltag class="starttag">textobject</sgmltag>
|
|
element will be used. However, the biggest advantage in usage
|
|
of the format <xref linkend="former-figure-imageobject"/>
|
|
is that in DocBook <literal>5.0</literal>, the <sgmltag
|
|
class="starttag">graphic</sgmltag> element will cease to
|
|
exist.</para>
|
|
|
|
<para>As a disadvantage, there is the need for more than one
|
|
representation code of the same information. It is up to the
|
|
author to decide how they will implement illustrations and
|
|
pictures in the document, but for compatibility with future
|
|
versions <emphasis>I recommend</emphasis> the use of this method
|
|
for pictures and graphics.</para>
|
|
|
|
<warning><title>Title page exception</title><para>
|
|
<sgmltag class="starttag">mediaobject</sgmltag>s will not display if they are
|
|
used on a title page. For more information read:
|
|
<ulink
|
|
url="http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage"
|
|
/>
|
|
</para></warning>
|
|
|
|
<note><title>ASCII Images</title><para>
|
|
You may also want to try converting your image to an ASCII
|
|
representation of the file. <application>JavE</application>
|
|
(Java ASCII Versatile Editor) can do this conversion for you.
|
|
It can be downloaded from <ulink url="http://www.jave.de/"
|
|
/>. It has an easy to use GUI interface.
|
|
</para>
|
|
|
|
<para>
|
|
If you're more command-line oriented you may want to try:
|
|
<application>tgif</application>
|
|
(<ulink url="http://bourbon.usc.edu:8001/tgif/" />) and
|
|
AA-Lib (<ulink url="http://aa-project.sourceforge.net/" />).
|
|
</para></note>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="metadata-markup"> <title>Markup for Metadata</title>
|
|
|
|
<section id="crediting">
|
|
<title>Crediting Translators, Converters and Co-authors</title>
|
|
|
|
<para>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><sgmltag
|
|
class="starttag">othercredit</sgmltag></title>
|
|
|
|
<para>All translators, converters and co-authors
|
|
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>role</sgmltag>
|
|
attribute set to <quote>converter</quote> or
|
|
<quote>translator</quote>,
|
|
as indicated in the example below:</para>
|
|
|
|
<example id="ex-othercredit">
|
|
<title>Other Credit</title>
|
|
<screen>
|
|
<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>
|
|
</screen>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="crediting-editors">
|
|
<title>Crediting Editors and Reviewers</title>
|
|
<para>
|
|
To help track the review process all new documents must include a
|
|
reference to the reviewers for the <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html">technical</ulink>,
|
|
<ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/languagereview.html">language</ulink>
|
|
and <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/metadatareview.html">metadata</ulink>
|
|
reviews.
|
|
</para>
|
|
|
|
<example id="ex-editor">
|
|
<title>Editor</title>
|
|
<screen>
|
|
<sgmltag class="starttag">editor</sgmltag>
|
|
<sgmltag class="starttag">firstname</sgmltag>Tabatha<sgmltag class="endtag">firstname</sgmltag>
|
|
<sgmltag class="starttag">surname</sgmltag>Marshall<sgmltag class="endtag">surname</sgmltag>
|
|
<sgmltag class="starttag">contrib</sgmltag>Language review of version 0.8<sgmltag class="endtag">contrib</sgmltag>
|
|
<sgmltag class="endtag">editor</sgmltag>
|
|
</screen>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="crediting-version">
|
|
<title><sgmltag class="starttag">revremark</sgmltag>s</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.</para>
|
|
</section>
|
|
|
|
<section id="acceptedrev">
|
|
<title> Revision History </title> <para> The <sgmltag
|
|
class="starttag">revhistory</sgmltag> tag should be used to denote
|
|
the various revisions of the document. Specify the date, revision
|
|
number and comments regarding what has changed.</para> <para>
|
|
Revisions should be listed with the most-recent version at the
|
|
top (list in descending order).
|
|
</para>
|
|
</section>
|
|
|
|
<section id="accepteddates">
|
|
<title> Date formats </title> <para> The <sgmltag
|
|
class="starttag">pubdate</sgmltag> tag in your header should list
|
|
the publication date of this particular version of the document
|
|
(coincide with the revision date). It should be in the following
|
|
format: </para> <programlisting format="linespecific"><sgmltag
|
|
class="starttag">pubdate</sgmltag>2002-04-25<sgmltag
|
|
class="endtag">pubdate</sgmltag></programlisting>
|
|
<para>
|
|
The date is in the format YYYY-MM-DD, which is one of the <ulink
|
|
url="http://www.w3.org/TR/NOTE-datetime">ISO 8601</ulink>
|
|
standard formats for representing dates. For you Yanks out
|
|
there (me too), think of it as going from the largest unit of
|
|
time to the smallest.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="sampleai">
|
|
<title> Sample Article (or Book) Information Element </title>
|
|
<para> Here is a sample of a complete DocBook (SGML or XML)
|
|
<sgmltag class="starttag">articleinfo</sgmltag> element
|
|
which contains some of the items and constructs previously
|
|
described. </para>
|
|
|
|
<example id="sample-metadata">
|
|
<title>Sample Meta Data</title>
|
|
<programlisting>
|
|
<![CDATA[<!--
|
|
Above these lines in a typical DocBook article would be the article
|
|
element (the immediate parent of the articleinfo element) and above
|
|
that typically, the DOCTYPE declaration and internal subset.
|
|
-->]]>
|
|
|
|
<sgmltag class="starttag">articleinfo</sgmltag>
|
|
|
|
<!--
|
|
Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate
|
|
-->
|
|
|
|
<sgmltag class="starttag">title</sgmltag>Sample HOWTO<sgmltag class="endtag">title</sgmltag>
|
|
|
|
<sgmltag class="starttag">author</sgmltag>
|
|
<sgmltag class="starttag">firstname</sgmltag>Your Firstname<sgmltag class="endtag">firstname</sgmltag>
|
|
<sgmltag class="starttag">surname</sgmltag>Your Surname<sgmltag class="endtag">surname</sgmltag>
|
|
<sgmltag class="starttag">affiliation</sgmltag>
|
|
<sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag>your email<sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag>
|
|
<sgmltag class="endtag">affiliation</sgmltag>
|
|
<sgmltag class="endtag">author</sgmltag>
|
|
|
|
<sgmltag class="starttag">editor</sgmltag>
|
|
<sgmltag class="starttag">firstname</sgmltag>Tabatha<sgmltag class="endtag">firstname</sgmltag>
|
|
<sgmltag class="starttag">surname</sgmltag>Marshall<sgmltag class="endtag">surname</sgmltag>
|
|
<sgmltag class="starttag">contrib</sgmltag>Language review of version 0.8<sgmltag class="endtag">contrib</sgmltag>
|
|
<sgmltag class="endtag">editor</sgmltag>
|
|
|
|
<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>
|
|
|
|
<sgmltag class="starttag">pubdate</sgmltag>YYYY-MM-DD<sgmltag class="endtag">pubdate</sgmltag>
|
|
|
|
<sgmltag class="starttag">revhistory</sgmltag>
|
|
<sgmltag class="starttag">revision</sgmltag>
|
|
<sgmltag class="starttag">revnumber</sgmltag>1.0<sgmltag class="endtag">revnumber</sgmltag>
|
|
<sgmltag class="starttag">date</sgmltag>YYYY-MM-DD<sgmltag class="endtag">date</sgmltag>
|
|
<sgmltag class="starttag">authorinitials</sgmltag>ABC<sgmltag class="endtag">authorinitials</sgmltag>
|
|
<sgmltag class="endtag">revremark</sgmltag>first official release<sgmltag class="endtag">revremark</sgmltag>
|
|
<sgmltag class="endtag">revision</sgmltag>
|
|
|
|
<sgmltag class="starttag">revision</sgmltag>
|
|
<sgmltag class="starttag">revnumber</sgmltag>0.9<sgmltag class="endtag">revnumber</sgmltag>
|
|
<sgmltag class="starttag">date</sgmltag>YYYY-MM-DD<sgmltag class="endtag">date</sgmltag>
|
|
<sgmltag class="starttag">authorinitials</sgmltag>ABC<sgmltag class="endtag">authorinitials</sgmltag>
|
|
<sgmltag class="starttag">revremark</sgmltag>First draft<sgmltag class="endtag">revremark</sgmltag>
|
|
<sgmltag class="endtag">revision</sgmltag>
|
|
<sgmltag class="endtag">revhistory</sgmltag>
|
|
|
|
<!--
|
|
Provide a good abstract; a couple of sentences is sufficient
|
|
-->
|
|
|
|
<sgmltag class="starttag">abstract</sgmltag>
|
|
<sgmltag class="starttag">para</sgmltag>
|
|
This is a sample DocBook (SGML or XML) HOWTO which has been
|
|
constructed to serve as a template.
|
|
<sgmltag class="endtag">para</sgmltag>
|
|
<sgmltag class="endtag">abstract</sgmltag>
|
|
|
|
<sgmltag class="endtag">articleinfo</sgmltag>
|
|
</programlisting>
|
|
</example>
|
|
|
|
</section>
|
|
</section> <!-- end of metadata-markup -->
|
|
|
|
<section id="doc-bib">
|
|
<title>Bibliographies</title>
|
|
<para>
|
|
Not everyone will choose to use the correct formatting for a
|
|
bibliography. Most will use a list of some kind. And that's ok. But
|
|
when you're ready to move to the next level, here's how to do it.
|
|
</para>
|
|
|
|
<para>
|
|
Below are two examples of bibliographic entries. The first is a very
|
|
simple entry. It has only a title, URL and possibly a short
|
|
description (abstract). The second is a little more complex and is
|
|
for a full entry (for instance a book) with an ISBN, publisher and copyright
|
|
date.
|
|
</para>
|
|
|
|
<note><title>DocBook requirements for bibliographic references</title>
|
|
<para>
|
|
At least one element within <sgmltag class="starttag">biblioentry</sgmltag> is
|
|
required, but it doesn't matter which one you have. So you might
|
|
have a <sgmltag class="starttag">title</sgmltag>, or a URL (<sgmltag class="starttag">bibliosource</sgmltag>), or an
|
|
<sgmltag class="starttag">author</sgmltag>, or, ...
|
|
</para>
|
|
<para>
|
|
For a full list of all options, visit <ulink
|
|
url="http://docbook.org/tdg/en/html/biblioentry.html" />. For
|
|
more examples visit <ulink
|
|
url="http://docbook.org/tdg/en/html/bibliography.html" />.
|
|
</para>
|
|
</note>
|
|
|
|
<caution><title>Displaying <sgmltag class="starttag">abstract</sgmltag> content</title>
|
|
<para>
|
|
By default <sgmltag class="starttag">abstract</sgmltag>s do not display on web
|
|
pages. You need to modify the <filename>biblio.xsl</filename> file.
|
|
Do a search for the word <quote>abstract</quote> and then add
|
|
this information inside the <xsl:template> tags. If that
|
|
doesn't make sense, don't worry about it too much, but do be
|
|
aware that it's required for the abstracts to show up.
|
|
<!-- it is not automatic, you must change the biblio.xsl file.
|
|
-->
|
|
</para>
|
|
|
|
<screen>
|
|
<div xmlns="http://www.w3.org/1999/xhtml" class="{name(.)}">
|
|
<xsl:apply-templates mode="bibliography.mode"/>
|
|
</div>
|
|
</screen>
|
|
</caution>
|
|
|
|
<example id="ex-bib">
|
|
<title>A Bibliography</title>
|
|
<screen>
|
|
<sgmltag class="starttag">bibliography</sgmltag>
|
|
<sgmltag class="starttag">title</sgmltag>Bibliography title<sgmltag class="endtag">title</sgmltag>
|
|
|
|
<sgmltag class="starttag">bibliodiv</sgmltag>
|
|
<sgmltag class="starttag">title</sgmltag>Section title<sgmltag class="endtag">title</sgmltag>
|
|
<sgmltag class="starttag">biblioentry</sgmltag>
|
|
<sgmltag class="starttag">title</sgmltag>Book or Web Site Title<sgmltag class="endtag">title</sgmltag>
|
|
<sgmltag class="starttag">bibliosource</sgmltag><sgmltag class="emptytag">ulink url=""</sgmltag><sgmltag class="endtag">bibliosource</sgmltag>
|
|
<sgmltag class="starttag">abstract</sgmltag><sgmltag class="endtag">abstract</sgmltag>
|
|
<sgmltag class="endtag">biblioentry</sgmltag>
|
|
|
|
<sgmltag class="starttag">biblioentry</sgmltag>
|
|
<sgmltag class="starttag">title</sgmltag><sgmltag class="endtag">title</sgmltag>
|
|
<sgmltag class="starttag">bibliosource</sgmltag><sgmltag class="emptytag">ulink url=""</sgmltag><sgmltag class="endtag">bibliosource</sgmltag>
|
|
<sgmltag class="starttag">author</sgmltag><sgmltag class="starttag">firstname</sgmltag><sgmltag class="endtag">firstname</sgmltag><sgmltag class="starttag">surname</sgmltag><sgmltag class="endtag">surname</sgmltag><sgmltag class="endtag">author</sgmltag>
|
|
<sgmltag class="starttag">copyright</sgmltag><sgmltag class="starttag">year</sgmltag><sgmltag class="endtag">year</sgmltag>
|
|
<sgmltag class="starttag">holder</sgmltag><sgmltag class="endtag">holder</sgmltag><sgmltag class="endtag">copyright</sgmltag>
|
|
<sgmltag class="starttag">editor</sgmltag><sgmltag class="starttag">firstname</sgmltag><sgmltag class="endtag">firstname</sgmltag><sgmltag class="starttag">surname</sgmltag><sgmltag class="endtag">surname</sgmltag><sgmltag class="endtag">editor</sgmltag>
|
|
<sgmltag class="starttag">isbn</sgmltag><sgmltag class="endtag">isbn</sgmltag>
|
|
<sgmltag class="starttag">publisher</sgmltag>
|
|
<sgmltag class="starttag">publishername</sgmltag><sgmltag class="endtag">publishername</sgmltag>
|
|
<sgmltag class="endtag">publisher</sgmltag>
|
|
<sgmltag class="starttag">abstract</sgmltag><sgmltag class="endtag">abstract</sgmltag>
|
|
<sgmltag class="endtag">biblioentry</sgmltag>
|
|
<sgmltag class="endtag">bibliodiv</sgmltag>
|
|
<sgmltag class="endtag">bibliography</sgmltag>
|
|
</screen>
|
|
|
|
<para>
|
|
View <xref linkend="bibliography" /> to see this in action.
|
|
</para>
|
|
|
|
</example>
|
|
</section>
|
|
|
|
<section id="tools-entities"> <title>Entities (shortcuts,
|
|
text macros and re-usable text)</title>
|
|
|
|
<indexterm zone="tools-writing">
|
|
<primary>entities</primary> <secondary>parameters</secondary>
|
|
<tertiary>usage</tertiary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
There may be some segments of text, or markup
|
|
that you want to use over and over again. Instead
|
|
of typing it up multiple times (and then having
|
|
to edit it multiple times if you want to make
|
|
a change) you can use <glossterm>external
|
|
entities</glossterm>. Entities can give you a short
|
|
cut to:
|
|
re-using whole documents, text snippets, and
|
|
special markup. Some common ways to use an
|
|
entity would be for:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><formalpara> <title>text macros
|
|
for markup</title> <para>An example would be a company
|
|
URL. By using a parameter entity you
|
|
could refer simply to &my-company-url;
|
|
instead of typing out the full <ulink
|
|
url="http://foo.bar">Foo.bar</ulink>
|
|
each time. </para> </formalpara></listitem>
|
|
|
|
<listitem><formalpara> <title>software
|
|
license</title> <para>Such as the GNU Free
|
|
Documentation License: it is long. And must
|
|
be included in full in each document. By
|
|
leaving the license in a separate file you can
|
|
easily include it in many documents without
|
|
having to redo the markup each time. </para>
|
|
</formalpara></listitem>
|
|
|
|
<listitem><formalpara> <title>repeated
|
|
text</title> <para>For instance an introduction to a
|
|
topic which is included both as a summary in
|
|
one section and as an introduction to the full
|
|
information in another. Saves on editing time if
|
|
you need to make changes to both sets of text.
|
|
</para> </formalpara> </listitem>
|
|
</itemizedlist>
|
|
|
|
<example id="ex-entities"> <title>Adding
|
|
Entities</title> <screen>
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
|
<-- I can add comments here -->
|
|
<!ENTITY shortcut "Replace 'shortcut' with this text.">
|
|
|
|
<!ENTITY sc-to-a-file SYSTEM "anotherfile.xml">
|
|
<-- note: the square bracket on the third line is closed on the next
|
|
line--> ]>
|
|
</screen> </example>
|
|
|
|
<para>
|
|
To use these entities simply insert the name
|
|
you gave the entity between a <quote>&</quote> (ampersand) and a <quote>;</quote> (semicolon). For
|
|
example: <quote>&shortcut;</quote> would expand into <quote>Replace
|
|
'shortcut' with this text</quote>; <quote>&sc-to-a-file;</quote>
|
|
would include the full contents of whatever
|
|
is in <replaceable>anotherfile.xml</replaceable>.
|
|
</para>
|
|
|
|
<para>An important feature while writing a text is the ability to
|
|
check whether or not it will be presented in the final draft. It is
|
|
common to have several parts of the text marked as draft,
|
|
especially when updating an already existing document.</para>
|
|
|
|
<para>With the use of parameter entities, you can include or
|
|
eliminate these drafts by 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 paragraph 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>example</tertiary>
|
|
</indexterm>
|
|
|
|
<para>The entity <literal>review</literal> might have several texts
|
|
defined, as in <xref linkend="ex-entity-parameters"/>. When the
|
|
changes to the text are considered final, you need only to remove
|
|
parts of the text between the 3<superscript>rd.</superscript>
|
|
and 6<superscript>th.</superscript> lines.</para>
|
|
|
|
<para>To keep the draft definitions and hide the text in the
|
|
final draft, just alter the specification of the entity from
|
|
<literal>INCLUDE</literal> to <literal>IGNORE</literal>.</para>
|
|
</section>
|
|
|
|
<section id="namedfiles">
|
|
<title>Customizing your HTML files</title>
|
|
|
|
<section id="filenames">
|
|
<title>HTML file names</title>
|
|
<para>By default,
|
|
when separate HTML files are made, the SGML processor will assign
|
|
arbitrary names to the resulting files. This can be confusing
|
|
to readers who may bookmark a page only to have it change.
|
|
Whatever your reasoning, here's how to make separate files
|
|
named the way you want:</para> <para>In your first <sgmltag
|
|
class="starttag">article</sgmltag> tag (which should be the only
|
|
one) include an <parameter>id</parameter> parameter and call it <quote>index</quote>. This will make
|
|
your tag look like this:</para>
|
|
|
|
<programlisting format="linespecific">
|
|
<sgmltag class="starttag">article id="index"</sgmltag> </programlisting>
|
|
|
|
<para>Do not modify the first
|
|
<sgmltag class="starttag">chapter</sgmltag>
|
|
tag, as it's usually an introduction and you want that on the first
|
|
page. For each other <sgmltag class="starttag">section</sgmltag>
|
|
tag, include the id parameter and name it. A name should include
|
|
only alphanumeric characters, and it should be short enough to
|
|
understand what it is.</para>
|
|
|
|
<programlisting format="linespecific">
|
|
<sgmltag class="starttag">chapter id="tips"</sgmltag>
|
|
</programlisting>
|
|
|
|
<note><title>Pick section IDs intelligently</title><para>
|
|
We all know that <ulink
|
|
url="http://www.w3.org/Provider/Style/URI.html">Cool URIs Don't
|
|
Change</ulink>. This means your ids should not change either. Unless of
|
|
course the content for the id has changed substantially and the id name is no longer
|
|
relevant.
|
|
</para></note>
|
|
|
|
<warning><title>HTML file name generation using Jade</title><para>
|
|
If you are using <application>Jade</application> to transform
|
|
your DocBook into HTML you must use the following parameter:
|
|
<parameter>-V %use-id-as-filename%</parameter>.
|
|
</para></warning>
|
|
</section>
|
|
|
|
<section id="header">
|
|
<title>Headers and Footers</title>
|
|
<para>
|
|
There is no <quote>easy</quote> way to add headers and
|
|
footers to your document. If you are using DocBook XSL and
|
|
doing your own document transformations you
|
|
may customize the XSL template to suit your needs. For more
|
|
information read <ulink
|
|
url="http://www.sagehill.net/docbookxsl/HTMLHeaders.html" />.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</appendix>
|