Using Elements Correctly

For XML be valid, it must not only be well-formed (i.e., all the start and end tags match), it must also have all the tags in the proper hierarchy according to the associated DTD. The tag at the top of the hierarchy is called the root element (e.g., <chapter>s or <part>s) and contains various child elements (e.g., <sect1>). Logical rules apply, such as the fact that a <sect3> cannot be directly nested within a <sect1>; it must be within a <sect2>. Improper nesting will result in invalid DocBook.

The terms tag and element are sometimes used interchangeably, but there is a distinction. For example, <chapter> is a tag that indicates the start of a chapter element. For the XML document to be well-formed, it must contain an end tag, </chapter>. Some tags are self-contained and stand alone as complete elements, without the need for separate end tags. For example, <xref linkend="foo"/> is self-contained. If you’re familiar with HTML, the rules are pretty much the same.

Chapters and Sections

Each .xml file should be a complete DocBook document with its own DOCTYPE declaration.

Each chapter is made up of sections. We recommend using sect1, sect2, and sect3 elements rather than generic section elements to structure your chapter.

The barebones structure of a chapter is something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="chapter_id">
  <title>Chapter Title Here</title>
  <sect1>
    <title>Sect1 Title Here</title>
    <para>Text goes here...</para>
    <sect2>
      <title>Sect2 Title Here</title>
      <para>Text goes here...</para>
      <sect3>
        <title>Sect3 title here</title>
        <para>Text goes here...</para>
      </sect3>
    </sect2>
  </sect1>
</chapter>

<chapterinfo>
  <author>
    <firstname>Author</firstname>
    <surname>Name</surname>
  </author>
</chapterinfo>

Parts

Parts are files that group chapters together. Note that the chapters should be in their own files. Atlas will take care of the nesting based on the order specified in the Build List.

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<part>
<title>Part 1</title>
</part>

Block Versus Inline Elements

There are two kinds of elements:

Block

Usually presented with a paragraph break before and after them, block elements may contain character data, inline elements, and possibly other block elements. Examples include paras, lists, sidebars, tables, and block quotes.

Inline

Usually distinguished by a font change rather than obvious breaks, inline elements may contain character data and possibly other inline elements, but never block elements. Examples include cross-references, filenames, commands, and URLs.

Inline Font Markup

Here are some commonly used inline elements:

<emphasis>

Provided for use where you would traditionally use italics to emphasize a word or phrase.

<emphasis role="bold">

A general-purpose tag provided for where you would use bold type to emphasize a word or phrase.

Warning

O'Reilly house style prefers italic rather than bold for emphasis.

<phrase role="roman">

Provided for use within italicized text where you would ordinarily use italics to emphasize a word or phrase.

<literal>

Any stretch of text that must appear in constant width font.

<replaceable>

Text that should be replaced with user-supplied values or by values determined by context. Appears in constant width italic.

<subscript>

A subscript character.

<superscript>

A superscript character.

<ulink url="ulink.org"/>

Adding a hyperlink. See Hyperlinks for more details. (For fake or example URLs, use <emphasis> instead.)

<userinput>

Data entered by the user, typically at a prompt line. Use with <replaceable> if needed: <userinput><replaceable>...</replaceable><userinput>

Cross-References

All cross-references to titled elements—figures, tables, examples, sections, chapters, parts, etc.—should be marked up using xrefs, not written in plain text. xref elements will become live hyperlinks in online versions, and they will automatically update if you move the referenced elements around while editing. There is never any need to hardcode labels (e.g., “Chapter 1”, “Figure 1”) or page numbers, as these aspects of the rendered xref are autogenerated by Atlas.

To insert an xref, follow these steps:

1. Note the id of the element you are referencing. If the element does not have an id, you will need to add one. For the project to be valid, id attributes must be unique across the entire project, have no spaces, not contain a colon, and not start with a number. Here’s an example of a figure id:

   <figure id="figure_titles_written_with_underscores_make_nice_ids">

2. Once you have the id, you can insert an xref element that references it via a linkend attribute, like so:

   <xref linkend="figure_titles_written_with_underscores_make_nice_ids" />

