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 <chapter> can contain a <para> (paragraph), but cannot contain a <book>.
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 the OASIS SGML/XML standards group, 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.
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.
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.
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.
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.
nsgmls is written and maintained by James Clark and is available for free from his web page.
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:
<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>
Sometimes, people choose to do this with another kind of list:
<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>
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.
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:
For more information, you really ought to check out the W3C's website at http://www.w3.org/.
The correct way to mark up this passage is like this:
<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>
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:
For more information, you <emphasis>really</emphasis> ought to check out the W3C's website at <emphasis>http://www.w3.org/</emphasis>.
The author thought that because <emphasis> causes its contents to be formatted in italic, it's okay to label everything that comes out in italic as a <emphasis>. So what? Well, it becomes a problem when you want to repurpose 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.
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:
| element | filename | purpose |
|---|---|---|
| <book> | book.xml |
Contains the DOCTYPE declaration, declares local entities in the internal subset, holds metadata, contains file reference entities to chapters and other external elements. |
| <copyrightpg> | copy.xml |
Contains the copyright page with legal info. |
| <preface> | ch00.xml |
Contains the preface. |
| <chapter> |
chxx.xml, where xx is the number of the chapter (e.g. 01, 04, 11) |
Contains a chapter. |
| <appendix> |
appx.xml, where x is the letter of the appendix (e.g. a, b, c) |
Contains an appendix. |
| <bibliography> | biblio.xml |
A chapter-level section containing bibliographic citations. |
| <glossary> | gloss.xml |
A chapter-level section containing glossary definitions. |
| <part> |
partx.xml, where x is the number of the part (e.g. 1, 2, 3) |
Contains a part (the first page only). |
| <colophon> | colo.xml |
A section at the end of the book describing details of the book's production. |
So a typical directory listing for a book would look something like this:
$> 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
There is one master file for the book (book.xml); 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 <part> elements logically contain <chapter>s.
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 <title> and contains other divisions or block elements. We will look at top-level containers (<book>, <chapter>, <preface>, <appendix>, and <part>), and intermediate-level divisions (<sect1>, <sect2>, <sect3>, <sect4>, <simplesect>, and <partinfo>).
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:
<chapter id="intro-chapter">
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, id="shapes-section" is better than id="A6-4.2".
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:
| element | pattern | example |
|---|---|---|
| appendix | prefix-APP-letter | MONKEYS-APP-B |
| chapter | prefix-CH-num | MONKEYS-CH-3 |
| preface | prefix-PREF | MONKEYS-PREF |
| part | prefix-PART-num | MONKEYS-PART-2 |
| sect1 (A-head or section) | prefix-CH/APP-num/letter-SECT-num | MONKEYS-CH-3-SECT-2 |
| sect2 (B-head or sub section) | prefix-CH/APP-num/letter-SECT-num.num | MONKEYS-CH-3-SECT-2.4 |
| figure | prefix-CH/APP-num/letter-FIG-num | MONKEYS-PREF-FIG-24 |
| table | prefix-CH/APP-num/letter-TABLE-num | MONKEYS-APP-C-TABLE-11 |
| example | prefix-CH/APP-num/letter-EX-num | MONKEYS-CH-12-EX-8 |
| indexterm | prefix-terms | MONKEYS-perilous-furballs |
The prefix is a short code you pick to represent your book in ids. 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.
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.
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 <bookinfo> 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.
<!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;
©
&part1;
&part2;
&colo;
</book>
In this example, none of the external entity references for chapters and appendixes appear in book.xml. 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.
The preface is contained entirely within one file called ch00.xml. It looks like this:
<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>
A <part> 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:
<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>
No entity declarations are necessary because they were made in the book.xml file and carried over. The <partinfo> is an intermediate-level division that contains all elements between the <title> and the chapter-level children of the <part>.
Chapters follow the same basic pattern as a preface:
<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>
The hierarchy of sections is important. A <sect1> contains <sect2>s, which can contain <sect3>s, etc. Also important: we now require that elements after the chapter <title>, but before the first <sect1>, be enclosed in a <simplesect>.
Appendixes are pretty much the same as chapters, except that they are contained in an <appendix> element instead of a <chapter>, and the id format is different.
A glossary is a collection of definitions for terms used in the book. A <glossary> element surrounds the whole thing, and is usually at the same level as a chapter. Each definition is contained in a <glossentry> element with one <glossentry>, containing the term being defined, and an optional (if there is a see-also, for example) <glossdef>, containing the definition. It can also contain any number of <glosssee> and <glossseealso> elements, which redirect the reader's attention to another term. Stylistically, a <glossentry> should not contain both a <glossdef> and <glosssee>, but a <glossdef> and <glossseealso> are okay.
A glossary looks like this:
<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>
Coming soon...
A block element is any element that starts a new line when formatted and contains inline elements. We have seen three already: <para>, <title>, and <figure>. Following is a table of block elements with examples:
| element | purpose | example |
|---|---|---|
| <para> | Paragraph. |
<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> |
| <title> | Title. |
<title>The Benefits of Laughter</title> |
| <comment> |
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. |
<comment>This section is too short and needs more examples. [Ellen]</comment> |
| <blockquote> | Quotation. |
<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> |
| <itemizedlist> |
A list of items where order doesn't matter. |
<itemizedlist> <listitem><para>dogsled</para></listitem> <listitem><para>hang-glider</para></listitem> <listitem><para>roller blades</para></listitem> </itemizedlist> |
| <orderedlist> |
A list of items where order is important. |
<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> |
| <variablelist> |
A list that contains terms and their definitions. |
<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>
|
| <programlisting> |
A piece of computer code or example markup where whitespace and other formatting must be preserved. |
<programlisting>public void init(ServletConfig config)
throws ServletException {
super.init(config);
String greeting = getInitParameter("greeting");
}</programlisting>
|
| <screen> |
A representation of data displayed on a computer screen. (Whitespace and other formatting are preserved.) |
<screen>> ls -l total 6860 -r--r--r-- 1 jliggett ora 2570 Mar 27 19:38 BOOKFILES -rw-rw-r-- 1 jliggett ora 103283 Mar 27 19:38 BOOKIDS -rw-rw-r-- 1 bsalter ora 2692 Mar 28 14:43 Makefile drwxrwxr-x 2 bsalter ora 512 Aug 10 14:22 RCS/ -rw-rw-r-- 1 jliggett ora 39 Jul 26 17:39 README.txt</screen> |
| <literallayout> |
Traditional text with special linebreaks to be preserved. |
<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>
|
| <figure> |
A graphic with a title. |
<figure id="FOO-APP-E-FIG-19"> <title>The garden variety eggplant</title> <graphic fileref="figs/eggplant.eps"/> </figure> |
| <example> |
Anything that serves as an example and requires a title. (Use an <informalexample> if you don't need a title.) |
<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> |
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.
| element | purpose | example |
|---|---|---|
| <abbrev> | An abbreviated term. |
She's in <abbrev>bldg</abbrev 42.> |
| <accel> | A shortcut. |
Type <accel>Ctl-s</accel> to search for a term. |
| <acronym> |
Mark text as being an acronym. |
<acronym>ASCII</acronym> |
| <action> |
A user interface action like a mouse click. |
Click <action>mouse button-3</action> for a pop-up menu. |
| <application> |
The name of a computer software program. |
We can convert any document written in <application>Microsoft Word</application>. |
| <citation> |
The source of a quote or piece of information. |
<citation>Bill Gates</citation> once said <quote>256 kB of RAM ought to be good enough for anybody.</quote> |
| <citetitle> |
The name of a book or article. |
<citetitle>The Hobbit</citetitle> |
| <classname> |
An identifier for a class in some programming language. |
The <classname>string</class> class has six public methods. |
| <classref> |
A cross reference to a class, with special formatting such as displaying the class name. (Used mainly in Java books.) |
|
| <command> |
Any command one would type in a computer terminal. |
To print the file to screen, use the <command>lpr</command> command. |
| <computeroutput> |
Text that would be output by a computer program. |
When we run the script we get the result <computeroutput>file not found</computeroutput>. |
| <email> |
An email address. (Note that there may be some conflict with the <systemitem> element.) |
Send questions to <email>tools@oreilly.com</email>. |
| <emphasis> |
Give special emphasis to a word or phrase. Usually this formats as italic, but default formatting can be overridden with a role attribute such as role="bold". |
This step is <emphasis>very</emphasis> important |
| <envar> | An environment variable. |
Set the variable <envar>EDITOR</envar> to <literal>emacs</literal>. |
| <filename> | Tags a word as being a filename. |
Be sure to read <filename>readme.txt</filename>. |
| <firstterm> |
The first time an important term is mentioned. |
A <firstterm>squib</firstterm> is someone born to a wizard family but who can't do magic. |
| <foreignphrase> | Words from another language. |
There's nothing wrong with borrowing code <foreignphrase>per se<foreignphrase>. |
| <footnoteref> |
A marker that imports a <footnote> where there would otherwise be a redundant footnote definition. |
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">. |
| <graphic> |
An icon or picture to be imported into the document. |
Examples marked with a disk icon <graphic fileref="figs/icon.eps"> are on the companion disk. |
| <function> |
The name of a function, method, or subroutine. |
The function <function>alpha_sort</function> can be made more efficient. |
| <guibutton> |
A clickable control (e.g. a button) in a graphical interface. |
Select the <guibutton>print<guibutton> button to get hardcopy. |
| <guimenu> |
A menu or submenu in a graphical interface. |
Close the program by selecting <guimenuitem>exit</guimenuitem> from the <guimenu>file</guimenu> menu. |
| <guimenuitem> |
An item in a menu or submenu in a graphical interface. |
Close the program by selecting <guimenuitem>exit</guimenuitem> from the <guimenu>file</guimenu> menu. |
| <keycap> |
A character to be represented as a key on a keyboard. |
Pressing <keycap>s</keycap> will save the buffer to a file. |
| <keysym> | ||
| <lineannotation> |
An annotation appearing inside a <screen> or <programlisting>. |
for( int $i=0; $i<10; $i++ ) {
<lineannotation>body of loop</lineannotation>
}
|
| <literal> |
A token or string that is part of a computer program or script, which should be formatted in constant width. |
If the parameter's value is <literal>YELLOW</literal> your subroutine will explode. |
| <option> |
A code to apply an optional parameter to a command, program, or function. |
The command synopsis is <command>rm <option>-i</option> *.txt</command>. |
| <optional> |
Designates some text as an optional item. |
The stylesheet specification is optional: <command>formatfiles <optional>stylesheet</optional> in.xml<command>. |
| <parameter> |
The name of a parameter for a function, method, or subroutine. |
In the <function>factorial</function> function, there is only one parameter, <parameter>num</parameter>. |
| <prompt> |
A word meant to appear as a prompt in a computer display. |
At the prompt <prompt>Data?</prompt>, type in your age in hexadecimal. |
| <quote> |
Quoted text. |
Our motto is <foreignphrase>Caveat Emptor</foreignphrase>, which means <quote>we hope you like it!</quote> |
| <replaceable> |
Marks the data as a replaceable item, a value to be filled in. |
...where <replaceable>w</replaceable> is the width. |
| <returnvalue> |
Data that has been returned from a program or function. |
The <function>reverse_string</function> gives the value <returnvalue>tesolcmoorb</returnvalue>. |
| <sgmltag> |
The name of an SGML or XML element. |
The <sgmltag>P</sgmltag> element adds space above and below. |
| <structfield> |
The name of a field in a data structure. |
<structfield>name</structfield> is a fixed array of bytes. |
| <structname> |
The name of a data structure. |
To add a record, we must create a new <structname>PartStruct</structname>. |
| <subscript> |
Text that should be rendered in subscript (smaller and below the baseline). |
The molecule H<subscript>2</subscript>O has many strange properties. |
| <superscript> |
Text that should be rendered in superscript (smaller and above the midline). |
Einstein revolutionized physics with the simple equation E=MC<superscript>2</superscript> |
| <symbol> |
A special symbol or token. |
The mutant gene <symbol>BLu-6</symbol> is responsible for Smurfs' vivid azure hue. |
| <systemitem> |
Designates data as a special item having to do with computers or networks. Most common use is to encode a URL. |
<systemitem class="url">http://www.oreilly.com</systemitem> |
| <type> |
A variable or constant data type. |
The function returns a value of type <type>boolean</type>. |
| <userinput> |
Text entered by a human into a computer terminal. |
At the command line, type <userinput>telnet bubba.beerguzzlin.org</userinput> |
| <wordasword> |
A word used as an example. |
By <wordasword>snake</wordasword>, I mean <quote>dirty, stinkin' varmint</quote>. |
| <xref> |
A cross reference to some element in the book. The required linkend attribute contains the id of the element being referenced. |
For more information, refer to <xref linkend="XYZ-CH-4"/>. |
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: <table>, which requires a title, and <informaltable>, which does not. These elements contain a <tgroup> element with an attribute cols that specifies the number of columns in the table.
The table has a head, body, and foot, contained in <thead>, <tbody>, and <tfoot> elements, respectively. Only the body is required. The head and body contain a set of rows, each a <row> element. The foot contains text that will appear just below the table, usually within the lines.
A <row> element contains some number of <entry>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:
<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>
To span a row, add to the <entry> element an attribute morerows="N", where N is the number of rows to span beyond the current row. For example, to make an entry that spans 3 rows, use morerows="2". For each of the following rows that are spanned, leave out an <entry> element, since the spanning cell will inhabit that space.
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:
<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>
We generate indexes for books automatically, with the data originating in <indexterm> 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:
<indexterm id="ixt-blather-frobozz-zmic"> <primary>blather</primary> <secondary>frobozz</secondary> <tertiary sortas="@">zmic</tertiary> <seealso>fuj</seealso> </indexterm>
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:
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
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.
To create a term that spans a segment of text, you use two <indexterm> elements linked by an id-startref attribute pair and class attributes. For example:
<!-- 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"/>
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.
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:
<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>
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:
<caution> <para>Make sure your craft has reached the surface before unsealing the hatch. Otherwise, high-pressure water will flood the compartment.</para> </caution>
An admonition can appear in any section but cannot contain sections. Try to keep its content simple, using only paragraphs and lists if possible.
A <footnote> is coded as a block that interrupts a paragraph. It can look a little odd:
<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>...
When the same footnote applies to different places in a document, you can use a <footnoteref> element to reference it. The following example shows how:
<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>
In some cases, you want a footnote's text to appear in another section or chapter. The <endnote> element serves that function. It also stores the body of the note elsewhere. For example:
<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>
One of the more complex block elements is <refentry>. 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 role attribute to let you choose the one that best fits your book.
There are three main types supported:
Default
Nutshell
Java
Here are three examples of common reference pages used in DocBook Lite:
<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>
<refentry>
<refmeta>
<refentrytitle>DBI::do</refentrytitle>
</refmeta>
<refnamediv>
<refname>DBI::do</refname>
</refnamediv>
<refsynopsisdiv>
<synopsis>$rows_affected = $db->do($statement);
$rows_affected = $db->do($statement, \%unused);
$rows_affected =
$db->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->connect('DBI:mSQL:mydata',undef,undef);
my $rows_affected =
$db->do("UPDATE mytable SET name='Joe' WHERE name='Bob'");
print "$rows_affected Joe's were changed to Bob's\n";
my $rows_affected2 =
$db->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>
<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>
Nutshell books use a particular kind of reference structure that looks like this:
<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>
This example shows how Java <refentry>s look:
<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[ ]</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"/> →
<classref role="includePkg" package="java.io"
class="OutputStream"/> → <classref package="java.io"
class="FilterOutputStream"/> → <classref role="includePkg"
package="java.io" class="DataOutputStream"/> (<classref
package="java.io" class="DataOutput"/>)</literal></para>
</refsect1>
</refentry>
For a simpler markup language better suited for general-purpose documentation, try out SimpleDoc.