FreeBSD documentation uses several Document Type Definitions (DTDs) and sets of XML entities. These are all installed by the textproc/docproj port.

The Handbook is written in DocBook XML using the FreeBSD DocBook extended DTD.

The Handbook is organized as a DocBook book. The book is divided into parts, each of which contains several chapters. chapters are further subdivided into sections (sect1) and subsections (sect2, sect3) and so on.

<chapter id="kernelconfig">
...
</chapter>

These Makefiles usually take the form of:

SUBDIR =articles
SUBDIR+=books

COMPAT_SYMLINK = en

DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

The first four non-empty lines define the make(1) variables SUBDIR, COMPAT_SYMLINK, and DOC_PREFIX.

The SUBDIR statement and COMPAT_SYMLINK statement show how to assign a value to a variable, overriding any previous value.

The second SUBDIR statement shows how a value is appended to the current value of a variable. The SUBDIR variable is now articles books.

The DOC_PREFIX assignment shows how a value is assigned to the variable, but only if it is not already defined. This is useful if DOC_PREFIX is not where this Makefile thinks it is - the user can override this and provide the correct value.

What does it all mean? SUBDIR mentions which subdirectories below this one the build process should pass any work on to.

COMPAT_SYMLINK is specific to compatibility symlinks (amazingly enough) for languages to their official encoding (doc/en would point to en_US.ISO-8859-1).

DOC_PREFIX is the path to the root of the FreeBSD Document Project tree. This is not always that easy to find, and is also easily overridden, to allow for flexibility. .CURDIR is a make(1) builtin variable with the path to the current directory.

The final line includes the FreeBSD Documentation Project's project-wide make(1) system file doc.project.mk which is the glue which converts these variables into build instructions.

These Makefiles set make(1) variables that describe how to build the documentation contained in that directory.

Here is an example:

[email protected]

DOC?= book

FORMATS?= html-split html

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

# SGML content
SRCS=  book.xml

DOC_PREFIX?= ${.CURDIR}/../../..

.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

The MAINTAINER variable allows committers to claim ownership of a document in the FreeBSD Documentation Project, and take responsibility for maintaining it.

DOC is the name (sans the .xml extension) of the main document created by this directory. SRCS lists all the individual files that make up the document. This should also include important files in which a change should result in a rebuild.

FORMATS indicates the default formats that should be built for this document. INSTALL_COMPRESSED is the default list of compression techniques that should be used in the document build. INSTALL_ONLY_COMPRESS, empty by default, should be non-empty if only compressed documents are desired in the build.

The DOC_PREFIX and include statements should be familiar already.

By inspection:

DOCFORMAT?=	docbook
MAINTAINER?=	[email protected]

PREFIX?=	/usr/local
PRI_LANG?=	en_US.ISO8859-1

.if defined(DOC)
.if ${DOCFORMAT} == "docbook"
.include "doc.docbook.mk"
.endif
.endif

.include "doc.subdir.mk"
.include "doc.install.mk"

This file is too long to explain in detail. These notes describe the most important features.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

clean: _SUBDIRUSE
	rm -f ${CLEANFILES}

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

Before running the examples in this document, install textproc/docproj from the FreeBSD Ports Collection. This is a meta-port that downloads and installs the standard programs and supporting files needed by the Documentation Project. csh(1) users must use rehash for the shell to recognize new programs after they have been installed, or log out and then log back in again.

FPIs must follow a specific syntax:

"Owner//Keyword Description//Language"

PUBLIC  "-//W3C//DTD XHTML 1.0 Transitional//EN"             "1.0/transitional.dtd"

Instead of using an FPI to indicate the DTD to which the document conforms (and therefore, which file on the system contains the DTD), the filename can be explicitly specified.

The syntax is slightly different:

<!DOCTYPE html SYSTEM "/path/to/file.dtd">

The SYSTEM keyword indicates that the XML processor should locate the DTD in a system specific fashion. This typically (but not always) means the DTD will be provided as a filename.

