# DocBook: Sample Markup

## General Tips and Tricks

For a general overview of what markup is all about, please read

- An editor capable of inserting elements according to the DTD will help a lot since it will enforce the DTD. This way you can be sure that no invalid elements were added anywhere in your document.

- In order to ensure that future changes are as easy as possible, authors should try to keep compatibility with the XML version of the DocBook DTD. This means keeping element names in lower case, using double quotes in all attributes, and not omitting end tags. Most tools that automatically insert elements (like psgml+emacs) follow these rules automatically or with some fine tuning.

- Each type of document created has a specific structure. This document is in book format. Most authors, however, will want to use the shorter article format instead. Templates are available from .

### Useful markup

shows some markup that is useful for generating generic documents. Remember that some elements are valid only on some contexts.

#### Check several formats

Sometimes the appearance of a particular tag changes from one conversion format to another. As a beginner in DocBook writing, you may wish to see how your document looks in several formats before you publish them. You are advised to look at how your document is presented in HTML, PDF and PostScript, since these formats will be made available by TLDP once you publish your document.

#### Better too much than not enough

Since the formatting depends on the output style chosen, it's recommended to use as much markup as possible. Even if the appearance of the output doesn't seem to change with the standard output style, there may be specific output formats that will make these tags stand out.

#### Useful markup

Description | Sample markup | Result
--- | --- | ---
E-mail address | `email`address@domain`email` | address@domain
About the author | `author`...`author` | (see example below)

Author's name

    firstnameMaryfirstname
    othernameMargaretothername
    surnameO'Harasurname

Mary Margaret O'Hara

Keys' name (printings on the keyboard) | `keycap`F1`keycap` | F1
Symbol represented by the keys | `keysym`KEY_F1`keysym` | KEY_F1
Key's code | `keycode`0x3B`keycode` | 0x3B

Combinations or sequences of keys

    keycombo
       keycapCtrlkeycap
       keycapSkeycap
    keycombo

Ctrl S

Program Menus | `guimenu`File`guimenu` | File
Menu Items | `guimenuitem`Save`guimenuitem` | Save

Menu Sequences

    menuchoice
       shortcut
          keycombo
             keycapCtrlkeycap
             keycapSkeycap
          keycombo
       shortcut
       guimenuFileguimenu
       guimenuitemSaveguimenuitem
    menuchoice

Ctrl S File Save

Mouse Button | `mousebutton`left`mousebutton` | left
Application Names | `application`application`application` | application
Text Bibliographical Reference | `citation`reference`citation` | reference

Quote

    blockquote
       attributionText Authorattribution
       paraQuote Text.para
    blockquote

> Text Author

> Quote Text.

Index | (NA) | See .

File Names

    filenamefilefilename

`file`

Directories

    filename id="directory"directoryfilename

`directory/`

Emphasize Text Text can be emphasized in a few ways. The most common ways are italics and bold. DocBook, however, supports only italics. The use of bold requires additional settings on the style sheet used.

    emphasistextemphasis

text

Footnotes

    footnote
       paraFootnote textpara
    footnote

(See note at the end of this table for an example)

URLs

    ulink url="http://www.conectiva.com"Conectiva S.A.

Conectiva S.A.

Itemized (unnumbered) List

    itemizedlist
       listitem
          paraitempara
       listitem
       listitem
          paraitempara
       listitem
    itemizedlist

- item

- item

Ordered (numbered) List

    orderedlist
       listitem
          paraitempara
       listitem
       listitem
          paraitempara
       listitem
    orderedlist

1. item

2. item

Segmented List

    segmentedlist
       titleBinary to decimal conversiontitle
       segtitleBinarysegtitle
       segtitleDecimalsegtitle
       seglistitemseg00segseg0seg
       seglistitem
       seglistitemseg01segseg1seg
       seglistitem
       seglistitemseg10segseg2seg
       seglistitem
    segmentedlist

#### Binary to Decimal Conversion

Binary Decimal 00 0 01 1 10 2