The following table shows examples of xref markup and standard rendering for various elements.

Figures

Figures generally have a title (aka caption) and an autogenerated number. You do not need to number the figure in the XML; Atlas will autogenerate the number in the figure label and in all xrefs to it. If you'd prefer that your image not be numbered or labeled, simply omit the id attribute and title element.

Here’s an example of formal figure markup:

<figure id="docbook_duck_fig">
<title>The DocBook duck</title>
<mediaobject>
  <imageobject>
    <imagedata fileref="images/docbook_duck.png" format="PNG" />
  </imageobject>
</mediaobject>
</figure>

Figure 8-1 shows how the above markup renders.

Make sure to add your image files to the project (typically in an images/ directory). Then set the fileref and format attributes in the XML markup so that they match the image file names and types exactly. For example, if an image is named battery.png in the images/ directory, it should be referenced in the XML as images/battery.png, not images/Battery.png, and the format should be PNG.

<inlinemediaobject>
   <imageobject>
      <imagedata fileref="images/icons_0501.png"/>
   </imageobject>
</inlinemediaobject>

<figure id="figure_with_custom_alt_text">
  <title>Figure image with custom alt text</title>

  <mediaobject>
    <imageobject>
      <imagedata fileref="images/universal_design_for_web_applications_cover.png"/>
    </imageobject>

    <textobject>
      <phrase>Universal Design for Web Applications Cover</phrase>
    </textobject>
  </mediaobject>
</figure>

<informalfigure id="informalfigure_with_custom_alt_text">
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/universal_design_for_web_applications_cover.png"
                    width="2.4in"/>
    </imageobject>

    <textobject>
      <phrase>Universal Design for Web Applications Cover</phrase>
    </textobject>
 </mediaobject>
</informalfigure>

<inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/oreilly_logo.png" width="0.12in"/>
  </imageobject>
  <textobject>
    <phrase>O’Reilly Media, Inc. logo</phrase>
  </textobject>
</inlinemediaobject>

Tables

If your table requires a description, you expect to refer to it later elsewhere in the text, or it’s especially complex, you probably want to use a table element. Otherwise, you can consider using an informaltable.

<table id="example_table">
<title>Example formal table</title>
  <tgroup cols="2">
    <thead>
      <row>
        <entry>Heading1</entry>
        <entry>Heading2</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Text1</entry>
        <entry>Text2</entry>
      </row>
      <row>
        <entry>Text3</entry>
        <entry>Text4</entry>
      </row>
    </tbody>
  </tgroup>
</table>

<table id="example_table">
  <tgroup cols="2">
    <tbody>
      <row>
        <entry>Text1</entry>
        <entry>Text2</entry>
      </row>
      <row>
        <entry>Text3</entry>
        <entry>Text4</entry>
      </row>
    </tbody>
  </tgroup>
</table>

Lists

There are four common types of lists. Here’s the markup and an example of each.

<simplelist>
  <member>This is a list of several short items.</member>
  <member>Usually one or a few words each.</member>
</simplelist>

<itemizedlist>
  <listitem><para>This is a list.</para></listitem>
  <listitem><para>With bullets.</para></listitem>
<itemizedlist>

<orderedlist>
  <listitem><para>This list uses numbers.</para></listitem>
  <listitem><para>Instead of bullets.</para></listitem>
<orderedlist>

<orderedlist continuation="continues">

<variablelist>
  <varlistentry>
    <term>The first part could be a term</term>
    <listitem><para>Followed by a definition.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Or a name</term>
    <listitem><para>Followed by a description. Etc.</para></listitem>
  </varlistentry>
</variablelist>

<term role="plain">Variable list term</term>

Notes, Tips, Warnings, and Cautions

Admonitions are great for adding supplemental information or warnings to the reader.

The markup for a note looks like this:

<note>
  <para>Here's some text inside a note.</para>
</note>

It will render something like this:

You can create a tip like this:

<tip>
  <para>If you tie your shoelaces, you're less likely to trip and fall down.</para>
</tip>

Which looks something like this:

You can also use a warning:

<warning>
  <para>Be warned of something important!</para>
