9.5. Block Elements

9.5. Block Elements
Prev	Chapter 9. DocBook Markup	Next

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:

Note is for information that should be heeded by all readers.
Important is a variation on Note.
Caution is for information regarding possible data loss or software damage.
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.
1. And now do this small thing.
2. 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 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.14. programlisting Example

Usage:

<para>When finished, the program will look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("hello, world\n");
    return 0;
}</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");
    return 0;
}

9.5.7. 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.15. co and calloutlist Example

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

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

Example 9.16. informaltable Example

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

Example 9.18. screen, prompt, and userinput Example

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.

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