Variable List

    variablelist
       varlistentry
          termEntry 1term
          listitem
             paraDescriptionpara
          listitem
       varlistentry
       varlistentry
          termEntry 2term
          listitem
             paraDescriptionpara
          listitem
       varlistentry
    variablelist

Entry 1

  Description

Entry 2

  Description

Simple Lists

    simplelist type="horiz" columns="3"
       member1member
       member2member
       member3member
       member4member
       member5member
       member6member
    simplelist
    simplelist type="inline"
       memberAmember
       memberBmember
       memberCmember
       memberDmember
       memberEmember
       memberFmember
    simplelist

- 1
- 2
- 3
- 4
- 5
- 6

- A
- B
- C
- D
- E
- F

Pictures | (NA) | See

Glossary

    glossentry
       glosstermTermglossterm
       glossdef
          paraDefinitionpara
       glossdef
    glossentry

(See the glossary at the end of this document)

Crossed References

    section id="secao"
    ...
    section
    section id="reference the other section"
    ...
    paraPlease, seexref linkend="secao" / for more information.

(NA)

## `section` and `sectN`: what's the difference?

### Acknowledgment

These notes were provided by: John Daily and Saqib Ali (saqib@seagate.com).

`section` versus `sectN` is largely a question of flexibility. The stylesheets can make a `section` in a `section` look just like a `sect2` within a `sect1`, so there's no output advantage.

But, a `section` within a `section` can be extracted into its own top-level section, nested even more deeply, or moved to an entirely different part of the document, without it and its own `section` children being renamed. That is not true of the numbered section tags, which are very sensitive to rearrangements. This can be easier for authors who are new to DocBook than using `sectN`.

The main idea behind creating structured data is that it should be easy to access and query. One should be able to retrieve a subsection of any structured data, by using querying languages for XML (XPath and XQuery). `sectN` are useful when traversing a document using XPath/XQuery. `sectN` gives more flexibility, and control while writing an XPath expression.

A well-defined, valid and well-structured document makes it easier for one to write XPath/Query to retreive specific data from a document. For example you can use XPath to retrieve information in the `sect3` block with certain attributes. However if you just used `section` for all subsections, it becomes harder to retrieve the block of information that you need.

So which one should you use? The one you feel most comfortable with is a good place to start. This document is written with `section`s. You may, or may not, think this is a good idea. :)

## Command Prompts

There are likely as many ways of doing this as there are DocBook authors; however, here are two ways that you might find useful. Thanks to Y Giridhar Appaji Nag and Martin Brown for the markup used here.

### Command Prompt with `programlisting`

    programlisting
    	prompt# promptuserinputcommandcdcommand /some/diruserinput
    	prompt# promptuserinputcommandlscommand -luserinput
    programlisting

Displays as:

    # cd /some/dir
    # ls -l

### Command Prompt with `screen`

First create a general entity in the internal subset at the very beginning of your document. This entity will define a name for the shortcut which you can use to display the full prompt at any point in your document. `<!ENTITY prompt "<prompt>[user@machine ~/dir]$</prompt>">`

For more information about entities, read .

    screen
    &prompt; userinputcd /some/diruserinput
    &prompt; userinputls -luserinput screen

Displays as:

    [user@machine ~/dir]$ cd /some/dir
    [user@machine ~/dir]$ ls -l

If you would like to add the output of your commands you can add `computeroutput` text`computeroutput` within the `screen` or `programlisting` as appropriate.

## Encoding Indexes

The generation of indexes depends on the markups inserted in the text.

Such markups will be processed afterwards by an external tool and will generate the index. An example of such a tool is the `collateindex.pl` script (see ). Details about the process used to generate these indexes are shown in .

The indexes have nesting levels. The markup of an index is done by the code .

### Code for the generation of an index

    indexterm
       primaryMain levelprimary
       secondarySecond levelsecondary
    	tertiaryThird leveltertiary
    	indexterm

It is possible to refer to chapters, sections, and other parts of the document using the attribute `zone`.

