DocBook rocks!

Table of Contents

1. Block Elements

1.1. Paragraphs and Line Breaks
1.2. Headers
1.3. Blockquotes
1.4. Lists
1.5. Code Blocks

2. Span Elements

2.1. Links
2.2. Emphasis
2.3. Code

3. Miscellaneous

3.1. Escaping Special Characters

4. Fancy Stuff

4.1. Prompts in Command Lines
4.2. Tables

List of Tables

3.1.
4.1.

List of Examples

1.1.
1.2.
1.3.
1.4.
1.5.
1.6.
1.7.
1.8.
1.9.
1.10.
2.1.
2.2.
2.3.
2.4.

1. Who this is for?

You want to write a page or two of documentation for your favorite DocBook-using project, and didn't find or got spooked by the extremely thorough and intimidating official documentation.

This is a quick dive in to about ten DocBook tags which will let you get going and documenting pretty much everything you need. At the end is some fancier stuff you probably won't need.

You don't have to have ever used DocBook before, or plan to ever use it again. My goal is to give you just enough knowledge to contribute some docs to your favorite DockBook-using project.

Chapter 1. Block Elements

Table of Contents

1.1. Paragraphs and Line Breaks
1.2. Headers
1.3. Blockquotes
1.4. Lists
1.5. Code Blocks

1.1. Paragraphs and Line Breaks

Example 1.1.

<para>
  your text goes here! It isn't whitespace sensitive.
  Feel free to break up your sentences in to

  as many lines

  as

  you

  like.

</para>

your text goes here! It isn't whitespace sensitive. Feel free to break up your sentences in to as many lines as you like.

1.2. Headers

DocBook automatically applies the right header for your content, based on its nesting.

Example 1.2.

