# DocBook Basics

## Introduction to DocBook

To understand DocBook, a basic understanding of SGML and XML is helpful.

SGML stands for Standard Generalized Markup Language and is one of the first markup languages ever created. A different, but similar markup language is XML which stands for Extended Markup Langauge. XML extends and structures SGML in ways which were optional using SGML. Both use what are called Document Type Definitions (DTD) to define document structural types such as HTML and DocBook. A DTD specifies document elements which are delimited by angle brackets, < and >, and document text is then marked by both beginning and ending elements. Using the DocBook DTD, for example, one marks up a title with `<title>`The Title`</title>`. The DTD (in the case of the GDP, DocBook) also defines rules for how the elements can be used. For example, if one element can only be used when embedded within another, this is defined in the DTD.

A XML file is just a plain ASCII file containing the text with the markup specified above. To convert it to some easily readable format, you need special tools. The GDP uses xsltproc, a free converter which converts the DocBook file into browser readable HTML using XSL stylesheets. Yelp is used to run xsltproc and then display the resulting HTML in a user friendly format. You can read more about DocBook in usingdocbook.

The final appearance of the output (e.g. PostScript or HTML) is determined by a stylesheet. Stylesheets are files, written in a special language (XSL — Extended Specification Language or DSSSL — Document Style Semantics and Specification Language), which specify the appearance of various DocBook elements, for example, what fonts to use for titles and various inline elements, page numbering style, and much more. You need to install a common collection of stylesheets in installingdocbook (Norman Walsh's modular stylesheets). The GNOME Documentation Project uses a customized set of stylesheets on top of Norman Walsh's version.

The advantage of specifying the structure of a document with XML instead of specifying the appearance of the document with a typical word processor, or with HTML, is that the resulting document can be processed in a variety of ways using the structural information. Whereas formatting a document for appearance assumes a medium (typically written text on a standard-sized piece of paper), XML can be processed to produce output for a large variety of media such as text, postscript, HTML, Braille, audio, and potentially many other formats. This assumption of a specific media makes translating documents not written in XML very difficult.

Using elements contained in a document to structure the text of that same document also allows search engines to make use of that information. For example, if you are searching for all documents written by the author Susie your search engine could be made smart enough to only search <author> elements, making for a faster and more accurate search.

Using a stylesheet to determine the overall appearance of the output, rather than the DTD or the XML document, allows everyone in the project to create documents with the same look just by using the same stylesheet. It also allows the look to be updated just by modifying that one stylesheet.

As stated before, the GDP uses the DocBook DTD. For a list of introductory and reference resources on DocBook, see resources. The following sections also provide convenient instructions on which markup tags to use in various circumstances. Be sure to read guidelines for GDP documentation-specific guidelines.

## Starting a Document

DocBook can be used to write many different documents. Glossaries, FAQs, indexes, books, and articles are some of the documents which can be written. To start the type of document you will need to enclose the document in the appropriate tag. You will be able to tell the type of document from the first tag. For books you will enclose the document in the `<book>` tag and for articles you will enclose the document in the `<article>` tag.

DocBook documents contain meta data, data which describes the document, typically at the beginning of the document. This meta data will include copyright notices, author information, revision history, and release information. The meta data is enclosed within the info tags. For books you will enclose the meta data with the `<bookinfo>` tag and for articles you will enclose the meta data in the `<articleinfo>` tag.

Throughout this chapter a full article will be produced showing you how to write a full article in DocBook. So far we have

    <article>
      <articleinfo>
      This will contain some information about the document.
      </articleinfo>
      This is the body of the document.
    </article>

as our document. As you continue to learn more about DocBook the article will grow.

### Sections and Paragraphs

DocBook has sections for structuring your document up to 5 sections deep. Also paragraphs must be enclosed with the `<para>` tag. The top-level element of a book body is `<chapter>`; it may contain one or more `<sect1>`, each of them may contain `<sect2>` and so on up to `<sect5>`. The top-level element of an article body is always `<sect1>`. Regardless of which elements you use, give each structural element an unique id, see guidelines-sectids.

Please try to avoid using deeply nested sections. For most situations, `<sect1>` and `<sect2>` should be sufficient. If not, you probably should split your `<sect1>` into several smaller ones. For splitting large sections into smaller ones, see the GNOME Documentation Style Guide.

Each section needs to contain a title. The title is a concise description of the content of a section. The `<title>` tag encloses the title of each section. The title is placed right after the section tags but before the body of the section. For help on writing good titles, see the GNOME Documentation Style Guide.

Use the tag `<para>` for paragraphs. If there is only one paragraph in a section you still need to use the `para` tag. You need to close the tag at the end of the all paragraphs. If the paragraph is only one line you should place the `para` tags on the same line. If the paragraph is multiple lines the `para` tags should be placed on separate lines as shown in the example below.

The most basic section of DocBook is made up of three parts. The section tags define where each section of text begins and ends, the title tags give a concise description of each section and the paragraph tags surround the text. So for our article document looks like:

    <article>
      <articleinfo>
      This will contain some information about the document.
      </articleinfo>

      <sect1>
        <title>DocBook Example</title>
        <para>
          This is an example of using DocBook for the most basic type of
          document.  The article just has one section and one paragraph.
        </para>
      </sect1>
    </article>

This is a very basic document with only one section and no meta data.

### DocBook Meta Data

The meta data of a document is put in `<articleinfo>` or `<bookinfo>` tags. The title of the entire document is put in the meta data. It is enclosed in the `<title>` tag. The copyright information is enclosed in the `<copyright>` tags. The copyright years are put inside the `<year>` tag and the copyright holder is put inside the `lt;holder>` tag. For example:

    <copyright>
      <year>2002</year>
      <holder>Eric Baudais</holder>
    </copyright>

is how the copyright information should look like inside articleinfo.

The author information contains the author's name, their address, and any affiliation. The authors of a document are enclosed in the `<authorgroup>` tag. The individual author's information is put inside the `<author>` tag. If there is only one author of the document you do not need the authorgroup tag. The author's name is divided into their firstname and surname with the two tags `<firstname>` and `<surname>`. The author's affiliation is put inside the `<affiliation>` tag. The address can be the author's email address or a physical address where they can be contacted through regular mail. For example:

    <authorgroup>
      <author>
        <firstname>Eric</firstname>
        <surname>Baudais</surname>
        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
          <address>
            <email>baudais@kkpsi.org</email>
          </address>
        </affiliation>
      </author>

      <author>
        <firstname>John</firstname>
        <surname>Doe</surname>
        <affiliation>
          <orgname>Free Software Foundation</orgname>
          <address>
            59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
            <email>john.doe@gnu.org</email>
          </address>
        </affiliation
      </author>
    </authorgroup>

is how the author information should look inside the articleinfo. There are more information you can include inside the author tag. This is just the basics of how to construct the meta data.

The last meta data for a document is any legal statements such as the license of the document or any disclaimers or any warranties and the release information. The legal information about the document is enclosed in the `<legalnotice>` tag. You can have a title for the legalnotice using the `<title>` tag. The legalnotice should be treated as a section of the articleinfo. All paragraphs should be enclosed with the `<para>` tag. The release information is enclosed in the `<releaseinfo>` tag. This is different from the legalnotice because the release information is entered without any paragraph tags. For example:

    <legalnotice>
      <title>Legal Notices</title>

      <para>
        Permission is granted to copy, distribute and/or modify this
        document under the terms of the GNU Free Documentation
        License (GFDL), Version 1.1 or any later version published
        by the Free Software Foundation with no Invariant Sections,
        no Front-Cover Texts, and no Back-Cover Texts.  You can find
        a copy of the GFDL at this <ulink type="help"
        url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
        distributed with this manual.
      </para>
    </legalnotice>

    <releaseinfo>
      This is version 1.0.0 of DocBook Basics documenting version 4.1.2 of
      DocBook XML.
    </releaseinfo>

is the other information included in the meta data. There are more information about the document you can include, but this is a good beginning for a basic document.

The document created so far includes the meta data and the body of the documentation. Our article document now looks like:

    <article>
      <articleinfo>

        <copyright>
          <year>2002</year>
          <holder>Eric Baudais</holder>
        </copyright>

        <authorgroup>
          <author>
            <firstname>Eric</firstname>
            <surname>Baudais</surname>
            <affiliation>
              <orgname>GNOME Documentation Project</orgname>
              <address>
                <email>baudais@kkpsi.org</email>
              </address>
            </affiliation>
          </author>

          <author>
            <firstname>John</firstname>
            <surname>Doe</surname>
              <affiliation>
              <orgname>Free Software Foundation</orgname>
              <address>
                59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
                <email>john.doe@gnu.org</email>
              </address>
            </affiliation
          </author>
        </authorgroup>

        <legalnotice>
          <title>Legal Notices</title>

          <para>
            Permission is granted to copy, distribute and/or modify this
            document under the terms of the GNU Free Documentation
            License (GFDL), Version 1.1 or any later version published
            by the Free Software Foundation with no Invariant Sections,
            no Front-Cover Texts, and no Back-Cover Texts.  You can find
            a copy of the GFDL at this <ulink type="help"
            url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
            distributed with this manual.
          </para>
        </legalnotice>

        <releaseinfo>
          This is version 1.0.0 of DocBook Basics documenting version 4.1.2 of
          DocBook XML.
        </releaseinfo>

      </articleinfo>

      <sect1>
        <title>DocBook Example</title>
        <para>
          This is an example of using DocBook for the most basic type of
          document.  The article just has one section and one paragraph.
        </para>
      </sect1>
    </article>

The document is still very basic with not much content. Yet there is lots of meta data information about the document. As you learn more about the DocBook tags your documents will become more complex. However, the basic structure of the document is done and all that is left is to write the document.

## Structural Elements

DocBook has many other tags to structure a document than sections and paragraph. Notes, figures, lists, and tables can all be included into a document and are as much a part of the way a document is structured as sections and paragraphs. An explanatory figure or table in the right place will enlighten the reader and enhance the appearance and readability of the document. The GNOME Documentation Style Guide talks more about when and where to use these effectively. Some of these are easy to use with DocBook while others take a while to master.

### Notes, Warnings, and Tips

For notes, tips, warnings, and important information, called admonitions, should be set apart from the main text (usually as a paragraph with some warning sign on the margin). A title is usually a good idea as it tells the reader what information you are trying to set off, but is entirely optional. Use the tags `<note>`, `<tip>`, `<warning>`, `<important>` respectively. For example:

    <tip>
    <title>DocBook Validation Tip</title>
      <para>
        To validate DocBook without displaying the document, add the
        argument <parameter class="option">--noout</programlisting> to the
        <application>xmllint</programlisting> command.
      </para>
    </tip>

produces

#### DocBook Validation Tip

To validate DocBook without displaying the document, add the argument `--noout` to the xmllint command.

The `<tip>` tag should not be inside a `<para>` tag but between paragraphs.

### Screenshots and other Figures

To include screenshots and other figures, use the following tags:

    <figure id="app-FIG-shot1">
     <title>Screenshot</title>
     <screenshot>
      <mediaobject>
       <imageobject>
        <imagedata fileref="figures/example_screenshot.png" format="PNG"/>
       </imageobject>
       <textobject>
         <phrase>Shows the application screenshot with several buttons.</phrase>
       </textobject>
       <caption>
        <para>Screenshot of a program</para>
       </caption>
      </mediaobject>
     </screenshot>
    </figure>

replacing `example_screenshot` with the actual file name (without extension). The result will look like this:

#### Screenshot

Shows the application screenshot with several buttons.

Screenshot of a program

### Screenshot Tools

There are many tools for taking screenshots in GNOME/Linux. Perhaps the most convenient is the Take a Screen Shot tool located in Actions Take a Screen Shot . Just choose whether you want to save the screenshot to a file or on the desktop and click Okay. When you click the Okay button the tool will take a screenshot in a second. If you want a window in focus you will need to focus the window in the second from when you click the Okay button to when the tool takes a screen shot. For applets in a Panel, GIMP can be used to crop the screenshot to only include the relevant portion of the Panel. Note that GIMP can both be used for taking screenshots, cropping screenshots, and converting image formats. If you need to convert an image to PNG from another format make sure you use compression liberally. A high compression level will usually look fine in Yelp.

### Program Listings and Terminal Session

To show a file fragment—for example, program listing—use `<programlisting>` tag:

    <programlisting>
    [Desktop Entry]
    Name=Gnumeric spreadsheet
    Exec=gnumeric
    Icon=gnome-gnumeric.png
    Terminal=0
    Type=Application
    </programlisting>

which produces

    [Desktop Entry]
    Name=Gnumeric spreadsheet
    Exec=gnumeric
    Icon=gnome-gnumeric.png
    Terminal=0
    Type=Application

As a matter of fact, all examples in this document were produced using `<programlisting>`.

To show a record of a terminal session (i.e. sequence of commands entered at the command line) use the `<screen>` tag:

    <screen>
    <prompt>bash$</prompt><userinput>make love</userinput>
    make: *** No rule to make target `love'. Stop.
    </screen>

which produces

    bash$make love
    make: *** No rule to make target `love'.  Stop.

Observe the use of tags `<prompt>` and `<userinput>` for marking system prompt and commands entered by user.

#### Note

Note that both `<programlisting>` and `<screen>` preserve linebreaks, but interpret XML tags (unlike LaTeX `verbatim` environment). Take a look at the source of this document to see how you can have XML tags literally shown but not interpreted,

### Lists

The most common list types in DocBook are `<itemizedlist>`, `<orderedlist>`, and `<variablelist>`.

`<itemizedlist>`

- This is the simplest unnumbered list, parallel to `<ul>` in HTML. Here is an example:

      <itemizedlist>
        <listitem>
          <para>
            <guilabel>Show backup files</guilabel> &mdash; This will
            show any backup file that might be on your system.
          </para>
        </listitem>
        <listitem>
          <para>
            <guilabel>Show hidden files</guilabel> &mdash; This will
            show all "dot files" or files that begin with a dot.  Those
            files typically include configuration files and directories.
          </para>
        </listitem>
        <listitem>
          <para>
            <guilabel>Mix files and directories</guilabel> &mdash; This
            option will  display files and directories in the order you
            sort them instead of
            always having directories shown above files.
          </para>
         </listitem>
      </itemizedlist>

  and output:

  - Show backup files — This will show any backup file that might be on your system.

  - Show hidden files — This will show all "dot files" or files that begin with a dot. Those files typically include configuration files and directories.

  - Mix files and directories — This option will display files and directories in the order you sort them instead of always having directories shown above files.

  Note the use of the character entity `&mdash;` for a long dash (see docbook-specsymb). Also, please note that the result looks much nicer because the terms being explained (Show backup files, etc.) are set in a different font. In this case, it was achieved by using `<guilabel>` tag. In other cases, use appropriate tags such as `<guimenuitem>`, `<command>`, or — if none of this applies — use `<emphasis>`.

`<orderedlist>`

- This list is completely analogous to `<itemizedlist>` and has the same syntax, but it produces numbered list. By default, this list uses Arabic numerals for numbering entries; you can override this using `numeration`, for example `<orderedlist numeration="lowerroman">`. Possible values of the numeration attribute are `arabic`, `upperalpha`, `loweralpha`, `upperroman`, and `lowerroman`.

`<variablelist>`

- This list is used when each entry is rather long, so it should be formatted as a block of text with some subtitle, like a small subsection. The `<variablelist>` is more complicated than itemizedlists, but for larger blocks of text, or when you're explaining or defining something, it's best to use them. Their greatest advantage is that it's easier for a computer to search. The lines you are reading now were produced by `<variablelist>`. The source looked liked this:

      <variablelist>
        <varlistentry>
          <term> <sgmltag>&lt;itemizedlist&gt;</sgmltag></term>
          <listitem><para>
      	This is the simplest unnumbered list, parallel to
              <sgmltag>&lt;ul&gt;</sgmltag> in HTML. Here is an example:...
          </para></listitem>
          </varlistentry>
          <varlistentry>
      	<term> <sgmltag>&lt;orderedlist&gt;</sgmltag></term>
           <listitem><para>
      	This list is completely analogous to
      	<sgmltag>&lt;itemizedlist&gt;</sgmltag>
          </para></listitem>
          </varlistentry>
          <varlistentry>
      	<term> <sgmltag>&lt;variablelist&gt;</sgmltag></term>
           <listitem><para>
      		This list is used when each entry is rather long,...
          </para></listitem>
          </varlistentry>
      </variablelist>

Lists can be nested; in this case, the stylesheets are smart enough to change the numeration (for `<orderedlist>`) or marks of each entry (in `<itemizedlist>`) for sub-lists

## Inline Elements

### GUI elements

- `<guibutton>` — used for clickable buttons in the user interface

- `<guimenu>`, `<guisubmenu>` —used for top-level menus and submenus respectively, for example `<guisubmenu>Utilities</guisubmenu> submenu of the <guimenu>Main Menu</guimenu>`

- `<guimenuitem>`—an entry in a menu

- `<guiicon>`—an icon

- `<guilabel>`—for items which have labels, like tabs, bounding boxes, or radio buttons.

- `<interface>`— for most everything else... a window, a dialog box, the Panel, etc.

If you need to refer to a sequence of menu choices, such as Main Menu Utilities GNOME terminal there is a special construction for this, too:

    <menuchoice>
      <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
      <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>

### Links and References

To refer to another place in the same document, you can use tags `<xref>` and `<link>`. The first of them automatically inserts the full name of the element you refer to (section, figure, etc.), while the second just creates a link (in HTML output). Here is an example:

    An example of a <link linkend="app-extip">tip</link> was given in
    <xref linkend="notes" />.

which produces:

    An example of a tip was given in  docbook-notes.

Here `notes` is the id attribute of docbook-notes and `extip` is the id attribute of the section about tips.

To produce a link to an external source, such as a Web page or a local file, use the `<ulink>` tag, for example:

    To find more about GNOME, please visit the <ulink type="http"
    url="http://www.gnome.org">GNOME Web Site</ulink>

which produces:

    To find more about GNOME, please visit the GNOME Web Site

You can use any of the standard URL types, such as `http, ftp, file, telnet, mailto` (in most cases, however, use of `mailto` is unnecessary—see discussion of `<email>` tag).

For more on this topic, see refering.

### Filenames, commands, and other computer-related things

Here are some tags used to describe operating system-related things:

- `<filename>` — used for filenames, e.g.`<filename>` foo.sgml `</filename>` produces: `foo.sgml`.

- `<filename class="directory">` — used for directories, e.g.`<filename class="directory">`/usr/bin `</filename>` produces: `/usr/bin`.

- `<application>` — used for application names, e.g. `<application>`Gnumeric `</application>` produces: Gnumeric.

- `<envar>` — used for environment variables, e.g. `<envar>`PATH`</envar>` produces : `PATH`

- `<command>` — used for commands entered on command line, e.g. `<command>`make install `</command>` produces: `make install`.

- `<parameter>` — used for options or arguments passed to a system call or command, e.g. `<parameter>`--version `</parameter>` produces: `--version`.

- `<replaceable>` — used for replaceable text, e.g. `<command>`db2html`<replaceable>` foo.sgml `</replaceable>``</command>` produces: `db2html `foo.sgml``.

### Keyboard Input

To mark up text input by the user, use `<userinput>`.

To mark keystrokes such as shortcuts and other commands, use `<keycap>`. This is used for marking up what is printed on the top of the physical key on the keyboard. There are a couple of other tags for keys, too: `<keysym>` and `<keycode>`. However you are unlikely to need these for most documentation. For reference, `<keysym>` is for the symbolic name of a key. `<keycode>` is for the scan code of a key. These are not terms commonly required in GNOME documentation, although `<keysym>` is useful for marking up control codes.

To mark up a combination of keystrokes, use the `<keycombo>` wrapper:

    <keycombo>
     <keycap>Ctrl</keycap>
     <keycap>Alt</keycap>
     <keycap>F1</keycap>
    </keycombo>

Finally, if you want to show a shortcut for some menu command, here are the appropriate tags (rather long):

    <menuchoice>
     <shortcut>
      <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
     </shortcut>
     <guimenuitem> Quit</guimenuitem>
    </menuchoice>

which produces simply Ctrl-q Quit

### E-mail Addresses

To mark up e-mail address, use `<email>`:

     The easiest way to get in touch with me is by e-mail
    (<email>me@mydomain.com</email>)

which produces: The easiest way to get in touch with me is by e-mail (me@mydomain.com) Note that `<email>` automatically produces a link in the HTML version.

### Special Symbols

DocBook also provides special means for entering typographic symbols which can not be entered directly form the keyboard (such as copyright sign). This is done using character entities, which ii the XML analogue of macros, or commands, of LaTeX. They generally have the form `&entityname;`. Note that the semicolon is required.

here is partial list of most commonly used enitites:

- `&amp;` — ampersend (&)

- `&lt;` — left angle bracket (<)

- `&gt;` — right angle bracket (>)

- `&copy;` — copyright sign (©)

- `&mdash;` — long dash (—)

- `&hellip;` — ellipsis (…)

Note that the actual look of the resulting symbols depends on the fonts used by your browser; for example, it might happen that long dash (`&mdash;`) looks exactly like the usual dash (-). However, in the PostScript (and thus, in print) the output will look markedly better if you use appropriate tags.

## Indexing