### Use of the attribute `zone`

    section id="encoding-index"
    titleEncoding Indexestitle
    indexterm zone="encoding-index"
    primaryeditionprimary secondaryindexsecondary
    indexterm

    para
    	The generation of indexes depend on the inserted markups on the text.
    para

The has the code used to generate the entry of this edition on the index. In fact, since the attribute `zone` is used, the index statement could be located anywhere in the document or even in a separate file.

However, to facilitate maintenance the entries for the index were all placed after the text to which it refers.

### Usage of values `startofrange` and `endofrange` on the attribute`class`

        paraTyping the text normally
        sometimes there's the need of
       indexterm class="startofrange"
       id="example-band-index"
          primaryexamplesprimary secondaryindexsecondary
       indexterm mark large amounts of
       text.para

       paraKeep inserting the paragraphs
       normally.para

       paraUntil the end of the section
       intended to be indexed.  indexterm
       startref="example-band-index" class="endofrange".
       para

## Inserting Pictures

It is necessary to insert pictures formats for all possible finished document types. For example: JPG files for web pages and EPS for PostScript and PDF files.

If you use the TeX format you'll need the images as a PostScript file. For on-line publishing you can use any kind of common image file, such as JPG, GIF or PNG.

The easiest way to insert pictures is to use the `fileref` attribute. Usually pictures are generated in JPG and in PostScript (PS or EPS).

### Inserting a picture

    figure
       titlePicture's
       Titletitle graphic fileref="images/file"graphic
    figure

Replacing `figure` by `informalfigure` eliminates the need to insert a title for the picture.

There's still the `float` attribute on which the value `0` indicates that the picture should be placed exactly where the tag appears. The value `1` allows the picture to be moved to a more convenient location (this location can be described on the style sheet, or it can be controlled by the application).

### Graphics formats

When submitting graphics to the LDP, please submit one set of graphics in `.eps`, and another in `.gif`, `.jpg` or `.png`. The preferred format is `.png` or `.jpg` due to patent problems with `.gif`.

You can use `.jpg` files for continuous-tone images such as photos or images with gradual changes in color. Use `.png` for simple images like diagrams, some screen shots, and images with a low number of colors.

### Alternative Methods

The first alternative to is to eliminate the `figure` or `informalfigure` elements.

Another interesting alternative when you have decided to publish the text on media where pictures are not accepted, is the use of a wrapper, `imageobject`.

#### Using `imageobject`

    figure
       titleTitletitle
       mediaobject
          imageobject
    	 imagedata fileref="images/file.eps" format="EPS"
          imageobject
       imageobject
    	 imagedata fileref="images/file.jpg" format="JPG"
          imageobject
          textobject
    	 phraseHere there's an image of this examplephrase
          textobject
       caption
       paraImage Description. Optional. para
       caption
       mediaobject
    figure

Files using the following formats are available

- BMP
- CGM-BINARY
- CGM-CHAR
- CGM-CLEAR
- DITROFF
- DVI
- EPS
- EQN
- FAX
- GIF
- GIF87A
- GIF89A
- IGES
- JPEG
- JPG
- LINESPECIFIC
- PCX
- PIC
- PS
- SGML
- TBL
- TEX
- TIFF
- WMF
- WPG

.

This method presents an advantage: a better control of the application. The elements `imageobject` are consecutively tested until one of them is accepted. If the output format does not support images the `textobject` element will be used. However, the biggest advantage in usage of the format is that in DocBook `5.0`, the `graphic` element will cease to exist.

As a disadvantage, there is the need for more than one representation code of the same information. It is up to the author to decide how they will implement illustrations and pictures in the document, but for compatibility with future versions I recommend the use of this method for pictures and graphics.

#### Title page exception

`mediaobject`s will not display if they are used on a title page. For more information read:

#### ASCII Images

You may also want to try converting your image to an ASCII representation of the file. JavE (Java ASCII Versatile Editor) can do this conversion for you. It can be downloaded from . It has an easy to use GUI interface.

If you're more command-line oriented you may want to try: tgif () and AA-Lib ().

## Markup for Metadata

### Crediting Translators, Converters and Co-authors