Using FPIs is preferred for reasons of portability. If the SYSTEM identifier is used, then the DTD must be provided and kept in the same location for everyone.

General entities are used to assign names to reusable chunks of text. These entities can only be used in the document. They cannot be used in an XML context.

To include the text of a general entity in the document, include &entity-name; in the text. For example, consider a general entity called current.version which expands to the current version number of a product. To use it in the document, write:

<para>The current version of our product is
  &current.version;.</para>

When the version number changes, edit the definition of the general entity, replacing the value. Then reprocess the document.

General entities can also be used to enter characters that could not otherwise be included in an XML document. For example, < and & cannot normally appear in an XML document. The XML parser sees the < symbol as the start of a tag. Likewise, when the & symbol is seen, the next text is expected to be an entity name.

These symbols can be included by using two predefined general entities: < and &.

General entities can only be defined within an XML context. Such definitions are usually done immediately after the DOCTYPE declaration.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>

Parameter entities, like general entities, are used to assign names to reusable chunks of text. But parameter entities can only be used within an XML context.

Parameter entity definitions are similar to those for general entities. However, parameter entries are included with %entity-name;. The definition also includes the % between the ENTITY keyword and the name of the entity.

For a mnemonic, think “Parameter entities use the Percent symbol”.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new  "%param.some more %param.text">

<!-- %param.new now contains "some more text" -->
]>

Consider some content for an XML book organized into files, one file per chapter, called chapter1.xml, chapter2.xml, and so forth, with a book.xml that will contain these chapters.

In order to use the contents of these files as the values for entities, they are declared with the SYSTEM keyword. This directs the XML parser to include the contents of the named file as the value of the entity.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- And so forth -->
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <!-- Use the entities to load in the chapters -->

  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>

Parameter entities can only be used inside an XML context. Including a file in an XML context can be used to ensure that general entities are reusable.

Suppose that there are many chapters in the document, and these chapters were reused in two different books, each book organizing the chapters in a different fashion.

The entities could be listed at the top of each book, but that quickly becomes cumbersome to manage.

Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within the document.

<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!-- Define a parameter entity to load in the chapter general entities -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- Now use the parameter entity to load in this file -->
%chapters;
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>

XHTML has tags to denote headings in the document at up to six different levels.

The largest and most prominent heading is h1, then h2, continuing down to h6.

The element's content is the text of the heading.

<h1>First section</h1>

<!-- Document introduction goes here -->

<h2>This is the heading for the first section</h2>

<!-- Content for the first section goes here -->

<h3>This is the heading for the first sub-section</h3>

<!-- Content for the first sub-section goes here -->

<h2>This is the heading for the second section</h2>

<!-- Content for the second section goes here -->

Generally, an XHTML page should have one first level heading (h1). This can contain many second level headings (h2), which can in turn contain many third level headings. Do not leave gaps in the numbering.

XHTML supports a single paragraph element, p.

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

A block quotation is an extended quotation from another document that will appear in a separate paragraph.

<p>A small excerpt from the US Constitution:</p>

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

XHTML can present the user with three types of lists: ordered, unordered, and definition.

Entries in an ordered list will be numbered, while entries in an unordered list will be preceded by bullet points. Definition lists have two sections for each entry. The first section is the term being defined, and the second section is the definition.

Ordered lists are indicated by the ol element, unordered lists by the ul element, and definition lists by the dl element.

Ordered and unordered lists contain listitems, indicated by the li element. A listitem can contain textual content, or it may be further wrapped in one or more p elements.

Definition lists contain definition terms (dt) and definition descriptions (dd). A definition term can only contain inline elements. A definition description can contain other block elements.

<p>An unordered list.  Listitems will probably be
  preceded by bullets.</p>

<ul>
  <li>First item</li>

  <li>Second item</li>

  <li>Third item</li>
</ul>

<p>An ordered list, with list items consisting of multiple
  paragraphs.  Each item (note: not each paragraph) will be
  numbered.</p>