</warning>

Which looks something like this:

Notes, tips, and warnings may contain paras, code blocks, and lists. They should not contain figures, tables, or examples.

Sidebars

Sidebar markup looks like this:

<sidebar>
  <title>When to Use a Sidebar?</title>
  <para>If a note, tip, or warning covers a lot of information or includes complex elements, consider using a sidebar instead. A sidebar can be much longer—even spanning several pages—and should have a title.</para>
</sidebar>

And renders something like this:

Hyperlinks

The DocBook element for URLs is ulink. Here’s an example:

<para><ulink url="http://www.macports.org">MacPorts</ulink> is a great tool for 
installing open source software on OS X.</para>

In the web PDF you build in Atlas, the hyperlink will be clickable:

In the print PDF, the URL will render in parentheses following the text by default:

So you won't need to do something like this:

<para>Macports (<ulink url="http://www.macports.org"/>) is a great tool for 
installing open source software on OS X.</para>

When you create ulinks, make sure the url attribute contains a full URL, including the protocol—e.g., use http://www.macports.org instead of www.macports.org. The ulink is not valid without the protocol.

Footnotes

A footnote generates a superscript number wherever it is placed in the text, and the body of the footnote appears at the bottom of the page.¹

<footnote><para>Like this.</para></footnote>

Table footnotes are lettered and appear directly after the table (not at the bottom of the page).

Indexing

Here’s the basic index entry markup:

<indexterm><primary>index entry syntax, level 1</primary></indexterm>

Secondary entry (subentry) markup:

<indexterm>
    <primary>index entry syntax</primary>
    <secondary>for a subentry</secondary>
</indexterm>

Tertiary entry (sub-subentry) markup:

<indexterm>
    <primary>index entry syntax</primary>
    <secondary>for a subentry</secondary>
    <tertiary>with a subentry</tertiary>
</indexterm>

Index entry with a range markup:

This book is full of geeky text with DocBook XML markup, which starts here:
<indexterm class="startofrange" id="geekytext">
<primary>geeky DocBook XML text</primary></indexterm>blah blah blah Ajax
blah blah blah Ruby on Rails
...
and ends here<indexterm class="endofrange" startref="geekytext"/>.

Code

Code blocks can be defined in DocBook with a programlisting element. Here’s a very simple one:

<programlisting>Hello World</programlisting>

If you have larger blocks of code that you want to give a title, a number, and a cross-reference, use an example element:

<example id="sample_example">
<title>Sample example</title>
  <programlisting>Hello World</programlisting>
</example>

programlisting is a verbatim environment, which means whitespace is preserved in rendered versions. You must escape all characters that have special meaning in XML (such as < and >—these characters obviously come up quite a bit in code). The simplest way to do this is to replace the character with an entity, such as > for >.

<programlisting>
<xi:include 
  xmlns:xi="http://www.w3.org/2001/XInclude" 
  parse="text" href="hello.c" />
</programlisting>

<programlisting><emphasis role="bold">GLuint m_gridTexture;
IResourceManager* m_resourceManager;
</emphasis>};</programlisting>

<programlisting><emphasis role="bold">GLuint m_gridTexture;</emphasis>
<emphasis role="bold">IResourceManager* m_resourceManager;</emphasis>
};</programlisting>

<programlisting>
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
locationManager.delegate = self;
    [locationManager startUpdatingLocation];
} else {
    NSLog(@"Location services not enabled.");
}
</programlisting>

<programlisting>CLLocationManager *locationManager = [[CLLocationManager alloc] init];
locationManager.delegate = self;
    [locationManager startUpdatingLocation];
} else {
    NSLog(@"Location services not enabled.");
}</programlisting>

<programlisting><programlisting> <co id="opening_tag_co"
          linkends="opening_tag" />
<xi:include <co id="xinclude_co" linkends="xinclude" /> 
  xmlns:xi="http://www.w3.org/2001/XInclude" 
  parse="text" href="hello.c" />
</programlisting> <co id="closing_tag_co" linkends="closing_tag" />
      
