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 &os; 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 steps, which may in turn consists of more steps or substeps. 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 xml:id="co-ex-include"/>

int <co xml:id="co-ex-return"/>
main(void)
{
    printf("hello, world\n"); <co xml: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> 1

int 2
main(void)
{
    printf("hello, world\n"); 3
}

1

Includes the standard IO header file.

2

Specifies that main() returns an int.

3

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 1This is Column Head 2
Row 1, column 1Row 1, column 2
Row 2, column 1Row 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 1This is Column Head 2
Row 1, column 1Row 1, column 2
Row 2, column 1Row 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.

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