The Crash Course to DocBook

Chapter 10. Describing the Application's Interface

10.1. Examples

These are the tags covered in this section:

literallayout - Wrapper for lines set off from the main text that are not tagged as screens, examples, or programlisting, in which line breaks and leading white space are to be regarded as significant
example - Example of a computer program or related information
informalexample - Untitled example
programlisting - Listing of all or part of a program
screen - Text that a user sees or might see on a computer screen

There are many situations where you must include examples of source code, commands, or GUI actions in your documentation. DocBook has many tags to support these needs. Whenever you want to include examples in your document, just put an <example> or <informalexample> tag around the example text or graphic.

Example 10-1. An example

<title>A BASIC Example</title>
20 GOTO 10

In this first example, we have a listing of a simple BASIC program. The code contained in the <programlisting> tag is displayed with the spacing and line breaks intact which is very useful for code examples and similar situations where you must preserve the literal formatting. The LiteralLayout and Screen tags work in the same way, but are used to indicate different types of content. screen contains output that would appear on the screen, while literallayout is used for any other text that must be rendered with line breaks and tabs.

The example would look something like this when converted:

Example 10-2. A programlisting

20 GOTO 10

One problem can occur with the LiteralLayout, ProgramListing, and Screen tags: all text is rendered literally, but DocBook tags are still interpreted as tags and not text. What do you do when you need to show text without having your tags interpreted? The answer is to use <![ CDATA [ ]]>, which labels the text contained within the inner brackets as character data that should not be interpreted by the SGML parser. Any text within the brackets will remain as-is after the conversion, so the example above will successfully reproduce its tags.

Example 10-3. CDATA usage

<title>some markup</title>
<para>This is a DocBook example.</Para>


This is what the markup example would look like when converted:

Example 10-4. Some markup

<para>This is a DocBook example.</para>