<calloutlist>
  <callout arearefs="opening_tag_co" id="opening_tag">
    <para>The opening tag for a <literal>programlisting</literal> element.</para>
  </callout>

  <callout arearefs="xinclude_co" id="xinclude">
    <para>An <literal>XInclude</literal>.</para>
  </callout>

  <callout arearefs="closing_tag_co" id="closing_tag">
    <para>The closing tag for a <literal>programlisting</literal> element.</para>
  </callout>
</calloutlist></programlisting>

<programlisting> 
<xi:include  
  xmlns:xi="http://www.w3.org/2001/XInclude" 
  parse="text" href="hello.c" />
</programlisting> 

<programlisting>&lt;programlisting&gt; <co id="opening_tag_co" 
  linkends="opening_tag"/>
&lt;xi:include <co id="xinclude_co" linkends="xinclude"/> 
  xmlns:xi="http://www.w3.org/2001/XInclude" 
  parse="text" href="hello.c" /&gt;
&lt;/programlisting&gt; <co id="closing_tag_co" linkends="closing_tag"/>
</programlisting>

<calloutlist>
<callout arearefs="opening_tag_co" id="opening_tag">
<para>The opening tag for a <literal>programlisting</literal>
element.</para>
</callout>

<callout arearefs="xinclude_co" id="xinclude">
<para>An <literal>XInclude</literal>.</para>
</callout>

<callout arearefs="closing_tag_co" id="closing_tag">
<para>The closing tag for a <literal>programlisting</literal>
element.</para>
</callout>
</calloutlist>

<programlisting language="java">int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;</programlisting>

int radius = 40;
float x = 110;
float speed = 0.5;
int direction = 1;

Unicode for Special Characters

For nonstandard characters, use Unicode. The following table provides the values for some common characters; for all others, check out the Unicode Char⁠acter Search.

To add a Unicode character directly to XML in a text editor, use the entity &#xCODEPOINT;, where CODEPOINT is the four-digit hexadecimal number after U+ (e.g., for U+20A0, enter ₠). Letters that are part of the codepoint may be entered as either upper- or lowercase (i.e., λ is the same as λ), but the x between the # symbol and the codepoint must be lowercase.

Comments and Remarks

You have two options for adding comments to your manuscript: standard XML comments (<!--foo-->) and remark elements.

XML comments are useful for commenting out large blocks of text—for example, text that is under review, or text that you don’t currently want to include in your manuscript. In the following example, the entire paragraph is commented out:

<!-- O’Reilly’s mission statement. 
<para>O’Reilly Media spreads the knowledge of innovators through its books, 
online services, magazines, research, and conferences. Since 1978, O’Reilly 
has been a chronicler and catalyst of leading-edge development, homing in 
on the technology trends that really matter and galvanizing their adoption 
by amplifying “faint signals” from the alpha geeks who are creating the future. 
An active participant in the technology community, the company has a long 
history of advocacy, meme-making, and evangelism.</para> -->

remark elements are better for directing specific comments to other collaborators. For example:

<remark>PRODUCTION: Please stet grammatical errors in the following</remark>

<para>I can haz cheezburger, plz?</para>

By default, remarks are not displayed in your PDF builds.

Quotes and Epigraphs

To add a quote anywhere in your book, use the blockquote element. Since it’ll be set apart from the text, there’s no need to put quotation marks around it. Here’s some example markup—a quote attributed to Benjamin Disraeli (by Wilfred Meynell, according to Frank Muir):

<blockquote>
  <attribution>Wilfred Meynell</attribution>

  <para>Many thanks; I shall lose no time in reading it.</para>
</blockquote>

Here’s how it renders:

Many thanks; I shall lose no time in reading it.

Wilfred Meynell

If you want to add a quote at the beginning of your chapters (or sections, parts, etc.), use the epigraph element. Here’s some example markup:

<epigraph>
  <attribution>Robert Benchley</attribution>

  <para>There are two kinds of people in the world: those who believe 
  there are two kinds of people in the world, and those who don't.</para>
</epigraph>

And here’s how it renders:

There are two kinds of people in the world: those who believe there are two kinds of people in the world, and those who don’t.

Robert Benchley