There are several ways that these folks, as well as other contributors to your document, can be given some recognition for the help they've given you.

#### `othercredit`

All translators, converters and co-authors should be credited with an `othercredit` tag entry. To properly credit a translator or converter, use the `othercredit` tag with the `role` attribute set to converter or translator, as indicated in the example below:

##### Other Credit

    othercredit role='converter'
      firstnameDavidfirstname
      surnameMerrillsurname
      contribConversion from HTML to DocBook v3.1 (SGML).contrib
    othercredit

#### Crediting Editors and Reviewers

To help track the review process all new documents must include a reference to the reviewers for the technical, language and metadata reviews.

##### Editor

    editor
      firstnameTabathafirstname
      surnameMarshallsurname
      contribLanguage review of version 0.8contrib
    editor

### `revremark`s

Within the `revision` tag hierarchy is a tag called `revremark`. Within this tag, you can make any brief notes you wish about each particular revision of your document.

### Revision History

The `revhistory` tag should be used to denote the various revisions of the document. Specify the date, revision number and comments regarding what has changed.

Revisions should be listed with the most-recent version at the top (list in descending order).

### Date formats

The `pubdate` tag in your header should list the publication date of this particular version of the document (coincide with the revision date). It should be in the following format:

    pubdate2002-04-25pubdate

The date is in the format YYYY-MM-DD, which is one of the ISO 8601 standard formats for representing dates. For you Yanks out there (me too), think of it as going from the largest unit of time to the smallest.

### Sample Article (or Book) Information Element

Here is a sample of a complete DocBook (SGML or XML) `articleinfo` element which contains some of the items and constructs previously described.

#### Sample Meta Data

    <!--
       Above these lines in a typical DocBook article would be the article
       element (the immediate parent of the articleinfo element) and above
       that typically, the DOCTYPE declaration and internal subset.
      -->

    articleinfo

      <!--
      	Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate
      -->

    titleSample HOWTOtitle

    author
    	firstnameYour Firstnamefirstname
    	surnameYour Surnamesurname
    	affiliation
    		addressemailyour emailemailaddress
    		affiliation
    author

    editor
      firstnameTabathafirstname
      surnameMarshallsurname
      contribLanguage review of version 0.8contrib
    editor

    othercredit role='converter'
      firstnameDavidfirstname
      surnameMerrillsurname
      contribConversion from HTML to DocBook v3.1 (SGML).contrib
    othercredit

       pubdateYYYY-MM-DDpubdate

    	revhistory
    		revision
    		revnumber1.0revnumber
    		dateYYYY-MM-DDdate
    		authorinitialsABCauthorinitials
    		revremarkfirst official releaserevremark
    		revision

    		revision
    		revnumber0.9revnumber
    		dateYYYY-MM-DDdate
    		authorinitialsABCauthorinitials
    		revremarkFirst draftrevremark
    		revision
    	revhistory

       <!--
    		Provide a good abstract; a couple of sentences is sufficient
       -->

      abstract
    		para
           This is a sample DocBook (SGML or XML) HOWTO which has been
           constructed to serve as a template.
    		para
    	abstract

    articleinfo

## Bibliographies

Not everyone will choose to use the correct formatting for a bibliography. Most will use a list of some kind. And that's ok. But when you're ready to move to the next level, here's how to do it.

Below are two examples of bibliographic entries. The first is a very simple entry. It has only a title, URL and possibly a short description (abstract). The second is a little more complex and is for a full entry (for instance a book) with an ISBN, publisher and copyright date.

### DocBook requirements for bibliographic references

At least one element within `biblioentry` is required, but it doesn't matter which one you have. So you might have a `title`, or a URL (`bibliosource`), or an `author`, or, ...

For a full list of all options, visit . For more examples visit .

### Displaying `abstract` content

By default `abstract`s do not display on web pages. You need to modify the `biblio.xsl` file. Do a search for the word abstract and then add this information inside the <xsl:template> tags. If that doesn't make sense, don't worry about it too much, but do be aware that it's required for the abstracts to show up.

    <div xmlns="http://www.w3.org/1999/xhtml" class="{name(.)}">
        <xsl:apply-templates mode="bibliography.mode"/>
    </div>

