9.5. Block Elements

9.5.1. Paragraphs

DocBook supports three types of paragraphs:
formalpara, para, and
simpara.

Almost all paragraphs in FreeBSD documentation use
para. formalpara
includes a title element, and
simpara disallows some elements from
within para. Stick with
para.

Example 9.6. para Example

Usage:

<para>This is a paragraph. It can contain just about any
other element.</para>

Appearance:

This is a paragraph. It can contain just about any
other element.

9.5.2. Block Quotations

A block quotation is an extended quotation from another
document that should not appear within the current paragraph.
These are rarely needed.

Blockquotes can optionally contain a title and an
attribution (or they can be left untitled and
unattributed).

Example 9.7. blockquote Example

Usage:

<para>A small excerpt from the US Constitution:</para><blockquote><title>Preamble to the Constitution of the United States</title><attribution>Copied from a web site somewhere</attribution><para>We the People of the United States, in Order to form a more
perfect Union, establish Justice, insure domestic Tranquility,
provide for the common defence, promote the general Welfare, and
secure the Blessings of Liberty to ourselves and our Posterity, do
ordain and establish this Constitution for the United States of
America.</para></blockquote>

Appearance:

A small excerpt from the US Constitution:

Preamble to the Constitution of the United
States

We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the
general Welfare, and secure the Blessings of Liberty to
ourselves and our Posterity, do ordain and establish
this Constitution for the United States of
America.

--Copied from a web site
somewhere

9.5.3. Tips, Notes, Warnings, Cautions, and Important
Information

Extra information may need to be separated from
the main body of the text. Typically this is
“meta” information of which the user should be
aware.

Several types of admonitions are available:
tip, note,
warning, caution, and
important.

Which admonition to choose depends on the situation.
The DocBook
documentation suggests:

Warning is for information regarding possible
hardware damage or injury to life or limb.

Example 9.8. tip and important Example

Usage:

<tip><para>&os; may reduce stress.</para></tip><important><para>Please use admonitions sparingly. Too many admonitions
are visually jarring and can have the opposite of the
intended effect.</para></important>

Appearance:

Tip:

FreeBSD may reduce stress.

Important:

Please use admonitions sparingly. Too many admonitions
are visually jarring and can have the opposite of the
intended effect.

9.5.4. Examples

Examples can be shown with example.

Example 9.9. example Source

Usage:

<example><para>Empty files can be created easily:</para><screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen></example>

Appearance:

Example 9.10. Rendered example

Empty files can be created easily:

%touch file1 file2 file3

9.5.5. Lists and Procedures

Information often needs to be presented as lists, or as a
number of steps that must be carried out in order to
accomplish a particular goal.

To do this, use itemizedlist,
orderedlist, variablelist, or
procedure. There are other types of list
elements in DocBook, but we will not cover them here.

itemizedlist and
orderedlist are similar to their
counterparts in HTML, ul
and ol. Each one consists of one or more
listitem elements, and each
listitem contains one or more block
elements. The listitem elements are
analogous to HTML's li
tags. However, unlike HTML, they are required.

Example 9.11. itemizedlist and
orderedlist Example

Usage:

<itemizedlist><listitem><para>This is the first itemized item.</para></listitem><listitem><para>This is the second itemized item.</para></listitem></itemizedlist><orderedlist><listitem><para>This is the first ordered item.</para></listitem><listitem><para>This is the second ordered item.</para></listitem></orderedlist>

Appearance:

This is the first itemized item.

This is the second itemized item.

This is the first ordered item.

This is the second ordered item.

An alternate and often
useful way of presenting information is the
variablelist. These are lists where each entry has
a term and a description. They are well suited for many types
of descriptions, and present information in a form that is
often easier for the reader than sections and
subsections.

A variablelist has a title, and then
pairs of term and listitem
entries.

Example 9.12. variablelist Example

Usage:

<variablelist><varlistentry><term>Parallel</term><listitem><para>In parallel communications, groups of bits arrive
at the same time over multiple communications
channels.</para></listitem></varlistentry><varlistentry><term>Serial</term><listitem><para>In serial communications, bits arrive one at a
time over a single communications
channel.</para></listitem></varlistentry></variablelist>

Appearance:

Parallel

In parallel communications, groups of bits arrive
at the same time over multiple communications
channels.

Serial

In serial communications, bits arrive one at a
time over a single communications channel.

A procedure shows a series of
steps, which may in turn
consist of more steps or
substeps. Each step
contains block elements and may include an optional title.

Sometimes, steps are not sequential, but present a choice:
do this or do that,
but not both. For these alternative choices, use
stepalternatives.

Example 9.13. procedure Example

Usage:

<procedure><step><para>Do this.</para></step><step><para>Then do this.</para></step><step><substeps><step><para>And now do this smaller thing.</para></step><step><para>And now do this other smaller thing.</para></step></substeps></step><step><para>Finally, do one of these:</para><stepalternatives><step><para>Go left.</para></step><step><para>Go right.</para></step></stepalternatives></step></procedure>

Appearance:

Do this.

Then do this.

And now do this small thing.

And this other small thing.

Finally, do one of these:

Go left.

Go right.

9.5.6. Showing File Samples

Fragments of a file (or perhaps a complete file) are shown
by wrapping them in the programlisting
element.

White space and line breaks within
programlistingare
significant. In particular, this means that the opening tag
should appear on the same line as the first line of the
output, and the closing tag should appear on the same line
as the last line of the output, otherwise spurious blank
lines may be included.

9.5.8. Tables

Unlike HTML, DocBook does not need
tables for layout purposes, as the stylesheet handles those
issues. Instead, just use tables for marking up tabular
data.

In general terms (and see the DocBook documentation for
more detail) a table (which can be either formal or informal)
consists of a table element. This contains
at least one tgroup element, which
specifies (as an attribute) the number of columns in this
table group. Within the tablegroup there is one
thead element, which contains elements for
the table headings (column headings), and one
tbody which contains the body of the
table.

Both tgroup and
thead contain row
elements, which in turn contain entry
elements. Each entry element specifies
one cell in the table.

Always use the pgwide attribute with
a value of 1 with the
informaltable element. A bug in Internet
Explorer can cause the table to render incorrectly if this
is omitted.

Table borders can be suppressed by setting the
frame attribute to none
in the informaltable element. For example,
informaltable frame="none".

Example 9.17. Table with frame="none" Example

Appearance:

This is Column Head 1

This is Column Head 2

Row 1, column 1

Row 1, column 2

Row 2, column 1

Row 2, column 2

9.5.9. Examples for the User to Follow

Examples for the user to follow are often necessary.
Typically, these will consist of dialogs with the computer;
the user types in a command, the user gets a response back,
the user types another command, and so on.

A number of distinct elements and entities come into
play here.

screen

Everything the user sees in this example will be
on the computer screen, so the next element is
screen.

Within screen, white space is
significant.

prompt,
&prompt.root; and
&prompt.user;

Some of the things the user will be seeing on the
screen are prompts from the computer (either from the
operating system, command shell, or application). These
should be marked up using
prompt.

As a special case, the two shell prompts for the
normal user and the root user have been provided as
entities. To indicate the user is at a shell prompt,
use one of &prompt.root; and
&prompt.user; as necessary. They
do not need to be inside
prompt.

Note:

&prompt.root; and
&prompt.user; are FreeBSD
extensions to DocBook, and are not part of the
original DTD.

userinput

When displaying text that the user should type in,
wrap it in userinput tags. It will
be displayed differently than system output text.