<ol>
  <li><p>This is the first item.  It only has one paragraph.</p></li>

  <li><p>This is the first paragraph of the second item.</p>

    <p>This is the second paragraph of the second item.</p></li>

  <li><p>This is the first and only paragraph of the third
    item.</p></li>
</ol>

<dl>
  <dt>Term 1</dt>

  <dd><p>Paragraph 1 of definition 1.</p>

    <p>Paragraph 2 of definition 1.</p></dd>

  <dt>Term 2</dt>

  <dd><p>Paragraph 1 of definition 2.</p></dd>

  <dt>Term 3</dt>

  <dd><p>Paragraph 1 of definition 3.</p></dd>
</dl>

Pre-formatted text is shown to the user exactly as it is in the file. Text is shown in a fixed font. Multiple spaces and line breaks are shown exactly as they are in the file.

Wrap pre-formatted text in the pre element.

<pre>  From: [email protected]
  To: [email protected]
  Subject: New documentation available

  There is a new copy of my primer for contributors to the FreeBSD
  Documentation Project available at

    &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

  Comments appreciated.

  N</pre>

Mark up tabular information using the table element. A table consists of one or more table rows (tr), each containing one or more cells of table data (td). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then the pelement is not needed.

<p>This is a simple 2x2 table.</p>

<table>
  <tr>
    <td>Top left cell</td>

    <td>Top right cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>

A cell can span multiple rows and columns by adding the rowspan or colspan attributes with values for the number of rows or columns to be spanned.

<p>One tall thin cell on the left, two short cells next to
  it on the right.</p>

<table>
  <tr>
    <td rowspan="2">Long and thin</td>
  </tr>

  <tr>
    <td>Top cell</td>

    <td>Bottom cell</td>
  </tr>
</table>

<p>One long cell on top, two short cells below it.</p>

<table>
  <tr>
    <td colspan="2">Top cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>

<p>On a 3x3 grid, the top left block is a 2x2 set of
  cells merged into one.  The other cells are normal.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Top left large cell</td>

    <td>Top right cell</td>
  </tr>

  <tr>
    <!-- Because the large cell on the left merges into
         this row, the first <td> will occur on its
         right -->

    <td>Middle right cell</td>
  </tr>

  <tr>
    <td>Bottom left cell</td>

    <td>Bottom middle cell</td>

    <td>Bottom right cell</td>
  </tr>
</table>

Two levels of emphasis are available in XHTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis.

em is typically rendered in italic and strong is rendered in bold. This is not always the case, and should not be relied upon. According to best practices, web pages only hold structural and semantical information, and stylesheets are later applied to them. Think of semantics, not formatting, when using these tags.

<p><em>This</em> has been emphasized, while
  <strong>this</strong> has been strongly emphasized.</p>

Content that should be rendered in a fixed pitch (typewriter) typeface is tagged with tt (for “teletype”).

<p>Many system settings are stored in
  <tt>/etc</tt>.</p>

The additional FreeBSD elements are not (currently) in the Ports Collection. They are stored in the FreeBSD Subversion tree, as head/share/xml/freebsd.dtd.

FreeBSD-specific elements used in the examples below are clearly marked.

This table shows some of the most useful entities available in the FDP. For a complete list, see the *.ent files in doc/share/xml.

The content of a book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

This additional information is contained within info.

<book>
  <info>
    <title>Your Title Here</title>

    <author>
      <personname>
        <firstname>Your first name</firstname>
        <surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
          <email>Your email address</email>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the book's contents here.</para>
    </abstract>
  </info>

  …

</book>

The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

This additional information is contained within info.

<article>
  <info>
    <title>Your title here</title>

    <author>
      <personname>
	<firstname>Your first name</firstname>
	<surname>Your surname</surname>
      </personname>

      <affiliation>
	<address>
	  <email>Your email address</email></address>
	</address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the article's contents here.</para>
    </abstract>
  </info>

  …

</article>

Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books.

<chapter>
  <title>The Chapter's Title</title>

  ...
</chapter>

A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph.