<section>
  <title>This is a section!</title>
  <section>
    <title>And a sub-section!</title>
    <section>
      <title>How low can we go?</title>
      <section>
        <title>(let's not find out.)</title>
      </section>
    </section>
  </section>
</section>

1. This is a section!

1.1. And a sub-section!

1.1.1. How low can we go?

1.1.1.1. (let's not find out.)

Sometimes, you may want a subtitle. DocBook supports that!

Example 1.3.

<section>
  <title>My Cool Document</title>
  <subtitle>Publishing formats can be fun!</subtitle>
</section>

1. My Cool Document

Publishing formats can be fun!

1.3. Blockquotes

Blockqoutes are easy, and support a lot of the other elements, too:

Example 1.4.

<blockquote>
  <attribution>
    <link xlink:href="https://opensource.com/article/17/9/docbook">opensource.com</link>
  </attribution>
  <para>
    learn the basics in the first few minutes,
    and keep a reference handy to learn more
    as needed.
  </para>
</blockquote>

	learn the basics in the first few minutes, and keep a reference handy to learn more as needed.
	-- opensource.com

Note

Where the author of the quote is displayed is up to the rendering of the documentation. It is common to put the attribution first, but not necessary. If I had put the attribution after the paragraph, it would have displayed the same way.

1.4. Lists

DocBook supports bulleted and numbered lists.

Example 1.5.

<itemizedlist>
  <listitem>
    <para>
      Red
    </para>
  </listitem>
  <listitem>
    <para>
      Blue
    </para>
  </listitem>
  <listitem>
    <para>
      Green
    </para>
  </listitem>
</itemizedlist>

Red
Blue
Green

Example 1.6.

<orderedlist>
  <listitem>
    <para>
      Norman Walsh
    </para>
  </listitem>
  <listitem>
    <para>
      Jon Bosak
    </para>
  </listitem>
  <listitem>
    <para>
      Dale Dougherty
    </para>
  </listitem>
</orderedlist>

Norman Walsh
Jon Bosak
Dale Dougherty

or a list with multiple paragraphs:

Example 1.7.

<orderedlist>
  <listitem>
    <para>
      This is a list item with two paragraphs.
    </para>

    <para>
      This is the second paragraph in the list
      item, you don't have to do anything special
      here but keep adding para tags :)
    </para>
  </listitem>
  <listitem>
    <para>
      Another item in the same list.
    </para>
  </listitem>
</orderedlist>

This is a list item with two paragraphs.
This is the second paragraph in the list item, you don't have to do anything special here but keep adding para tags :)
Another item in the same list.

or a list with a blockquote:

Example 1.8.

<orderedlist>
  <listitem>
    <blockquote>
      <attribution>
        <link xlink:href="http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/x57.html">Why care about DocBook at all?</link>
      </attribution>
      <para>
        There are two possibilities that make DocBook
        really interesting. One is multi-mode
        rendering and the other is searchable
        documentation databases.
      </para>
    </blockquote>
  </listitem>
</orderedlist>

	There are two possibilities that make DocBook really interesting. One is multi-mode rendering and the other is searchable documentation databases.
	-- Why care about DocBook at all?

Note

The <listitem> can't contain text directly inside of it. If you want to include text, use a <para>. You could also use a <blockquote> or <programlisting> or many other options.

1.5. Code Blocks

Example 1.9.

<programlisting>
#!/bin/sh
git clone https://github.com/grahamc/docbook.rocks.git
</programlisting>

#!/bin/sh
git clone https://github.com/grahamc/docbook.rocks.git

Note

If you'll have a lot of <s, >s, or &s like you're embedding a bunch of XML or HTML, you'll probably want to use a CDATA section instead of escaping them all:

Example 1.10.

<programlisting><![CDATA[
<para>
  No need to escape each < > or &
</para>
]]></programlisting>

<para>
  No need to escape each < > or &
</para>

Chapter 2. Span Elements

Table of Contents

2.1. Links
2.2. Emphasis
2.3. Code

2.1. Links

DocBook supports normal URL links:

Example 2.1.

<para>
  If you're a bit freaked out by DocBook, check out
  <link xlink:href="https://docbook.rocks">DocBook
  Rocks</link> for a really gentle introduction, and
  a "just-the-basics" look at how to be productive
  with DocBook.
</para>

If you're a bit freaked out by DocBook, check out DocBook Rocks for a really gentle introduction, and a "just-the-basics" look at how to be productive with DocBook.

and also has a special method for linking within the same document:

Example 2.2.

<section>
  <section xml:id="section-one">
    <title>A nice section demonstrating linking
    inside the same document</title>
    <para>
      Definitely go check out
      <xref linkend="section-two" />!
    </para>
  </section>

  <section xml:id="section-two">
    <title>Another section, look at that!</title>
  </section>
</section>

1.1. A nice section demonstrating linking inside the same document

Definitely go check out Section 1.2, “Another section, look at that!”!

1.2. Another section, look at that!

The name <xref> may be a bit weird of a name at first. Maybe remembering it like a crossreference will help.

2.2. Emphasis

DocBook documents typically only italicize for emphasis, though this is depends on how you process your document.

Example 2.3.

<para>
  DocBook has a whole lot of tags, but you
  probably don't need them
  <emphasis>all</emphasis>. Don't be scared
  off by them if you look at the official
  documentation.
</para>

DocBook has a whole lot of tags, but you probably don't need them all. Don't be scared off by them if you look at the official documentation.

2.3. Code

To write a bit of code inside a paragraph, wrap it in <literal></literal>:

Example 2.4.

<para>
  Print to the screen with the
  <literal>printf()</literal> function.
</para>

Print to the screen with the printf() function.

Chapter 3. Miscellaneous

Table of Contents

3.1. Escaping Special Characters

3.1. Escaping Special Characters

DocBook requires the author to escape a few symbols, depending on where you are using them.

Symbol	How to type it instead	When
`<`	`<` as in less than	Everywhere in your document.
`>`	`>` as in greater than	Everywhere in your document.
`&`	`&` as in ampersand	Everywhere in your document.
`"`	`"` as in quote	Only inside attributes using a double quote, like `<foo xlink:title="a "can do" attitude!">`.
`'`	`'` as in apostrophe	Only inside attributes using a single quote, like `<foo xlink:title='it isn't impossible!'>`.

Chapter 4. Fancy Stuff

Table of Contents

4.1. Prompts in Command Lines
4.2. Tables

4.1. Prompts in Command Lines

Copy and paste the following commands:

$ git clone https://github.com/grahamc/docbook.rocks.git
$ cd docbook.rocks

You'll notice you only copied the commands, and not the prompt's $ .

Note

We've just learned about the <screen> tag. A <screen> tag is like a <programlisting> except it is intended to show the text in a terminal window.

With Markdown you might imagine having a special fenced codeblock, like

```shell-commands
git clone https://github.com/grahamc/docbook.rocks.git
cd docbook.rocks
```

and having it automatically prefix the lines with an unselectable $ . This would be interesting, but undesirable because you wouldn't want

```shell-commands
git clone https://github.com/grahamc/docbook.rocks.git
Cloning into 'docbook.rocks'...
remote: Counting objects: 52, done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 52 (delta 19), reused 48 (delta 15), pack-reused 0
Unpacking objects: 100% (52/52), done.
```

to turn in to

```shell-commands
$ git clone https://github.com/grahamc/docbook.rocks.git
$ Cloning into 'docbook.rocks'...
$ remote: Counting objects: 52, done.
$ remote: Compressing objects: 100% (36/36), done.
$ remote: Total 52 (delta 19), reused 48 (delta 15), pack-reused 0
$ Unpacking objects: 100% (52/52), done.
```

You might imagine having your parser detect the existing prompts and fix them:

```shell-commands
$ git clone https:/b/github.com/grahamc/docbook.rocks.git
Cloning into 'docbook.rocks'...
remote: Counting objects: 52, done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 52 (delta 19), reused 48 (delta 15), pack-reused 0
Unpacking objects: 100% (52/52), done.
$ cd docbook.rocks
```

having it automatically change the $ to be unselectable.

But what about if your prompt changes, like

$ su -i
#

sure you could detect # too... but what about something fancier, like:

$ git clone https:/b/github.com/grahamc/docbook.rocks.git
Cloning into 'docbook.rocks'...
remote: Counting objects: 52, done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 52 (delta 19), reused 48 (delta 15), pack-reused 0
Unpacking objects: 100% (52/52), done.
$ cd docbook.rocks
$ nix-shell
[nix-shell:~/docbook.rocks]$

Having your markdown processer handle each of these cases is quite complicated, and we haven't even addressed cases where the prompt may be inside of another program.

With DocBook, there is an optional, built-in tag to explicitly mark the prompt:

<screen>
<prompt>$ </prompt>git clone https://github.com/grahamc/docbook.rocks.git
<prompt>$ </prompt>cd docbook.rocks
</screen>

4.2. Tables

If you've done any HTML, you'll have no trouble with DocBook tables.

<table>
  <thead>
    <tr>
      <th>Writing Format</th>
      <th>How good it is</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>DocBook</td>
      <td>Really good!</td>
    </tr>
    <tr>
      <td>MarkDown</td>
      <td>Pretty great!</td>
    </tr>
    <tr>
      <td>LaTeX</td>
      <td>Great for computer scientists!</td>
    </tr>
  </tbody>
</table>

Writing Format	How good it is
DocBook	Really good!
MarkDown	Pretty great!
LaTeX	Great for computer scientists!

Colophon

Built with Nix, DocBook, and HighlighterJS. The text is authored by Graham Christensen. The source can be found at https://github.com/grahamc/docbook.rocks. This document is licensed CC-BY-SA-4.0.