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
.
para
Usage:
Appearance:
This is a paragraph. It can contain just about any other element.
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).
blockquote
Usage:
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 |
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.
warning
Usage:
Appearance:
Installing FreeBSD may make you want to delete Windows from your hard disk.
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
[3]
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.
itemizedlist
,
orderedlist
, and
procedure
Usage:
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.
Do this.
Then do this.
And now do this.
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.
programlisting
Usage:
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:
A callout is a mechanism for referring back to an earlier piece of text or specific position within an earlier example without linking to it within the text.
To do this, mark areas of interest in the example
(programlisting
,
literallayout
, or whatever) with the
co
element. Each element must have a
unique id
assigned to it. After the
example include a calloutlist
that refers
back to the example and provides additional
commentary.
co
and
calloutlist
Appearance:
When finished, the program will look like this:
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.
informaltable
Usage:
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">
.
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 |
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
.
&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.
screen
, prompt
,
and userinput
Usage:
Appearance:
%
ls -1
foo1
foo2
foo3
%
ls -1 | grep foo2
foo2
%
su
Password:
#
cat foo2
This is the file called 'foo2'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.
[3] There are other types of list element in DocBook, but we are not concerned with those at the moment.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.