<chapter>
  <title>This is An Empty Chapter</title>

  <para></para>
</chapter>

In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level.

The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5.

<chapter>
  <title>A Sample Chapter</title>

  <para>Some text in the chapter.</para>

  <sect1>
    <title>First Section</title>

    …
  </sect1>

  <sect1>
    <title>Second Section</title>

    <sect2>
      <title>First Sub-Section</title>

      <sect3>
	<title>First Sub-Sub-Section</title>

	…
      </sect3>
    </sect2>

    <sect2>
      <title>Second Sub-Section (1.2.2)</title>

      …
    </sect2>
  </sect1>
</chapter>

parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article.

<part>
  <title>Introduction</title>

  <chapter>
    <title>Overview</title>

    ...
  </chapter>

  <chapter>
    <title>What is FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>History</title>

    ...
  </chapter>
</part>

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>This is a paragraph.  It can contain just about any
  other element.</para>

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

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

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:

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

Examples can be shown with example.

<example>
  <para>Empty files can be created easily:</para>

  <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen>
</example>

Appearance:

% touch file1 file2 file3

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.

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

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.

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

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.

<procedure>
  <step>
    <para>Do this.</para>
  </step>

  <step>
    <para>Then do this.</para>
  </step>

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

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.

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

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

int
main(void)
{
    printf("hello, world\n");
}</programlisting>

#include <stdio.h>

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

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.

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

#include <stdio.h> 

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

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

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

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

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

To emphasize a particular word or phrase, use emphasis. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system.

There is no way to change the presentation of the emphasis within the document, no equivalent of HTML's b and i. If the information being presented is important, then consider presenting it in important rather than emphasis.

<para>&os; is without doubt <emphasis>the</emphasis>
  premiere &unix;-like operating system for the Intel
  architecture.</para>

Many computer terms are acronyms, words formed from the first letter of each word in a phrase. Acronyms are marked up into acronym elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below.

<para>Request For Comments (<acronym>RFC</acronym>) 1149
  defined the use of avian carriers for transmission of
  Internet Protocol (<acronym>IP</acronym>) data.  The
  quantity of <acronym>IP</acronym> data currently
  transmitted in that manner is unknown.</para>

To quote text from another document or source, or to denote a phrase that is used figuratively, use quote. Most of the markup tags available for normal text are also available from within a quote.

<para>However, make sure that the search does not go beyond the
  <quote>boundary between local and public administration</quote>,
  as <acronym>RFC</acronym> 1535 calls it.</para>

To refer to a specific key on the keyboard, use keycap. To refer to a mouse button, use mousebutton. And to refer to combinations of key presses or mouse clicks, wrap them all in keycombo.

keycombo has an attribute called action, which may be one of click, double-click, other, press, seq, or simul. The last two values denote whether the keys or buttons should be pressed in sequence, or simultaneously.

The stylesheets automatically add any connecting symbols, such as +, between the key names, when wrapped in keycombo.

<para>To switch to the second virtual terminal, press
  <keycombo action="simul"><keycap>Alt</keycap>
    <keycap>F1</keycap></keycombo>.</para>

<para>To exit <command>vi</command> without saving changes, type
  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
    <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>My window manager is configured so that
  <keycombo action="simul"><keycap>Alt</keycap>
    <mousebutton>right</mousebutton>
  </keycombo> mouse button is used to move windows.</para>

Both applications and commands are frequently referred to when writing documentation. The distinction between them is that an application is the name of a program or suite of programs that fulfill a particular task. A command is the filename of a program that the user can type and run at a command line.

It is often necessary to show some of the options that a command might take.

Finally, it is often useful to list a command with its manual section number, in the “command(number)” format so common in Unix manuals.

Mark up application names with application.

To list a command with its manual section number (which should be most of the time) the DocBook element is citerefentry. This will contain a further two elements, refentrytitle and manvolnum. The content of refentrytitle is the name of the command, and the content of manvolnum is the manual page section.

This can be cumbersome to write, and so a series of general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;.