### A Bibliography

    bibliography
    titleBibliography titletitle

    bibliodiv
    titleSection titletitle
    biblioentry
    titleBook or Web Site Titletitle
    bibliosourceulink url=""bibliosource
    abstractabstract
    biblioentry

    biblioentry
    titletitle
    bibliosourceulink url=""bibliosource
    authorfirstnamefirstnamesurnamesurnameauthor
    copyrightyearyear
    holderholdercopyright
    editorfirstnamefirstnamesurnamesurnameeditor
    isbnisbn
    publisher
    publishernamepublishername
    publisher
    abstractabstract
    biblioentry
    bibliodiv
    bibliography

View to see this in action.

## Entities (shortcuts, text macros and re-usable text)

There may be some segments of text, or markup that you want to use over and over again. Instead of typing it up multiple times (and then having to edit it multiple times if you want to make a change) you can use external entities. Entities can give you a short cut to: re-using whole documents, text snippets, and special markup. Some common ways to use an entity would be for:

- ### text macros for markup

  An example would be a company URL. By using a parameter entity you could refer simply to &my-company-url; instead of typing out the full <ulink url="http://foo.bar">Foo.bar</ulink> each time.

- ### software license

  Such as the GNU Free Documentation License: it is long. And must be included in full in each document. By leaving the license in a separate file you can easily include it in many documents without having to redo the markup each time.

- ### repeated text

  For instance an introduction to a topic which is included both as a summary in one section and as an introduction to the full information in another. Saves on editing time if you need to make changes to both sets of text.

### Adding Entities

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    <-- I can add comments here -->
    <!ENTITY shortcut "Replace 'shortcut' with this text.">

    <!ENTITY sc-to-a-file SYSTEM "anotherfile.xml">
    <-- note: the square bracket on the third line is closed on the next
    line--> ]>

To use these entities simply insert the name you gave the entity between a & (ampersand) and a ; (semicolon). For example: &shortcut; would expand into Replace 'shortcut' with this text; &sc-to-a-file; would include the full contents of whatever is in anotherfile.xml.

An important feature while writing a text is the ability to check whether or not it will be presented in the final draft. It is common to have several parts of the text marked as draft, especially when updating an already existing document.

With the use of parameter entities, you can include or eliminate these drafts by altering only one line at the beginning of a document.

### Use of parameter entities

    !ENTITY % review "INCLUDE" ...
    ![%review;[ <para>This paragraph will
    be included on the draft when the entity "review" is defined with the
    value "INCLUDE". </para> ]]

The entity `review` might have several texts defined, as in . When the changes to the text are considered final, you need only to remove parts of the text between the 3rd. and 6th. lines.

To keep the draft definitions and hide the text in the final draft, just alter the specification of the entity from `INCLUDE` to `IGNORE`.

## Customizing your HTML files

### HTML file names

By default, when separate HTML files are made, the SGML processor will assign arbitrary names to the resulting files. This can be confusing to readers who may bookmark a page only to have it change. Whatever your reasoning, here's how to make separate files named the way you want:

In your first `article` tag (which should be the only one) include an `id` parameter and call it index. This will make your tag look like this:

    article id="index"

Do not modify the first `chapter` tag, as it's usually an introduction and you want that on the first page. For each other `section` tag, include the id parameter and name it. A name should include only alphanumeric characters, and it should be short enough to understand what it is.

    	chapter id="tips"

#### Pick section IDs intelligently

We all know that Cool URIs Don't Change. This means your ids should not change either. Unless of course the content for the id has changed substantially and the id name is no longer relevant.

#### HTML file name generation using Jade

If you are using Jade to transform your DocBook into HTML you must use the following parameter: `-V %use-id-as-filename%`.

### Headers and Footers

There is no easy way to add headers and footers to your document. If you are using DocBook XSL and doing your own document transformations you may customize the XSL template to suit your needs. For more information read .