readme-dblite.html [plain text]
<html>
<head>
<title>Using DocBook Lite</title>
<style>
body {
background-color: wheat;
font-family: sans-serif;
}
.section {
margin: 0.5em;
padding: 0.5em;
background-color: wheat;
}
.contents {
margin: 0.5em;
padding: 0.5em;
background-color: silver;
}
</style>
</head>
<body>
<h1 class="doctitle">Using DocBook Lite</h1>
<div class="contents">
<h2 class="ctitle">Contents</h2>
<a href="#section-1">1. Introduction</a>
<br>
<a href="#section-2">2. XML</a>
<br>
<a href="#section-3">3. For best results...</a>
<br>
<a href="#section-4">4. The Physical Structure of a Book</a>
<br>
<a href="#section-5">5. The Logical Structure of a Book</a>
<br>
<a href="#section-6">6. Block elements</a>
<br>
<a href="#section-7">7. Inline elements</a>
<br>
<a href="#section-8">8. Tables</a>
<br>
<a href="#section-9">9. Indexterms</a>
<br>
<a href="#section-10">10. Out-of-flow Text</a>
<br>
<a href="#section-11">11. Reference Pages</a>
<br>
<a href="#section-12">12. See Also...</a>
<br>
</div>
<a name="section-1"></a>
<div class="section">
<h2 class="stitle">1. Introduction</h2>
<p>
This document describes the use of DocBook Lite, a document type
definition (DTD) that defines and shapes the markup of O'Reilly
books. The DTD declares a set of elements (containers of content) and
entities (stand-ins for content). Its notation restricts the kinds of
elements and data that each element can hold. For example, a
<tt><chapter></tt> can contain a
<tt><para></tt> (paragraph), but cannot contain a
<tt><book></tt>.
</p>
<p>
DocBook Lite is an application of the XML markup language rules. XML
doesn't require that you use a DTD, but we find that enforcing
structure is vital to our ability to produce and repurpose books
efficiently. Originally, we used the full DocBook application
maintained by <a href="http://www.oasis-open.org/">the OASIS
SGML/XML standards group</a>, but have since refined it to a small
subset with its own DTD. It has a few additions for some types of
books, but mostly the markup should be compatible with the full
DocBook.
</p>
</div>
<a name="section-2"></a>
<div class="section">
<h2 class="stitle">2. XML</h2>
<p>
The eXtensible Markup Language (XML) is a
specification for how markup should work in a document. Using codes
embedded in text, it defines structure and properties for the parts of
a document. The basic philosophy of XML is that every unique part of a
document should be clearly labelled and its position should be
unambiguous. If a document satisfies the minimal rules of XML, it is
said to be well-formed. A document that is not
well-formed has syntax or other kinds of errors that need to be fixed
before the document can be processed.
</p>
<p>
The rules for a well-formed XML document differ from those of
HTML pages. HTML is less strict with syntax, and most browser will not
complain about poor style or errors. However, XML is much less
forgiving, so be warned.
</p>
<p>
DocBook Lite adds another level of control to the document. It
restricts the kinds of elements and structures that make up a
book. Specially tailored to O'Reilly's style, the DTD ensures that the
book has maximum quality and information value by the time it reaches
production. A document that conforms to our DTD is described as
valid. A document that is not valid has
incorrect markup that needs to be fixed before it can be accurately
processed by our tools.
</p>
<p>
To test the validity of a document, you need to use a program called a
validator. Sometimes this is built-in to the
text editor you're using. For example, Arbortext's Adept editor has a
validation option. Other editors may not include a validating parser
because it's assumed that any document you open is already valid, and
you won't make any mistakes because the editor won't let you (it
constrains your actions). There are also stand-alone validators that
read a document and list errors for you. We use nsgmls to validate
books.
</p>
<p>
<tt>nsgmls</tt> is written and maintained by James Clark
and is available for free from <a href="http://www.jclark.com/sp/nsgmls.htm">his web page</a>.
</p>
</div>
<a name="section-3"></a>
<div class="section">
<h2 class="stitle">3. For best results...</h2>
<p>
Just because you're using XML doesn't mean the document is marked up
as well as it can be. Even a valid document can have mistakes and
problems that lower the quality of the book and slow down
production. For example, you may use the wrong element name, which
will pass the DTD test but not make sense to a human. The following
code fragment shows the correct markup for a term-definition
list:
</p>
<div class="programlisting">
<pre><variablelist>
<varlistentry>
<term>monkey</term>
<listitem><para>A cute, furry mammal that climbs in trees.</para></listitem>
</varlistentry>
<varlistentry>
<term>koala</term>
<listitem><para>A cute, furry mammal that climbs in trees.</para></listitem>
</varlistentry>
</variablelist></pre>
</div>
<p>
Sometimes, people choose to do this with another kind of list:
</p>
<div class="programlisting">
<pre><itemizedlist>
<listitem><para>Monkey - A cute, furry mammal that climbs in trees.</para></listitem>
<listitem><para>Koala - A cute, furry mammal that climbs in trees.</para></listitem>
</itemizedlist></pre>
</div>
<p>
It's easier to type it the second way, but then you lose some
information, like the fact that it's supposed to be a mapping of terms
to definitions. Although you may think you're saving time with this
shortcut, it will add delays later when production staff have to
transform the list into its proper markup.
</p>
<p>
Another common mistake authors make is to assume that
presentational markup is just as good as
semantic markup. In other words, saying how
something looks is as good as saying what it is. This is contrary to
the philosophy of XML, and also will cause problems for your book
later on. For example, consider the inline markup for a Web address,
or URL. In print, a URL appears in italic like this:
</p>
<p>
For more information, you <em>really</em> ought to
check out the W3C's website at
<em>http://www.w3.org/</em>.
</p>
<p>
The correct way to mark up this passage is like this:
</p>
<div class="programlisting">
<pre><para>For more information, you <emphasis>really</emphasis>
ought to check out the W3C's website at <systemitem
class="url">http://www.w3.org/</systemitem>.</para></pre>
</div>
<p>
This is called semantic markup because the
"really" and the URL are labelled according to their meaning, not
their appearance. The next snippet shows the incorrect, presentational
markup:
</p>
<div class="programlisting">
<pre>For more information, you <emphasis>really</emphasis>
ought to check out the W3C's website at
<emphasis>http://www.w3.org/</emphasis>.</pre>
</div>
<p>
The author thought that because <tt><emphasis></tt>
causes its contents to be formatted in italic, it's okay to label
everything that comes out in italic as a
<tt><emphasis></tt>. So what? Well, it becomes a
problem when you want to <em>repurpose</em> the document
in HTML. Instead of the URL coming out as a hyperlink, it's merely
formatted in italic. When everything is marked up presentationally,
it's impossible to reuse the content in a different context.
</p>
</div>
<a name="section-4"></a>
<div class="section">
<h2 class="stitle">4. The Physical Structure of a Book</h2>
<p>
By physical structure, we mean the files and
directories used to contain the pieces of an XML document. An O'Reilly
book typically is stored in a single directory. Each chapter, preface,
and appendix exists in a separate file, and there is a
"master" file which contains the top (root) element for
the book. The following table lists the kinds of files and their name
conventions:
</p>
<table border="1">
<h4 class="exampletitle">Table 1. File naming conventions</h4>
<tr>
<th>element</th>
<th>filename</th>
<th>purpose</th>
</tr>
<tr>
<td><tt><book></tt></td>
<td>book.xml</td>
<td>
<p>
Contains the DOCTYPE declaration, declares local entities
in the internal subset, holds metadata, contains file reference
entities to chapters and other external elements.
</p>
</td>
</tr>
<tr>
<td><tt><copyrightpg></tt></td>
<td>copy.xml</td>
<td>
<p>
Contains the copyright page with legal info.
</p>
</td>
</tr>
<tr>
<td><tt><preface></tt></td>
<td>ch00.xml</td>
<td>
<p>
Contains the preface.
</p>
</td>
</tr>
<tr>
<td><tt><chapter></tt></td>
<td>
<p>
ch<i>xx</i>.xml, where
<i>xx</i> is the number of the chapter (e.g. 01,
04, 11)
</p>
</td>
<td>
<p>
Contains a chapter.
</p>
</td>
</tr>
<tr>
<td><tt><appendix></tt></td>
<td>
<p>
app<i>x</i>.xml, where
<i>x</i> is the letter of the appendix (e.g. a, b,
c)
</p>
</td>
<td>
<p>
Contains an appendix.
</p>
</td>
</tr>
<tr>
<td><tt><bibliography></tt></td>
<td>biblio.xml</td>
<td>
<p>
A chapter-level section containing bibliographic citations.
</p>
</td>
</tr>
<tr>
<td><tt><glossary></tt></td>
<td>gloss.xml</td>
<td>
<p>
A chapter-level section containing glossary definitions.
</p>
</td>
</tr>
<tr>
<td><tt><part></tt></td>
<td>
<p>
part<i>x</i>.xml, where
<i>x</i> is the number of the part (e.g. 1, 2,
3)
</p>
</td>
<td>
<p>
Contains a part (the first page only).
</p>
</td>
</tr>
<tr>
<td><tt><colophon></tt></td>
<td>colo.xml</td>
<td>
<p>
A section at the end of the book describing details of the
book's production.
</p>
</td>
</tr>
</table>
<p>
So a typical directory listing for a book would look something like
this:
</p>
<div class="screen">
<pre>$> ls /work/java/java.qref/xml
appa.xml ch01.xml ch06.xml part1.xml
appb.xml ch02.xml ch07.xml part2.xml
appc.xml ch03.xml ch08.xml
book.xml ch04.xml colo.xml
ch00.xml ch05.xml copy.xml</pre>
</div>
<p>
There is one master file for the book (<i>book.xml</i>);
three files for appendixes A, B, and C; one file for the preface;
eight files for chapters 1-8; two files for parts I and II; and a file
each for the copyright page and colophon. Note that the part files do
not contain the chapters, even though the
<tt><part></tt> elements logically contain
<tt><chapter></tt>s.
</p>
</div>
<a name="section-5"></a>
<div class="section">
<h2 class="stitle">5. The Logical Structure of a Book</h2>
<p>
Logical structure is defined by the book's
markup once the files have been assembled, which is how the parser
sees the document. The hierarchy of the book (chapters, sections,
sub-sections, etc.) is constructed using elements called
divisions. A division is a container that
usually has a <tt><title></tt> and contains other
divisions or block elements. We will look at top-level containers
(<tt><book></tt>, <tt><chapter></tt>,
<tt><preface></tt>,
<tt><appendix></tt>, and
<tt><part></tt>), and intermediate-level divisions
(<tt><sect1></tt>, <tt><sect2></tt>,
<tt><sect3></tt>, <tt><sect4></tt>,
<tt><simplesect></tt>, and
<tt><partinfo></tt>).
</p>
<a name="section-1.1"></a>
<div class="ssection">
<h3 class="sstitle">5.1. ID Attributes</h3>
<p>
To facilitate cross references, you should use IDs in major
hierarchical elements such as sections, chapters, and appendixes.
For example, a chapter might have an ID like this:
</p>
<div class="programlisting">
<pre><chapter id="intro-chapter"></pre>
</div>
<p>
Technically, the only requirement for an ID attribute is that it be
unique, since in XML no two elements can have the same ID attribute.
However, we ask that you use attribute names that are easy to read
and indicate the type of element and its subject. For example,
<tt>id="shapes-section"</tt> is better than
<tt>id="A6-4.2"</tt>.
</p>
<p>
When the book is in production, and the order of elements is
solidified, we will sometimes run a program that inserts ID attributes
where they were previously missing, or to replace those that make
sense only to the author. These generated IDs follow a pattern that
helps production staff trace links to their targets, even if the
target ID is missing or misspelled. The following table lists these
ID patterns:
</p>
<table border="1">
<h4 class="exampletitle">Table 1. Autogenerated ID Attributes</h4>
<tr>
<th>element</th>
<th>pattern</th>
<th>example</th>
</tr>
<tr>
<td>appendix</td>
<td><i>prefix</i>-APP-<i>letter</i></td>
<td>MONKEYS-APP-B</td>
</tr>
<tr>
<td>chapter</td>
<td><i>prefix</i>-CH-<i>num</i></td>
<td>MONKEYS-CH-3</td>
</tr>
<tr>
<td>preface</td>
<td><i>prefix</i>-PREF</td>
<td>MONKEYS-PREF</td>
</tr>
<tr>
<td>part</td>
<td><i>prefix</i>-PART-<i>num</i></td>
<td>MONKEYS-PART-2</td>
</tr>
<tr>
<td>sect1 (A-head or section)</td>
<td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-SECT-<i>num</i></td>
<td>MONKEYS-CH-3-SECT-2</td>
</tr>
<tr>
<td>sect2 (B-head or sub section)</td>
<td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-SECT-<i>num</i>.<i>num</i></td>
<td>MONKEYS-CH-3-SECT-2.4</td>
</tr>
<tr>
<td>figure</td>
<td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-FIG-<i>num</i></td>
<td>MONKEYS-PREF-FIG-24</td>
</tr>
<tr>
<td>table</td>
<td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-TABLE-<i>num</i></td>
<td>MONKEYS-APP-C-TABLE-11</td>
</tr>
<tr>
<td>example</td>
<td><i>prefix</i>-<i>CH/APP</i>-<i>num/letter</i>-EX-<i>num</i></td>
<td>MONKEYS-CH-12-EX-8</td>
</tr>
<tr>
<td>indexterm</td>
<td><i>prefix</i>-<i>terms</i></td>
<td>MONKEYS-perilous-furballs</td>
</tr>
</table>
<p>
The <i>prefix</i> is a short code you pick to
represent your book in <tt>id</tt>s. It's not required, but
we use it to eliminate any confusion when handling files separately,
since there is nothing within each file to indicate which book it came
from.
</p>
<p>
The number for any element type starts at 1. For elements inside
chapters or appendixes, the numbering is starts within the
chapter/appendix and continues to increment until the very end. An
exception is for sections, whose numbering resets to 1 with each
parent section or chapter.
</p>
</div>
<a name="section-1.2"></a>
<div class="ssection">
<h3 class="sstitle">5.2. The master book file</h3>
<p>
This file is the root of the whole book. Therefore, it contains the
important XML declaration at the top, as well as a directive to
declare the DTD. You would modify the second string value to the
actual location of the DTD on your system. Next are entity
declarations. These can only reside inside the square brackets. First
are the entities that point to the files in your book. Then follow any
special entities you want to define. The
<tt><bookinfo></tt> element will later be filled with
metadata, but for now it can be left empty. Finally, the entity
references for book files are listed in order at the bottom.
</p>
<div class="example">
<h4 class="exampletitle">Example 1. Contents of <i>book.xml</i>
</h4>
<div class="programlisting">
<pre><!DOCTYPE book PUBLIC
"-//ORA//DBLITE 1.1//EN" "/usr/local/prod/sgml/dblite/new.dtd"
[
<!-- Declare external entities -->
<!ENTITY ch00 SYSTEM "ch00.xml">
<!ENTITY ch01 SYSTEM "ch01.xml">
<!ENTITY ch02 SYSTEM "ch02.xml">
<!ENTITY ch03 SYSTEM "ch03.xml">
<!ENTITY ch04 SYSTEM "ch04.xml">
<!ENTITY ch05 SYSTEM "ch05.xml">
<!ENTITY ch06 SYSTEM "ch06.xml">
<!ENTITY ch07 SYSTEM "ch07.xml">
<!ENTITY ch08 SYSTEM "ch08.xml">
<!ENTITY ch09 SYSTEM "ch09.xml">
<!ENTITY part1 SYSTEM "part1.xml">
<!ENTITY part2 SYSTEM "part2.xml">
<!ENTITY appa SYSTEM "appa.xml">
<!ENTITY appb SYSTEM "appb.xml">
<!ENTITY appc SYSTEM "appc.xml">
<!ENTITY copy SYSTEM "copy.xml">
<!ENTITY colo SYSTEM "colo.xml">
<!-- Declare text entities -->
<!ENTITY ascii "<acronym>ASCII</acronym>">
<!ENTITY html "<acronym>HTML</acronym>">
<!ENTITY sgml "<acronym>SGML</acronym>">
<!ENTITY xml "<acronym>XML</acronym>">
<!ENTITY w3url "http://www.w3.org/">
]>
<book>
<title>Learning &xml;</title>
<bookinfo>
<!-- Marketing information and metadata,
to be filled out in production. -->
</bookinfo>
<!-- External entity refs -->
&ch00;
&copy;
&part1;
&part2;
&colo;
</book></pre>
</div>
</div>
<p>
In this example, none of the external entity references for chapters
and appendixes appear in <i>book.xml</i>. We will see
later that the chapters and appendixes are references only inside the
files for the parts in which they belong, to maintain the proper
hierarchy.
</p>
</div>
<a name="section-1.3"></a>
<div class="ssection">
<h3 class="sstitle">5.3. The preface</h3>
<p>
The preface is contained entirely within one file called
<i>ch00.xml</i>. It looks like this:
</p>
<div class="example">
<h4 class="exampletitle">Example 1. Contents of <i>ch00.xml</i>
</h4>
<div class="programlisting">
<pre><preface id="XML-PREF">
<title>Preface</title>
<!-- preamble (no A-head) -->
<simplesect>
<para>Welcome to &xml;. Put on your geek hat, twirl the
propeller, and get ready for a wacky ride!</para>
<para>Blah blah blah blah blah...</para>
</simplesect>
<!-- the first section (A-head) -->
<sect1 id="XML-PREF-SECT-1">
<title>Why &xml;?</title>
<para>&xml; is a markup language development kit. Blah blah
blah...</para>
<para>Blah blah blah blah blah...</para>
</sect1>
<!-- the second section -->
<sect1 id="XML-PREF-SECT-2">
<title>What's inside</title>
<para><xref linkend="XML-PART-1"/> starts off with an
introduction to some basic &xml; areas that any author ought to be
familiar with. Blah blah blah...</para>
</sect1>
<!-- Other sections... -->
</preface></pre>
</div>
</div>
</div>
<a name="section-1.4"></a>
<div class="ssection">
<h3 class="sstitle">5.4. Part Pages</h3>
<p>
A <tt><part></tt> is an element that contains chapters
or appendixes, dividing the book into major categories. At O'Reilly,
we separate chapters into different files by convention, so the part
is spread across several files. The front page of the part doesn't
belong in any particular chapter, so it gets its own file:
</p>
<div class="example">
<h4 class="exampletitle">Example 1. Contents of <i>part1.xml</i>
</h4>
<div class="programlisting">
<pre><part id="XML-PART-1">
<title>Basic Concepts</title>
<partintro>
<para>In this part of the book, we focus on easy material.
Blah blah blah...</para>
</partintro>
<!-- External entity references -->
&ch01;
&ch02;
&ch03;
&ch04;
</part></pre>
</div>
</div>
<p>
No entity declarations are necessary because they were made in the
<i>book.xml</i> file and carried over. The
<tt><partinfo></tt> is an intermediate-level division
that contains all elements between the
<tt><title></tt> and the chapter-level children of the
<tt><part></tt>.
</p>
</div>
<a name="section-1.5"></a>
<div class="ssection">
<h3 class="sstitle">5.5. The Chapter</h3>
<p>
Chapters follow the same basic pattern as a preface:
</p>
<div class="example">
<h4 class="exampletitle">Example 1. Contents of ch01.xml</h4>
<div class="programlisting">
<pre><chapter id="XML-CH-1">
<title>&xml; Basics</title>
<!-- preamble (no A-head) -->
<simplesect>
<para>In this chapter, we cover the
fundamentals of markup and document structure. Blah blah blah...</para>
<para>Blah blah blah blah blah...</para>
</simplesect>
<!-- the first section (A-head) -->
<sect1 id="XML-CH-1-SECT-1">
<title>What is Markup?</title>
<para>There's a lot of stuff you can
do with markup. Blah blah blah...</para>
<para>Blah blah blah blah blah...</para>
</sect1>
<!-- the second section -->
<sect1 id="XML-CH-1-SECT-2">
<title>A historical perspective</title>
<para>It's useful to see how &xml;
fits in the long line of markup languages. Blah blah blah...</para>
<!-- a sub-section -->
<sect2 id="XML-CH-1-SECT-2.1>
<title>The earliest days</title>
<para>Back in the olden days of
digital text, work was very hard. We had to flip knife switches
to program computers and &ascii;
was the only character set in town. Blah blah blah...</para>
<para>Blah blah blah blah blah...</para>
<!-- a sub-sub-section -->
<sect3 id="XML-CH-1-SECT-2.1.1>
<title>How I had to walk to work barefoot, uphill
both ways</title>
<para>Blah blah blah blah blah...</para>
<figure id="XML-CH-1-FIG-1">
<title>Picture of my blistered feet</title>
<graphic fileref="figs/soretoes.gif"/>
</figure>
</sect3>
</sect2>
</sect1>
<!-- Other sections... -->
</chapter></pre>
</div>
</div>
<p>
The hierarchy of sections is important. A
<tt><sect1></tt> contains
<tt><sect2></tt>s, which can contain
<tt><sect3></tt>s, etc. Also important: we now require
that elements after the chapter <tt><title></tt>, but
before the first <tt><sect1></tt>, be enclosed in a
<tt><simplesect></tt>.
</p>
<p>
Appendixes are pretty much the same as chapters, except that they are
contained in an <tt><appendix></tt> element instead of
a <tt><chapter></tt>, and the <tt>id</tt>
format is different.
</p>
</div>
<a name="section-1.6"></a>
<div class="ssection">
<h3 class="sstitle">5.6. Glossary</h3>
<p>
A glossary is a collection of definitions for terms used in the
book. A <tt><glossary></tt> element surrounds the
whole thing, and is usually at the same level as a chapter. Each
definition is contained in a <tt><glossentry></tt>
element with one <tt><glossentry></tt>,
containing the term being defined, and an optional (if there is a
see-also, for example) <tt><glossdef></tt>, containing
the definition. It can also contain any number of
<tt><glosssee></tt> and
<tt><glossseealso></tt> elements, which redirect the
reader's attention to another term. Stylistically, a
<tt><glossentry></tt> should not contain both a
<tt><glossdef></tt> and
<tt><glosssee></tt>, but a
<tt><glossdef></tt> and
<tt><glossseealso></tt> are okay.
</p>
<p>
A glossary looks like this:
</p>
<div class="example">
<h4 class="exampletitle">Example 1. Contents of gloss.xml</h4>
<div class="programlisting">
<pre><glossary id="the-glossary">
<!-- SECTION: XML-SPECIFIC TERMS -->
<glossdiv>
<title>XML Terms</title>
<glossentry>
<glossterm>absolute location term</glossterm>
<glossdef>
<para>A term that completely identifies the location of a
resource via XPointer. A unique ID attribute assigned to an
element can be used as an absolute location
term.</para>
</glossdef>
<glossseealso>relative location term</glossseealso>
<glossseealso>XPath</glossseealso>
<glossseealso>XPointer</glossseealso>
</glossentry>
<glossentry>
<glossterm>actuation</glossterm>
<glossdef>
<para>How a link in a document is triggered. For example, a
link to an imported graphic automatically includes a graphic
in the document, and a link to a URL resource requires a
signal from a human.</para>
</glossdef>
</glossentry>
</glossdiv>
<!-- SECTION: OTHER TERMS -->
<glossdiv>
<title>Other Terms</title>
<glossentry>
<glossterm>albatross<glossterm>
<glosssee>birds</glosssee>
</glossentry>
</glossdiv>
</glossary></pre>
</div>
</div>
</div>
<a name="section-1.7"></a>
<div class="ssection">
<h3 class="sstitle">5.7. Bibliography</h3>
<p>Coming soon...</p>
</div>
</div>
<a name="section-6"></a>
<div class="section">
<h2 class="stitle">6. Block elements</h2>
<p>
A block element is any element that starts a
new line when formatted and contains inline elements. We have seen
three already: <tt><para></tt>,
<tt><title></tt>, and
<tt><figure></tt>. Following is a table of block
elements with examples:
</p>
<table border="1">
<h4 class="exampletitle">Table 1. Common block elements</h4>
<tr>
<th>element</th>
<th>purpose</th>
<th>example</th>
</tr>
<tr>
<td><tt><para></tt></td>
<td>Paragraph.</td>
<td>
<div class="programlisting">
<pre><para>The quick, brown fox jumped over the lazy
dog. The quick, brown fox jumped over the lazy dog.
The quick, brown fox jumped over the lazy dog.</para></pre>
</div>
</td>
</tr>
<tr>
<td><tt><title></tt></td>
<td>Title.</td>
<td>
<div class="programlisting">
<pre><title>The Benefits of Laughter</title></pre>
</div>
</td>
</tr>
<tr>
<td><tt><remark></tt></td>
<td>
<p>
Comment that is not meant for the audience, and outside of the
flow of text. Usually, a communication between the author, editor,
reviewers, copyeditors, etc.
</p>
</td>
<td>
<div class="programlisting">
<pre><remark>This section is too short
and needs more examples. [Ellen]</remark></pre>
</div>
</td>
</tr>
<tr>
<td><tt><blockquote></tt></td>
<td>Quotation.</td>
<td>
<div class="programlisting">
<pre><blockquote>
<para>"They who can give up essential
liberty to purchase a little temporary
safety, deserve neither liberty nor safety,"
spat Ben Franklin.</para>
<para>"Yes," replied Mark Twain, "but
loyalty to petrified opinion never broke a
chain or freed a human soul."</para>
</blockquote></pre>
</div>
</td>
</tr>
<tr>
<td><tt><itemizedlist></tt></td>
<td>
<p>A list of items where order doesn't matter.</p>
</td>
<td>
<div class="programlisting">
<pre><itemizedlist>
<listitem><para>dogsled</para></listitem>
<listitem><para>hang-glider</para></listitem>
<listitem><para>roller blades</para></listitem>
</itemizedlist></pre>
</div>
</td>
</tr>
<tr>
<td><tt><orderedlist></tt></td>
<td>
<p>
A list of items where order is important.
</p>
</td>
<td>
<div class="programlisting">
<pre><orderedlist>
<listitem><para>Get a bowl.</para></listitem>
<listitem><para>Pour the cereal.</para></listitem>
<listitem><para>Add the milk.</para></listitem>
<listitem><para>Eat.</para></listitem>
</orderedlist></pre>
</div>
</td>
</tr>
<tr>
<td><tt><variablelist></tt></td>
<td>
<p>
A list that contains terms and their definitions.
</p>
</td>
<td>
<div class="programlisting">
<pre><variablelist>
<varlistentry><term>Snickers</term>
<listitem><para>Peanuts in nougat
covered in chocolate.</para></listitem></varlistentry>
<varlistentry><term>Payday</term>
<listitem><para>A peanut cluster cemented with caramel and
delicious sticky stuff.</para></listitem></varlistentry>
</variablelist></pre>
</div>
</td>
</tr>
<tr>
<td><tt><programlisting></tt></td>
<td>
<p>
A piece of computer code or example markup where whitespace and
other formatting must be preserved.
</p>
</td>
<td>
<div class="programlisting">
<pre><programlisting>public void init(ServletConfig config)
throws ServletException {
super.init(config);
String greeting = getInitParameter("greeting");
}</programlisting></pre>
</div>
</td>
</tr>
<tr>
<td><tt><screen></tt></td>
<td>
<p>
A representation of data displayed on a computer
screen. (Whitespace and other formatting are preserved.)
</p>
</td>
<td>
<div class="programlisting">
<pre><screen>&gt; ls -l
total 6860
-r--r--r-- 1 eray ora 2570 Mar 27 19:38 BOOKFILES
-rw-rw-r-- 1 eray ora 13283 Mar 27 19:38 BOOKIDS
-rw-rw-r-- 1 sierra ora 2692 Mar 28 14:43 Makefile
drwxrwxr-x 2 jwizda ora 512 Aug 10 14:22 RCS/
-rw-rw-r-- 1 jwizda ora 39 Jul 26 17:39 README</screen></pre>
</div>
</td>
</tr>
<tr>
<td><tt><literallayout></tt></td>
<td>
<p>
Traditional text with special linebreaks to be preserved.
</p>
</td>
<td>
<div class="programlisting">
<pre><literallayout>to be yourself, in a world that
tries, night and day, to make you
just like everybody else, is to fight
the greatest battle there ever is
to fight, and never stop fighting
e. e. cummings</literallayout></pre>
</div>
</td>
</tr>
<tr>
<td><tt><figure></tt></td>
<td>
<p>
A graphic with a title.
</p>
</td>
<td>
<div class="programlisting">
<pre><figure id="FOO-APP-E-FIG-19">
<title>The garden variety eggplant</title>
<graphic fileref="figs/eggplant.eps"/>
</figure></pre>
</div>
</td>
</tr>
<tr>
<td><tt><example></tt></td>
<td>
<p>Anything that serves as an example and requires a
title. (Use an <informalexample> if you don't need a
title.)
</p>
</td>
<td>
<div class="programlisting">
<pre><example id="BAZ-CH-14-EX-5">
<title>Contents of the file
<filename>blather.cfg</filename></title>
<programlisting>CATS = -c/usr/local/prod/sgml/CATALOG
DSLCAT = -c/usr/local/sp/dsssl/catalog
DECL = /usr/local/sp/pubtext/xml.dcl
SRCHURL = xsrch.htm
STYLE = dbwrap.dsl
VALOPTS = -sv -wxml</programlisting>
</example></pre>
</div>
</td>
</tr>
</table>
</div>
<a name="section-7"></a>
<div class="section">
<h2 class="stitle">7. Inline elements</h2>
<p>
In contrast to block elements, inline elements
do not force a line break, but coexist peacefully with their siblings
inside a block element. There are two basic types: those that contain
data, and those that don't. The first group is used to label one or
more words as a special kind of object, or deserving of special
processing. Those in the second group function as markers in the text,
anchoring a cross reference or marking some other kind of positional
data. The following table lists inline elements and their
function.
</p>
<table border="1">
<h4 class="exampletitle">Table 1. Inline Elements</h4>
<tr>
<th>element</th>
<th>purpose</th>
<th>example</th>
</tr>
<tr>
<td><tt><abbrev></tt></td>
<td>An abbreviated term.</td>
<td>
<div class="programlisting">
<pre>She's in <abbrev>bldg</abbrev 42.></pre>
</div>
</td>
</tr>
<tr>
<td><tt><accel></tt></td>
<td>A shortcut.</td>
<td>
<div class="programlisting">
<pre>Type <accel>Ctl-s</accel> to search for
a term.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><acronym></tt></td>
<td>
<p>
Mark text as being an acronym.
</p>
</td>
<td>
<div class="programlisting">
<pre><acronym>ASCII</acronym></pre>
</div>
</td>
</tr>
<tr>
<td><tt><action></tt></td>
<td>
<p>
A user interface action like a mouse click.
</p>
</td>
<td>
<div class="programlisting">
<pre>Click <action>mouse
button-3</action> for a pop-up menu.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><application></tt></td>
<td>
<p>
The name of a computer software program.</p>
</td>
<td>
<div class="programlisting">
<pre>We can convert any document written in
<application<Microsoft Word</application>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><citation></tt></td>
<td>
<p>
The source of a quote or piece of information.
</p>
</td>
<td>
<div class="programlisting">
<pre><citation>Bill Gates</citation>
once said <quote>256 kB of RAM ought to be good enough
for anybody.</quote></pre>
</div>
</td>
</tr>
<tr>
<td><tt><citetitle></tt></td>
<td>
<p>
The name of a book or article.
</p>
</td>
<td>
<div class="programlisting">
<pre><citetitle>The Hobbit</citetitle></pre>
</div>
</td>
</tr>
<tr>
<td><tt><classname></tt></td>
<td>
<p>
An identifier for a class in some programming
language.
</p>
</td>
<td>
<div class="programlisting">
<pre>The <classname>string</class>
class has six public methods.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><classref></tt></td>
<td>
<p>
A cross reference to a class, with special formatting such as
displaying the class name. (Used mainly in Java books.)
</p>
</td>
<td></td>
</tr>
<tr>
<td><tt><command></tt></td>
<td>
<p>
Any command one would type in a computer terminal.
</p>
</td>
<td>
<div class="programlisting">
<pre>To print the file to screen, use the
<command>lpr</command> command.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><computeroutput></tt></td>
<td>
<p>
Text that would be output by a computer program.
</p>
</td>
<td>
<div class="programlisting">
<pre>When we run the script we get the result
<computeroutput>file not found</computeroutput>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><email></tt></td>
<td>
<p>
An email address. (Note that there may be some conflict
with the <systemitem> element.)
</p>
</td>
<td>
<div class="programlisting">
<pre>Send questions to
<email>tools@oreilly.com</email>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><emphasis></tt></td>
<td>
<p>
Give special emphasis to a word or phrase. Usually this
formats as italic, but default formatting can be overridden with a
<tt>role</tt> attribute such as
<tt>role="bold"</tt>.
</p>
</td>
<td>
<div class="programlisting">
<pre>This step is <emphasis>very</emphasis> important</pre>
</div>
</td>
</tr>
<tr>
<td><tt><envar></tt></td>
<td>An environment variable.</td>
<td>
<div class="programlisting">
<pre>Set the variable <envar>EDITOR</envar>
to <literal>emacs</literal>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><filename></tt></td>
<td>Tags a word as being a filename.</td>
<td>
<div class="programlisting">
<pre>Be sure to read
<filename>readme.txt</filename>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><firstterm></tt></td>
<td>
<p>
The first time an important term is mentioned.
</p>
</td>
<td>
<div class="programlisting">
<pre>A <firstterm>squib</firstterm>
is someone born to a wizard family but who can't do magic.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><foreignphrase></tt></td>
<td>Words from another language.</td>
<td>
<div class="programlisting">
<pre>There's nothing wrong with borrowing code
<foreignphrase>per se<foreignphrase>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><footnoteref></tt></td>
<td>
<p>
A marker that imports a <tt><footnote></tt>
where there would otherwise be a redundant footnote
definition.
</p>
</td>
<td>
<div class="programlisting">
<pre>The Eiffel Tower is huge<footnote id="ABC-CH-4-FN-2">
<para>Although, compared to a breadbox, any
building is huge.</para></footnote>. So is a redwood
tree<footnoteref linkend="ABC-CH-4-FN-2">.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><graphic></tt></td>
<td>
<p>
An icon or picture to be imported into the document.
</p>
</td>
<td>
<div class="programlisting">
<pre>Examples marked with a disk icon
<graphic fileref="figs/icon.eps"> are on
the companion disk.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><function></tt></td>
<td>
<p>
The name of a function, method, or subroutine.
</p>
</td>
<td>
<div class="programlisting">
<pre>The function
<function>alpha_sort</function> can be made more
efficient.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><guibutton></tt></td>
<td>
<p>
A clickable control (e.g. a button) in a graphical interface.
</p>
</td>
<td>
<div class="programlisting">
<pre>Select the
<guibutton>print<guibutton> button to get
hardcopy.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><guimenu></tt></td>
<td>
<p>
A menu or submenu in a graphical interface.
</p>
</td>
<td>
<div class="programlisting">
<pre>Close the program by selecting
<guimenuitem>exit</guimenuitem> from the
<guimenu>file</guimenu> menu.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><guimenuitem></tt></td>
<td>
<p>
An item in a menu or submenu in a graphical interface.
</p>
</td>
<td>
<div class="programlisting">
<pre>Close the program by selecting
<guimenuitem>exit</guimenuitem> from the
<guimenu>file</guimenu> menu.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><keycap></tt></td>
<td>
<p>
A character to be represented as a key on a keyboard.
</p>
</td>
<td>
<div class="programlisting">
<pre>Pressing <keycap>s</keycap>
will save the buffer to a file.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><keysym></tt></td>
<td></td>
<td></td>
</tr>
<tr>
<td><tt><lineannotation></tt></td>
<td>
<p>
An annotation appearing inside a <tt><screen></tt> or
<tt><programlisting></tt>.
</p>
</td>
<td>
<div class="programlisting">
<pre>for( int $i=0; $i<10; $i++ ) {
<lineannotation>body of loop</lineannotation>
}</pre>
</div>
</td>
</tr>
<tr>
<td><tt><literal></tt></td>
<td>
<p>
A token or string that is part of a computer program or
script, which should be formatted in constant width.
</p>
</td>
<td>
<div class="programlisting">
<pre>If the parameter's value is
<literal>YELLOW</literal> your subroutine will
explode.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><option></tt></td>
<td>
<p>
A code to apply an optional parameter to a command,
program, or function.
</p>
</td>
<td>
<div class="programlisting">
<pre>The command synopsis is
<command>rm <option>-i</option> *.txt</command>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><optional></tt></td>
<td>
<p>
Designates some text as an optional item.
</p>
</td>
<td>
<div class="programlisting">
<pre>The stylesheet specification is optional:
<command>formatfiles <optional>stylesheet</optional>
in.xml<command>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><parameter></tt></td>
<td>
<p>
The name of a parameter for a function, method, or subroutine.
</p>
</td>
<td>
<div class="programlisting">
<pre>In the <function>factorial</function>
function, there is only one parameter,
<parameter>num</parameter>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><prompt></tt></td>
<td>
<p>
A word meant to appear as a prompt in a computer display.
</p>
</td>
<td>
<div class="programlisting">
<pre>At the prompt
<prompt>Data?</prompt>, type in your age in
hexadecimal.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><quote></tt></td>
<td>
<p>
Quoted text.
</p>
</td>
<td>
<div class="programlisting">
<pre>Our motto is
<foreignphrase>Caveat Emptor</foreignphrase>,
which means <quote>we hope you like it!</quote></pre>
</div>
</td>
</tr>
<tr>
<td><tt><replaceable></tt></td>
<td>
<p>
Marks the data as a replaceable item, a value to be filled in.
</p>
</td>
<td>
<div class="programlisting">
<pre>...where <replaceable>w</replaceable>
is the width.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><returnvalue></tt></td>
<td>
<p>
Data that has been returned from a program or function.
</p>
</td>
<td>
<div class="programlisting">
<pre>The <function>reverse_string</function>
gives the value <returnvalue>tesolcmoorb</returnvalue>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><sgmltag></tt></td>
<td>
<p>
The name of an SGML or XML element.
</p>
</td>
<td>
<div class="programlisting">
<pre>The <sgmltag>P</sgmltag>
element adds space above and below.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><structfield></tt></td>
<td>
<p>
The name of a field in a data structure.
</p>
</td>
<td>
<div class="programlisting">
<pre><structfield>name</structfield>
is a fixed array of bytes.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><structname></tt></td>
<td>
<p>
The name of a data structure.
</p>
</td>
<td>
<div class="programlisting">
<pre>To add a record, we must create a new
<structname>PartStruct</structname>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><subscript></tt></td>
<td>
<p>
Text that should be rendered in subscript (smaller and
below the baseline).
</p>
</td>
<td>
<div class="programlisting">
<pre>The molecule
H<subscript>2</subscript>O has many strange
properties.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><superscript></tt></td>
<td>
<p>
Text that should be rendered in superscript (smaller and
above the midline).
</p>
</td>
<td>
<div class="programlisting">
<pre>Einstein revolutionized physics with
the simple equation E=MC<superscript>2</superscript></pre>
</div>
</td>
</tr>
<tr>
<td><tt><symbol></tt></td>
<td>
<p>A special symbol or token.</p>
</td>
<td>
<div class="programlisting">
<pre>The mutant gene <symbol>BLu-6</symbol>
is responsible for Smurfs' vivid azure hue.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><systemitem></tt></td>
<td>
<p>
Designates data as a special item having to do with
computers or networks. Most common use is to encode a
URL.
</p>
</td>
<td>
<div class="programlisting">
<pre><systemitem class="url">http://www.oreilly.com</systemitem></pre>
</div>
</td>
</tr>
<tr>
<td><tt><type></tt></td>
<td>
<p>A variable or constant data type.</p>
</td>
<td>
<div class="programlisting">
<pre>The function returns a value of type
<type>boolean</type>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><userinput></tt></td>
<td>
<p>
Text entered by a human into a computer terminal.
</p>
</td>
<td>
<div class="programlisting">
<pre>At the command line, type
<userinput>telnet bubba.beerguzzlin.org</userinput></pre>
</div>
</td>
</tr>
<tr>
<td><tt><wordasword></tt></td>
<td>
<p>A word used as an example.</p>
</td>
<td>
<div class="programlisting">
<pre>By <wordasword>snake</wordasword>,
I mean <quote>dirty, stinkin' varmint</quote>.</pre>
</div>
</td>
</tr>
<tr>
<td><tt><xref></tt></td>
<td>
<p>
A cross reference to some element in the book. The
required <tt>linkend</tt> attribute contains the
<tt>id</tt> of the element being referenced.
</p>
</td>
<td>
<div class="programlisting">
<pre>For more information, refer to
<xref linkend="XYZ-CH-4"/>.</pre>
</div>
</td>
</tr>
</table>
</div>
<a name="section-8"></a>
<div class="section">
<h2 class="stitle">8. Tables</h2>
<p>
The tables used in DocBook Lite are a slimmed-down version of the CALS
table model, a popular markup format for tables. There are two outer
elements for tables: <tt><table></tt>, which requires
a title, and <tt><informaltable></tt>, which does not.
These elements contain a <tt><tgroup></tt> element
with an attribute <tt>cols</tt> that specifies the number of
columns in the table.
</p>
<p>
The table has a head, body, and foot, contained in
<tt><thead></tt>, <tt><tbody></tt>,
and <tt><tfoot></tt> elements, respectively. Only the
body is required. The head and body contain a set of rows, each a
<tt><row></tt> element. The foot contains text that
will appear just below the table, usually within the lines.
</p>
<p>
A <tt><row></tt> element contains some number of
<tt><entry></tt>s, each corresponding to a table
cell. The entry may either contain mixed content text, or a block
element such as a paragraph. The following is an example of a simple
titled table:
</p>
<div class="programlisting">
<pre><table id="ABC-CH-1-TABLE-5">
<title>States and Their Capitals</title>
<tgroup cols="2">
<thead>
<row>
<entry>State</entry>
<entry>Capital</entry>
</row>
</thead>
<tbody>
<row>
<entry>New York</entry>
<entry>Albany</entry>
</row>
<row>
<entry>Massachusetts</entry>
<entry>Boston</entry>
</row>
<row>
<entry>Hawaii</entry>
<entry>Honalulu</entry>
</row>
</tbody>
</tgroup>
</table></pre>
</div>
<p>
To span a row, add to the <tt><entry></tt>
element an attribute <tt>morerows="N"</tt>, where N is the
number of rows to span beyond the current row. For example, to make an
entry that spans 3 rows, use <tt>morerows="2"</tt>. For each
of the following rows that are spanned, leave out an
<tt><entry></tt> element, since the spanning cell will
inhabit that space.
</p>
<p>
To span columns, it's a bit more complicated (we didn't try to fix the
weird CALS way of doing it). First, you have to name the columns.
Second, you need to create named spans. Finally, you reference the
spans within the table cells. Here's an example:
</p>
<div class="programlisting">
<pre><informaltable>
<tgroup cols="3">
<colspec colnum="1" colname="c1">
<colspec colnum="3" colname="c3">
<spanspec spanname="span13" namest="c1" nameend="c3">
<tbody>
<row>
<entry>A</entry>
<entry>B</entry>
<entry>C</entry>
</row>
<row>
<entry colspan="span13" >D</entry>
</row>
<row>
<entry>E</entry>
<entry>F</entry>
<entry>G</entry>
</row>
</tbody>
</tgroup>
</table></pre>
</div>
</div>
<a name="section-9"></a>
<div class="section">
<h2 class="stitle">9. Indexterms</h2>
<p>
We generate indexes for books automatically, with the data originating
in <tt><indexterm></tt> elements interspersed
throughout the book. An indexterm holds all the information necessary
for a single entry in an index, including the primary, secondary, and
tertiary terms, references to other entries (see, see also), how to
sort the term, and whether it should cross a range of pages. An
indexterm typically looks like this:
</p>
<div class="programlisting">
<pre><indexterm id="ixt-blather-frobozz-zmic">
<primary>blather</primary>
<secondary>frobozz</secondary>
<tertiary sortas="@">zmic</tertiary>
<seealso>fuj</seealso>
</indexterm></pre>
</div>
<p>
The term in this example is a tertiary-level term "zmic", which appears
under the secondary term "frobozz", under the primary term
"blather". It will be sorted as if it began with the character "@",
which will pull it to the top of the secondary term's listing. The
term will display "see also fuj". Here's how the final index entry
might look in an index:
</p>
<div class="screen">
<pre>blaam 24-26
blather
abba 12, 15
crufty 99-105, 411
frobozz 75
zmic 10 (see also fuj) <-- the term
asca 19, 22
gumm 82-88
splat 470
zingle (see grooby)
gurgle 99, 111
bmm (see kluk)
bravy
scoot 45-48
yodle 91</pre>
</div>
<p>
Indexterms can appear inside a wide variety of elements, but they
typically appear inside paragraphs, lists, tables, or sections. They
are forbidden from appearing in titles, and should only rarely appear
inside program listings.
</p>
<p>
To create a term that spans a segment of text, you use two
<tt><indexterm></tt> elements linked by an
<tt>id</tt>-<tt>startref</tt>
attribute pair and <tt>class</tt> attributes. For
example:
</p>
<div class="programlisting">
<pre><!-- start of the range -->
<indexterm id="idx-fooby" class="startofrange">
<primary>fooby</primary>
</indexterm>
<!-- content to be indexed -->
<sect1>
<title>Programming Your Fooby</title>
<para>Blah blah blah...</para>
...
</sect1>
<!-- end of the range -->
<indexterm class="endofrange" startref="idx-fooby"/></pre>
</div>
</div>
<a name="section-10"></a>
<div class="section">
<h2 class="stitle">10. Out-of-flow Text</h2>
<p>
Out-of-flow text is handled in several ways. Sidebars are for short
discussions that don't belong in the general flow, aren't suitable for
their own section, and can easily be encapsulated as a one-page
aside. Admonitions (e.g. warnings, cautions, tips, etc.) are like
sidebars but attract attention to themselves with more dramatic
formatting and often an icon. Footnotes are shorter notes that have
only a weak connection to the text and should be removed from view to
the bottom of the page.
</p>
<a name="section-1.1"></a>
<div class="ssection">
<h3 class="sstitle">10.1. Sidebars</h3>
<p>
A sidebar functions like a section, but cannot contain sections within
itself. Any other block content is allowed. They can appear at any
level in the document underneath the chapter level. For example:
</p>
<div class="programlisting">
<pre><section>
<title>Bathyscaph Care and Maintenance</title>
<para>The hull of your submersible chamber is warranted
for seven years against seal ruptures and corrosion of fittings.
With proper care, you can extend the usable lifetime
considerably. Barnacles are the most common cause of
metal fatigue and gasket deterioration (see the sidebar for
tips in removing these pests).</para>
<sidebar>
<title>Scraping Barnacles</title>
<para>You'll need a wire brush and a solution of equal parts
vinegar and water. Pour the solution over the barnacles and let it
sit for several hours. When the barnacle shells are soft, scrub
them vigorously with the brush...</para>
...
</sidebar>
...
</sect2></pre>
</div>
</div>
<a name="section-1.2"></a>
<div class="ssection">
<h3 class="sstitle">10.2. Admonitions</h3>
<p>
To catch a reader's attention about a serious consideration, use an
admonition. DocBook provides a whole bunch: caution, important, note, tip,
and warning. In the absence of a title, either a default will be used
(e.g. "WARNING!") or an icon will catch the reader's attention. Here's
an example:
</p>
<div class="programlisting">
<pre><caution>
<para>Make sure your craft has reached the surface
before unsealing the hatch. Otherwise, high-pressure
water will flood the compartment.</para>
</caution></pre>
</div>
<p>
An admonition can appear in any section but cannot contain
sections. Try to keep its content simple, using only paragraphs and
lists if possible.
</p>
</div>
<a name="section-1.3"></a>
<div class="ssection">
<h3 class="sstitle">10.3. Footnotes</h3>
<p>
A <tt><footnote></tt> is coded as a block that
interrupts a paragraph. It can look a little odd:
</p>
<div class="programlisting">
<pre><para>When on Mars, be sure to
visit the great volcano Olympus Mons<footnote>
<para>It happens to be the tallest mountain in the Solar
System, so bring your best hiking shoes.</para>
</footnote>...</pre>
</div>
<p>
When the same footnote applies to different places in a document, you
can use a <tt><footnoteref></tt> element to reference
it. The following example shows how:
</p>
<div class="programlisting">
<pre><table>
<tgroup cols="2">
<row>
<entry>apple</entry>
<entry>red</entry>
</row>
<row>
<entry>banana<footnote id="warning">
<para>Peel it first!</para>
</footnote></entry>
<entry>yellow</entry>
</row>
<row>
<entry>grape</entry>
<entry>purple</entry>
</row>
<row>
<entry>orange<footnoteref
linkend="warning"/></entry>
<entry>orange</entry>
</row>
</tgroup>
</table></pre>
</div>
</div>
<a name="section-1.4"></a>
<div class="ssection">
<h3 class="sstitle">10.4. Endnotes</h3>
<p>
In some cases, you want a footnote's text to appear in another section
or chapter. The <tt><endnote></tt> element serves that
function. It also stores the body of the note elsewhere. For example:
</p>
<div class="programlisting">
<pre><para>We suspect that lightning often appears in hues other
than white. This hypothesis is supported by
Dr. Indigo Riceway<endnote linkend="note-riceway"/>.</para>
...
<endnote id="note-riceway">
<para>Riceway wrote about green lightning in his
book...</para>
</endnote></pre>
</div>
</div>
</div>
<a name="section-11"></a>
<div class="section">
<h2 class="stitle">11. Reference Pages</h2>
<p>
One of the more complex block elements is
<tt><refentry></tt>. It is used to encode a compact set of
information about a command, application, or other technical
entity. There are several different ways to format a reference entry,
so we provide a <tt>role</tt> attribute to let you choose
the one that best fits your book.
</p>
<p>
There are three main types supported:
</p>
<ul>
<li>
<p>
Default
</p>
</li>
<li>
<p>
Nutshell
</p>
</li>
<li>
<p>
Java
</p>
</li>
</ul>
<a name="section-1.1"></a>
<div class="ssection">
<h3 class="sstitle">11.1. Default Reference Pages</h3>
<p>
Here are three examples of common reference pages used in DocBook Lite:
</p>
<div class="figure">
<h4 class="figuretitle">Figure 1.
A refentry from <i>Samba</i>, Appendix C
</h4>
<image src="figs/ref1.gif"></image>
</div>
<div class="example">
<h4 class="exampletitle">Example 1. How the above refentry is coded</h4>
<div class="programlisting">
<pre><refentry>
<refmeta>
<refmiscinfo class="allowable values">YES, NO</refmiscinfo>
<refmiscinfo class="default">NO</refmiscinfo>
</refmeta>
<refnamediv>
<refname>alternate permissions = boolean</refname>
</refnamediv>
<refsynopsisdiv>
<para>Obsolete. Has no effect in Samba 2. Files will be shown as
read-only if the owner can't write them. In Samba 1.9 and
earlier, setting this option would set the DOS filesystem read-only
attribute on any file the user couldn't read. This in turn
required the <literal>delete readonly</literal>
option.</para>
</refsynopsisdiv>
</refentry></pre>
</div>
</div>
<div class="figure">
<h4 class="figuretitle">Figure 2.
A refentry from <i>MySQL and mSQL</i>, Chapter 21
</h4>
<image src="figs/ref2.gif"></image>
</div>
<div class="example">
<h4 class="exampletitle">Example 2. How the above refentry is coded</h4>
<div class="programlisting">
<pre><refentry>
<refmeta>
<refentrytitle>DBI::do</refentrytitle>
</refmeta>
<refnamediv>
<refname>DBI::do</refname>
</refnamediv>
<refsynopsisdiv>
<synopsis>$rows_affected = $db-&gt;do($statement);
$rows_affected = $db-&gt;do($statement, \%unused);
$rows_affected =
$db-&gt;do($statement, \%unused, @bind_values);</synopsis>
<para><literal>DBI::do</literal> directly performs a
non-<literal>SELECT</literal> SQL statement and
returns the number of rows affected by the statement. This is
faster than a <literal>DBI::prepare/DBI::execute
</literal>pair which requires two function calls. The
first argument is the SQL statement itself. The
second argument is unused in DBD::mSQL and DBD::mysql,
but can hold a reference to a hash of attributes for other
DBD modules. The final argument is an array of values used
to replace `placeholders,' which are indicated with a
`?' in the statement. The values of the array are
substituted for the placeholders from left to right. As an
additional bonus, <literal>DBI::do</literal> will
automatically quote string values before substitution.</para>
</refsynopsisdiv>
<refsect1>
<title>Example</title>
<programlisting>use DBI;
my $db = DBI-&gt;connect('DBI:mSQL:mydata',undef,undef);
my $rows_affected =
$db-&gt;do("UPDATE mytable SET name='Joe' WHERE name='Bob'");
print "$rows_affected Joe's were changed to Bob's\n";
my $rows_affected2 =
$db-&gt;do("INSERT INTO mytable (name) VALUES (?)",
{}, ("Sheldon's Cycle"));
# After quoting and substitution, the statement:
# INSERT INTO mytable (name) VALUES ('Sheldon's Cycle')
# was sent to the database server.</programlisting>
</refsect1>
</refentry></pre>
</div>
</div>
<div class="figure">
<h4 class="figuretitle">Figure 3.
A refentry from <i>Apache: The Definitive Guide</i>,
Chapter 14
</h4>
<image src="figs/ref3.gif"></image>
</div>
<div class="example">
<h4 class="exampletitle">Example 3. How the above refentry is coded</h4>
<div class="programlisting">
<pre><refentry>
<refmeta>
<refentrytitle>ap_pstrndup</refentrytitle>
</refmeta>
<refnamediv>
<refname>ap_pstrndup</refname>
<refpurpose>duplicate a string in a pool with
limited length</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
char *ap_pstrndup(pool *p, const char *s, int n)</synopsis>
<para>Allocates <literal>n</literal>+1 bytes
of memory and copies up to <literal>n</literal>
characters from <literal>s</literal>,
<literal>NULL</literal>- terminating the result.
The memory is destroyed when the pool is destroyed. Returns
a pointer to the new block of memory, or
<literal>NULL</literal> if <literal>s</literal>
is <literal>NULL</literal>.</para>
</refsynopsisdiv>
</refentry></pre>
</div>
</div>
</div>
<a name="section-1.2"></a>
<div class="ssection">
<h3 class="sstitle">11.2. Nutshell Type Reference Pages</h3>
<p>
Nutshell books use a particular kind of reference structure that
looks like this:
</p>
<div class="figure">
<h4 class="figuretitle">Figure 1.
A refentry from <i>Unix in a Nutshell</i>, Chapter 5
</h4>
<image src="figs/ref4.gif"></image>
</div>
<div class="example">
<h4 class="exampletitle">Example 1. How the above refentry is coded</h4>
<div class="programlisting">
<pre><nutlist longestterm="unseten">
<nutentry><term>alias</term>
<nutsynopsis><literal>alias</literal>
[<replaceable>name</replaceable>
[<replaceable>command</replaceable>]]</nutsynopsis>
<nutentrybody>
<para>Assign <emphasis>name</emphasis>
as the shorthand name, or alias, for
<emphasis>command</emphasis>. If
<emphasis>command</emphasis> is omitted, print the
alias for <emphasis>name</emphasis>;
if <emphasis>name</emphasis> is also
omitted, print all aliases. Aliases can be defined on the command
line, but they are more often stored in
<literal>.cshrc</literal>
so that they take effect after login. (See [cross ref deleted]
earlier in this chapter.) Alias definitions can reference
command-line arguments, much like the history list. Use
<literal>\!*</literal> to refer to all command-line
arguments, <literal>\!^</literal> for the first argument,
<literal>\!$</literal> for the last, etc. An alias
<emphasis>name</emphasis> can be any valid Unix
command; however, you lose the original command's meaning unless
you type <emphasis>\name</emphasis>.
See also <emphasis
role="bold">unalias</emphasis>.</para>
<refsect2><title>Examples</title>
<para>Set the size for <literal>xterm</literal>
windows under the X Window System:</para>
<programlisting>alias R 'set noglob; eval `resize`;
unset noglob'</programlisting>
<para>Show aliases that contain the string
<emphasis>ls</emphasis>:</para>
<programlisting>alias | grep ls</programlisting>
<para>Run <literal>nroff</literal>
on all command-line arguments:</para>
<programlisting>alias ms 'nroff -ms \!*'</programlisting>
<para>Copy the file that is named as the first argument:</para>
<programlisting>alias back 'cp \!^ \!^.old'</programlisting>
<para>Use the regular <literal>ls</literal>,
not its alias:</para>
<programlisting>% <userinput>\ls
</userinput></programlisting>
</refsect2>
</nutentrybody>
</nutentry>
</nutlist></pre>
</div>
</div>
</div>
<a name="section-1.3"></a>
<div class="ssection">
<h3 class="sstitle">11.3. Java Type Reference Pages</h3>
<p>
This example shows how Java <tt><refentry></tt>s
look:
</p>
<div class="figure">
<h4 class="figuretitle">Figure 1.
A refentry from <i>Java Fundamental Classes in a
Nutshell</i>, Chapter 32.
</h4>
<image src="figs/ref5.gif"></image>
</div>
<div class="example">
<h4 class="exampletitle">Example 1. How the above refentry is coded</h4>
<div class="programlisting">
<pre><refentry role="java"
id="java.io.dataoutputstream">
<refmeta>
<refmiscinfo class="version">Java 1.0</refmiscinfo>
<refmiscinfo class="package">java.io</refmiscinfo>
<refmiscinfo class="flags">PJ1.1</refmiscinfo>
</refmeta>
<refnamediv>
<refname>DataOutputStream</refname>
</refnamediv>
<refsect1 role="intro">
<para>This class is a subclass of
<literal>FilterOutputStream</literal> that allows
you to write Java primitive data types in a portable binary
format. Create a <literal>DataOutputStream</literal>
by specifying the <literal>OutputStream</literal>
that is to be filtered in the call to the constructor.
<literal>DataOutputStream</literal> has methods
that output only primitive types; use
<literal>ObjectOutputStream</literal> to output object
values. </para>
</refsect1>
<refsynopsisdiv>
<classsynopsis keyword="class">
<modifiers>public</modifiers>
<classname>DataOutputStream</classname>
<extends><classref package="java.io"
class="FilterOutputStream"/></extends>
<implements><classref
package="java.io" class="DataOutput"/></implements>
<members><title>Public Constructors</title>
<membergroup>
<funcprototype revision="" role="method" flags="">
<funcdef><modifiers>public</modifiers>
<function>DataOutputStream</function>
</funcdef>
<paramdef>
<type><classref role="includePkg"
package="java.io" class="OutputStream"/></type>
<parameter>out</parameter>
</paramdef>
</funcprototype>
</membergroup>
</members>
<members><title>Public Instance Methods</title>
<membergroup>
<funcprototype revision="" role="method" flags="">
<funcdef><modifiers>public final</modifiers>
<type>int</type>
<function>size</function>
</funcdef>
</funcprototype>
</membergroup>
</members>
<members><title>Methods Implementing
<classref package="java.io" class="DataOutput"/></title>
<membergroup>
<funcprototype revision="" role="method" flags=" synchronized">
<funcdef><modifiers>public</modifiers> <type>void</type>
<function>write</function>
</funcdef>
<paramdef><type>int</type> <parameter>b</parameter></paramdef>
<throws><classref package="java.io" class="IOException"/></throws>
</funcprototype>
</membergroup>
<membergroup>
<funcprototype revision="" role="method" flags=" synchronized">
<funcdef><modifiers>public</modifiers> <type>void</type>
<function>write</function>
</funcdef>
<paramdef>
<type>byte[&thinsp;]</type> <parameter>b</parameter></paramdef>
<paramdef><type>int</type> <parameter>off</parameter></paramdef>
<paramdef><type>int</type> <parameter>len</parameter></paramdef>
<throws><classref package="java.io" class="IOException"/></throws>
</funcprototype>
</membergroup>
<membergroup>
<funcprototype revision="" role="method" flags="">
<funcdef><modifiers>public final</modifiers> <type>void</type>
<function>writeBoolean</function>
</funcdef>
<paramdef><type>boolean</type> <parameter>v</parameter></paramdef>
<throws><classref package="java.io" class="IOException"/></throws>
</funcprototype>
</membergroup>
<membergroup>
<funcprototype revision="" role="method" flags="">
<funcdef><modifiers>public final</modifiers> <type>void</type>
<function>writeByte</function>
</funcdef>
<paramdef><type>int</type> <parameter>v</parameter></paramdef>
<throws><classref package="java.io" class="IOException"/></throws>
</funcprototype>
</membergroup>
<membergroup>
<funcprototype revision="" role="method" flags="">
<funcdef><modifiers>public final</modifiers> <type>void</type>
<function>writeInt</function>
</funcdef>
<paramdef><type>int</type> <parameter>v</parameter></paramdef>
<throws><classref package="java.io" class="IOException"/></throws>
</funcprototype>
</membergroup>
</members>
<members><title>Public Methods Overriding <classref package="java.io"
class="FilterOutputStream"/></title>
<membergroup>
<funcprototype revision="" role="method" flags="">
<funcdef><modifiers>public</modifiers> <type>void</type>
<function>flush</function>
</funcdef>
<throws><classref package="java.io" class="IOException"/></throws>
</funcprototype>
</membergroup>
</members>
<members>
<title>Protected Instance Fields</title>
<membergroup>
<funcprototype revision="" role="field" flags="">
<funcdef><modifiers>protected</modifiers> <type>int</type>
<function>written</function>
</funcdef>
</funcprototype>
</membergroup>
</members>
</classsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Hierarchy</title>
<para>
<literal><classref package="java.lang" class="Object"/> &rarr;
<classref role="includePkg" package="java.io"
class="OutputStream"/> &rarr; <classref package="java.io"
class="FilterOutputStream"/> &rarr; <classref role="includePkg"
package="java.io" class="DataOutputStream"/> (<classref
package="java.io" class="DataOutput"/>)</literal></para>
</refsect1>
</refentry></pre>
</div>
</div>
</div>
</div>
<a name="section-12"></a>
<hr>
<span class="footertitle">Written by:</span>
<br>
<b>Erik Ray <i><a href="mailto:eray@oreilly.com">eray@oreilly.com</a></i>
<br>
</b>
</body>
</html>