The file that contains these entities is in doc/share/xml/man-refs.ent, and can be referred to using this FPI:

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

Therefore, the introduction to FreeBSD documentation will usually include this:

<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

…

]>

Use command to include a command name “in-line” but present it as something the user should type.

Use option to mark up the options which will be passed to a command.

When referring to the same command multiple times in close proximity, it is preferred to use the &man.command.section; notation to markup the first reference and use command to markup subsequent references. This makes the generated output, especially HTML, appear visually better.

<para><application>Sendmail</application> is the most
  widely used Unix mail application.<para>

<para><application>Sendmail</application> includes the
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
  programs.</para>

<para>One of the command line parameters to <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, will display the current
  status of messages in the mail queue.  Check this on the command
  line by running <command>sendmail -bp</command>.</para>

To refer to the name of a file, a directory, a file extension, or a device name, use filename.

<para>The source for the Handbook in English is found in
  <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
  The main file is called <filename>book.xml</filename>.
  There is also a <filename>Makefile</filename> and a
  number of files with a <filename>.ent</filename> extension.</para>

<para><filename>kbd0</filename> is the first keyboard detected
  by the system, and appears in
  <filename>/dev</filename>.</para>

To include the name of a program from the FreeBSD Ports Collection in the document, use the package tag. Since the Ports Collection can be installed in any number of locations, only include the category and the port name; do not include /usr/ports.

By default, package refers to a binary package. To refer to a port that will be built from source, set the role attribute to port.

<para>Install the <package>net/wireshark</package> binary
  package to view network traffic.</para>

<para><package role="port">net/wireshark</package> can also be
  built and installed from the Ports Collection.</para>

Information for “system items” is marked up with systemitem. The class attribute is used to identify the particular type of information shown.

<para>The local machine can always be referred to by the
  name <systemitem class="systemname">localhost</systemitem>, which will have the IP
  address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>

<para>The <systemitem class="domainname">FreeBSD.org</systemitem>
  domain contains a number of different hosts, including
  <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
  <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>

<para>When adding an <acronym>IP</acronym> alias to an
  interface (using <command>ifconfig</command>)
  <emphasis>always</emphasis> use a netmask of
  <systemitem class="netmask">255.255.255.255</systemitem> (which can
  also be expressed as
  <systemitem class="netmask">0xffffffff</systemitem>).</para>

<para>The <acronym>MAC</acronym> address uniquely identifies
  every network card in existence.  A typical
  <acronym>MAC</acronym> address looks like
  <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>

<para>To carry out most system administration functions
  requires logging in as <systemitem class="username">root</systemitem>.</para>

Email addresses are marked up as email elements. In the HTML output format, the wrapped text becomes a hyperlink to the email address. Other output formats that support hyperlinks may also make the email address into a link.

<para>An email address that does not actually exist, like
  <email>[email protected]</email>, can be used as an
  example.</para>

A FreeBSD-specific extension allows setting the role attribute to nolink to prevent the creation of the hyperlink to the email address.

<para>Sometimes a link to an email address like
  <email role="nolink">[email protected]</email> is not
  desired.</para>

Two elements exist to describe parts of Makefiles, buildtarget and varname.

buildtarget identifies a build target exported by a Makefile that can be given as a parameter to make. varname identifies a variable that can be set (in the environment, on the command line with make, or within the Makefile) to influence the process.

<para>Two common targets in a <filename>Makefile</filename>
  are <buildtarget>all</buildtarget> and
  <buildtarget>clean</buildtarget>.</para>

<para>Typically, invoking <buildtarget>all</buildtarget> will
  rebuild the application, and invoking
  <buildtarget>clean</buildtarget> will remove the temporary
  files (<filename>.o</filename> for example) created by the
  build process.</para>

<para><buildtarget>clean</buildtarget> may be controlled by a
  number of variables, including <varname>CLOBBER</varname>
  and <varname>RECURSE</varname>.</para>

