9.5. Block Elements
Prev | Chapter 9. DocBook Markup | Next

## 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`

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`

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, Important Information and Sidebars

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.

Depending on the nature of the information, one of `tip`, `note`, `warning`, `caution`, and `important` should be used. Alternatively, if the information is related to the main text but is not one of the above, use `sidebar`.

The circumstances in which to choose one of these elements over another is loosely defined by the DocBook documentation, which suggests:

- A Note is for information that should be heeded by all readers.

- An Important element is a variation on Note.

- A Caution is for information regarding possible data loss or software damage.

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

Example 9.8. `warning`

Usage:

`<warning>` `<para>`Installing FreeBSD may make you want to delete Windows from your hard disk.`</para>` `</warning>`

Appearance:

### Warning:

Installing FreeBSD may make you want to delete Windows from your hard disk.

### 9.5.4. 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`, or `procedure`[2]

`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.

`procedure` is slightly different. It consists of `step`s, which may in turn consists of more `step`s or `substep`s. Each `step` contains block elements.

Example 9.9. `itemizedlist`, `orderedlist`, and `procedure`

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>` `<procedure>` `<step>` `<para>`Do this.`</para>` `</step>` `<step>` `<para>`Then do this.`</para>` `</step>` `<step>` `<para>`And now do this.`</para>` `</step>` `</procedure>`

Appearance:

- This is the first itemized item.

- This is the second itemized item.

1. This is the first ordered item.

2. This is the second ordered item.

1. Do this.

2. Then do this.

3. And now do this.

### 9.5.5. 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 `programlisting` are 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.

Example 9.10. `programlisting`

Usage:

`<para>`When finished, the program will look like this:`</para>` `<programlisting>`#include &lt;stdio.h&gt; int main(void) { printf("hello, world\n"); }`</programlisting>`

Notice how the angle brackets in the `#include` line need to be referenced by their entities instead of being included literally.

Appearance:

When finished, the program will look like this:

#include <stdio.h> int main(void) { printf("hello, world\n"); }

### 9.5.6. Callouts

A callout is a visual marker for referring to a piece of text or specific position within an example.

Callouts are marked with the `co` element. Each element must have a unique `id` assigned to it. After the example, include a `calloutlist` that describes each callout.

Example 9.11. `co` and `calloutlist`
`<para>`When finished, the program will look like this:`</para>` `<programlisting>`#include &lt;stdio.h&gt; `<co id="co-ex-include"/>` int `<co id="co-ex-return"/>` main(void) { printf("hello, world\n"); `<co id="co-ex-printf"/>` }`</programlisting>` `<calloutlist>` `<callout arearefs="co-ex-include">` `<para>`Includes the standard IO header file.`</para>` `</callout>` `<callout arearefs="co-ex-return">` `<para>`Specifies that `<function>`main()`</function>` returns an int.`</para>` `</callout>` `<callout arearefs="co-ex-printf">` `<para>`The `<function>`printf()`</function>` call that writes `<literal>`hello, world`</literal>` to standard output.`</para>` `</callout>` `</calloutlist>`

Appearance:

When finished, the program will look like this:

#include <stdio.h> int main(void) { printf("hello, world\n"); }

| Includes the standard IO header file.
| Specifies that `main()` returns an int.
| The `printf()` call that writes `hello, world` to standard output.

### 9.5.7. 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.

Example 9.12. `informaltable`

Usage:

`<informaltable pgwide="1">` `<tgroup cols="2">` `<thead>` `<row>` `<entry>`This is Column Head 1`</entry>` `<entry>`This is Column Head 2`</entry>` `</row>` `</thead>` `<tbody>` `<row>` `<entry>`Row 1, column 1`</entry>` `<entry>`Row 1, column 2`</entry>` `</row>` `<row>` `<entry>`Row 2, column 1`</entry>` `<entry>`Row 2, column 2`</entry>` `</row>` `</tbody>` `</tgroup>` `</informaltable>`

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

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.13. Tables Where `frame="none"`

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.8. 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.

Example 9.14. `screen`, `prompt`, and `userinput`

Usage:

`<screen>`&prompt.user; `<userinput>`ls -1`</userinput>` foo1 foo2 foo3 &prompt.user; `<userinput>`ls -1 | grep foo2`</userinput>` foo2 &prompt.user; `<userinput>`su`</userinput>` `<prompt>`Password: `</prompt>` &prompt.root; `<userinput>`cat foo2`</userinput>` This is the file called 'foo2'`</screen>`

Appearance:

`%` `ls -1` foo1 foo2 foo3 `%` `ls -1 | grep foo2` foo2 `%` `su` `Password:` `#` `cat foo2` This is the file called 'foo2'

### Note:

Even though we are displaying the contents of the file `foo2`, it is not marked up as `programlisting`. Reserve `programlisting` for showing fragments of files outside the context of user actions.

[2] There are other types of list element in DocBook, but we are not concerned with those at the moment.

Prev | Up | Next
9.4. Document Structure | Home | 9.6. In-line Elements

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.