Literal text, or text which should be entered verbatim, is often needed in documentation. This is text that is excerpted from another file, or which should be copied exactly as shown from the documentation into another file.

Some of the time, programlisting will be sufficient to denote this text. But programlisting is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph.

On these occasions, use literal.

<para>The <literal>maxusers 10</literal> line in the kernel
  configuration file determines the size of many system tables, and is
  a rough guide to how many simultaneous logins the system will
  support.</para>

There will often be times when the user is shown what to do, or referred to a file or command line, but cannot simply copy the example provided. Instead, they must supply some information themselves.

replaceable is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace.

<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

% man command

<para>The <literal>maxusers <replaceable>n</replaceable></literal>
  line in the kernel configuration file determines the size of many system
  tables, and is a rough guide to how many simultaneous logins the system will
  support.</para>

<para>For a desktop workstation, <literal>32</literal> is a good value
  for <replaceable>n</replaceable>.</para>

Buttons presented by a graphical user interface are marked with guibutton. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text.

<para>Edit the file, then click
  <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
  changes.</para>

System errors generated by FreeBSD are marked with errorname. This indicates the exact error that appears.

<screen><errorname>Panic: cannot mount root</errorname></screen>

Panic: cannot mount root

The following image formats are currently supported. An image file will automatically be converted to bitmap or vector image depending on the output document format.

These are the only formats in which images should be committed to the documentation repository.

Use the appropriate format for each image. Documentation will often have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format used. Do not commit the same image to the repository in two different formats.

Image files can be stored in one of several locations, depending on the document and image:

Images are included as part of a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject.

Include one imageobject, and two textobject elements. The imageobject will point to the name of the image file without the extension. The textobject elements contain information that will be presented to the user as well as, or instead of, the image itself.

Text elements are shown to the reader in several situations. When the document is viewed in HTML, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones.

This example shows how to include an image called fig1.png in a document. The image is a rectangle with an A inside it:

<mediaobject>
  <imageobject>
    <imagedata fileref="fig1"> 
  </imageobject>

  <textobject>
    <literallayout class="monospaced">+---------------+ 
|       A       |
+---------------+</literallayout>
  </textobject>

  <textobject>
    <phrase>A picture</phrase> 
  </textobject>
</mediaobject>

Images must be listed in the Makefile in the IMAGES variable. This variable must contain the names of all the source images. For example, if there are three figures, fig1.eps, fig2.png, fig3.png, then the Makefile should have lines like this in it.

…
IMAGES= fig1.eps fig2.png fig3.png
…

or

…
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
…

Again, the Makefile will work out the complete list of images it needs to build the source document, you only need to list the image files you provided.

Be careful when separating documentation into smaller files in different directories (see Section 7.7.1, “Using General Entities to Include Files”).

Suppose there is a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.xml, chapter2/chapter.xml, and chapter3/chapter.xml. If each chapter has images associated with it, place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/).

However, doing this requires including the directory names in the IMAGES variable in the Makefile, and including the directory name in the imagedata element in the document.

For example, if the book has chapter1/fig1.png, then chapter1/chapter.xml should contain:

<mediaobject>
  <imageobject>
    <imagedata fileref="chapter1/fig1"/> 
  </imageobject>

  …

</mediaobject>

The Makefile must contain:

…
IMAGES=  chapter1/fig1.png
…

Most DocBook elements accept an xml:id attribute to give that part of the document a unique name. The xml:id can be used as a target for a crossreference or link.

Any portion of the document that will be a link target must have an xml:id attribute. Assigning an xml:id to all chapters and sections, even if there are no current plans to link to them, is a good idea. These xml:ids can be used as unique anchor reference points by anyone referring to the HTML version of the document.

<chapter xml:id="introduction">
  <title>Introduction</title>

  <para>This is the introduction.  It contains a subsection,
    which is identified as well.</para>

  <sect1 xml:id="introduction-moredetails">
    <title>More Details</title>

    <para>This is a subsection.</para>
  </sect1>
</chapter>

Use descriptive values for xml:id names. The values must be unique within the entire document, not just in a single file. In the example, the subsection xml:id is constructed by appending text to the chapter xml:id. This ensures that the xml:ids are unique. It also helps both reader and anyone editing the document to see where the link is located within the document, similar to a directory path to a file.

To allow the user to jump into a specific portion of the document, even in the middle of a paragraph or an example, use anchor. This element has no content, but takes an xml:id attribute.

<para>This paragraph has an embedded
  <anchor xml:id="para1"/>link target in it.  It will not
  show up in the document.</para>

xref provides the reader with a link to jump to another section of the document. The target xml:id is specified in the linkend attribute, and xref generates the link text automatically.

<para>More information can be found
  in <xref linkend="introduction"/>.</para>

<para>More specific information can be found
  in <xref linkend="introduction-moredetails"/>.</para>

The link text is generated automatically from the chapter and section number and title elements.

The link elements described here allow the writer to define the link text. It is very important to use descriptive link text to give the reader an idea of where the link will take them. Remember that DocBook can be rendered to multiple types of media. The reader may be looking at a printed book or other form of media where there are no links. If the link text is not descriptive enough, the reader may not be able to locate the linked section.

<para>More information can be found in the
  <link linkend="introduction">sample introduction</link>.</para>

<para>More specific information can be found in the
  <link linkend="introduction-moredetails">sample introduction with more
    details</link> section.</para>

<para>Read the <link
    xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
    introduction</link>, then pick the nearest mirror from
  the list of <link
    xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
    mirror sites</link>.</para>

<para>Read this
  <link xlink:href="&url.articles.bsdl-gpl;">article
    about the BSD license</link>, or just the
  <link xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>

<para>Of course, you could stop reading this document and go to the
  <link xlink:href="&url.base;/index.html">FreeBSD home page</link> instead.</para>

<para>Wikipedia has an excellent reference on
  <link
    xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
    Partition Tables</link>.</para>

<para>Wikipedia has an excellent reference on
  GUID Partition Tables: <link
    xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"></link>.</para>

The FreeBSD XSLT and DSSSL stylesheets refer to docbook.css, which is expected to be present in the same directory as the XHTML files. The project-wide CSS file is copied from doc/share/misc/docbook.css when documents are converted to XHTML, and is installed automatically.

Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts.

Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate.

Keep explanations as short, simple, and clear as possible. Avoid empty phrases like “in order to”, which usually just means “to”. Avoid potentially patronizing words like “basically”. Avoid Latin terms like “i.e.” or “cf.”, which may be unknown outside of academic or scientific groups.

Write in a formal style. Avoid addressing the reader as “you”. For example, say “copy the file to /tmp” rather than “you can copy the file to /tmp”.

Give clear, correct, tested examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like “but really it should never be done that way”. Bad examples are worse than no examples. Give good examples, because even when warned not to use the example as shown, the reader will usually just use the example as shown.

Avoid weasel words like “should”, “might”, “try”, or “could”. These words imply that the speaker is unsure of the facts, and create doubt in the reader.

Similarly, give instructions as imperative commands: not “you should do this”, but merely “do this”.

Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them.

While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a “quick start” section that describes the most common situation, followed by an in-depth reference section.

Tags are entered in lower case, para, not PARA.

Text that appears in SGML contexts is generally written in upper case, <!ENTITY…>, and <!DOCTYPE…>, not <!entity…> and <!doctype…>.

Acronyms should be defined the first time they appear in a document, as in: “Network Time Protocol (NTP)”. After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document.

All acronyms should be enclosed in acronym tags.

The first line in each file starts with no indentation, regardless of the indentation level of the file which might contain the current file.

Opening tags increase the indentation level by two spaces. Closing tags decrease the indentation level by two spaces. Blocks of eight spaces at the start of a line should be replaced with a tab. Do not use spaces in front of tabs, and do not add extraneous whitespace at the end of a line. Content within elements should be indented by two spaces if the content runs over more than one line.

For example, the source for this section looks like this:

<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <para>The first line in each file starts with no indentation,
	<emphasis>regardless</emphasis> of the indentation level of
	the file which might contain the current file.</para>

      ...
    </sect2>
  </sect1>
</chapter>

Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags:

<para>See the <link
    linkend="gmirror-troubleshooting">Troubleshooting</link>
  section if there are problems booting.  Powering down and
  disconnecting the original <filename>ada0</filename> disk
  will allow it to be kept as an offline backup.</para>

<para>It is also possible to journal the boot disk of a &os;
  system.  Refer to the article <link
    xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
    Journaling on a Desktop PC</link> for detailed
  instructions.</para>

When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the systemitem element has been moved to the next line to avoid wrapping and indenting:

<para>With file flags, even
  <systemitem class="username">root</systemitem> can be
  prevented from removing or altering files.</para>

Configurations to help various text editors conform to these guidelines can be found in Chapter 13, Editor Configuration.

Do not commit changes to content at the same time as changes to formatting.

When content and whitespace changes are kept separate, translation teams can easily see whether a change was content that must be translated or only whitespace.

For example, if two sentences have been added to a paragraph so that the line lengths now go over 80 columns, first commit the change with the too-long lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, indicate that this is a whitespace-only change that can be ignored by translators.

Avoid line breaks in places where they look ugly or make it difficult to follow a sentence. Line breaks depend on the width of the chosen output medium. In particular, viewing the HTML documentation with a text browser can lead to badly formatted paragraphs like the next one:

Data capacity ranges from 40 MB to 15
GB.  Hardware compression …

The general entity   prohibits line breaks between parts belonging together. Use non-breaking spaces in the following places:

Edit ~/.vimrc, adding these lines:

if has("autocmd")
    au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
    au BufNewFile,BufRead *.[1-9] call ShowSpecial()
endif " has(autocmd)

function Set_Highlights()
    "match ExtraWhitespace /^\s* \s*\|\s\+$/
    highlight default link OverLength ErrorMsg
    match OverLength /\%71v.\+/
    return 0
endfunction

function ShowSpecial()
    setlocal list listchars=tab:>>,trail:*,eol:$
    hi def link nontext ErrorMsg
    return 0
endfunction " ShowSpecial()

function Set_SGML()
    setlocal number
    syn match sgmlSpecial "&[^;]*;"
    setlocal syntax=sgml
    setlocal filetype=xml
    setlocal shiftwidth=2
    setlocal textwidth=70
    setlocal tabstop=8
    setlocal softtabstop=2
    setlocal formatprg="fmt -p"
    setlocal autoindent
    setlocal smartindent
    " Rewrap paragraphs
    noremap P gqj
    " Replace spaces with tabs
    noremap T :s/        /\t/<CR>
    call ShowSpecial()
    call Set_Highlights()
    return 0
endfunction " Set_SGML()

Press P to reformat paragraphs or text that has been selected in Visual mode. Press T to replace groups of eight spaces with a tab.

Copy the sample XML syntax highlight file to the user's home directory:

% cp /usr/local/share/nano/xml.nanorc ~/.nanorc

Add these lines to the new ~/.nanorc.

syntax "xml" "\.([jrs]html?|xml|xslt?)$"
# trailing whitespace
color ,blue "[[:space:]]+$"
# multiples of eight spaces at the start a line
# (after zero or more tabs) should be a tab
color ,blue "^([TAB]*[ ]{8})+"
# tabs after spaces
color ,yellow "( )+TAB"
# highlight indents that have an odd number of spaces
color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
# lines longer than 70 characters
color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"

Process the file to create embedded tabs:

% perl -i'' -pe 's/TAB/\t/g' ~/.nanorc

Specify additional helpful options when running the editor:

% nano -AKipwz -r 70 -T8 chapter.xml

Users of csh(1) can define an alias in ~/.cshrc to automate these options:

alias nano "nano -AKipwz -r 70 -T8"

After the alias is defined, the options will be added automatically:

% nano chapter.xml