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:

MAINTAINER=nik@FreeBSD.org

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?=	doc@FreeBSD.org

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 entities 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 % entity "<!ENTITY version '1.0'>">
<!-- use the parameter entity -->
%entity;
]>

At first sight, parameter entities do not look very useful, but they make it possible to include other files into an XML document.

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: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: New documentation available

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

    &lt;URL:https://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>
    <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>

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");
    return 0;
}</programlisting>

#include <stdio.h>

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

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>

Occasionally it is useful to show a Uniform Resource Identifier (URI) without making it an active hyperlink. The uri element makes this possible:

<para>This URL shows only as text:
  <uri>https://www.FreeBSD.org</uri>.  It does not
  create a link.</para>

To create links, see Section 9.8, “Links”.

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>notreal@example.com</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">notreal@example.com</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 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.

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 element described here allows the writer to define the link text. When link text is used, it is very important to be descriptive to give the reader an idea of where the link goes. Remember that DocBook can be rendered to multiple types of media. The reader might 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 might not be able to locate the linked section.

The xlink:href attribute is the URL of the page, and the content of the element is the text that will be displayed for the user to activate.

In many situations, it is preferable to show the actual URL rather than text. This can be done by leaving out the element text entirely.

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

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

Preserve XML tags that are shown in the English original.

If <acronym>NTP</acronym> is not being used

Si <acronym>NTP</acronym> no se utiliza

Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also.

The contents of some tags should be copied verbatim, not translated:

The $FreeBSD$ version strings used in files require special handling. In examples like Example 12.1, “Creating a Spanish Translation of the Porter's Handbook”, these strings are not meant to be expanded. The English documents use $ entities to avoid including actual literal dollar signs in the file:

$FreeBSD$

The $ entities are not seen as dollar signs by the version control system and so the string is not expanded into a version string.

When a PO file is created, the $ entities used in examples are replaced with actual dollar signs. The resulting literal $FreeBSD$ string will be wrongly expanded by the version control system when the file is committed.

The same technique as used in the English documents can be used in the translation. The $ is used to replace the dollar sign in the translation entered into the PO editor:

$FreeBSD$

Manual pages are composed of several standard sections. Each section has a title in upper case, and the sections for a particular type of manual page appear in a specific order. For a category 1 General Command manual page, the sections are:

Some sections are optional, and the combination of sections for a specific type of manual page vary. Examples of the most common types are shown later in this chapter.

mdoc(7) markup is based on macros. Lines that begin with a dot contain macro commands, each two or three letters long. For example, consider this portion of the ls(1) manual page:

.Dd December 1, 2015  
.Dt LS 1
.Sh NAME  
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS  
.Nm  
.Op Fl -libxo  
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,  
.Op Fl D Ar format  
.Op Ar  
.Sh DESCRIPTION  
For each operand that names a
.Ar file
of a type other than
directory,
.Nm
displays its name as well as any requested,
associated information.
For each operand that names a
.Ar file
of type directory,
.Nm
displays the names of files contained
within that directory, as well as any requested, associated
information.

When rendered with the command man ls, the result displayed on the screen looks like this:

LS(1)                   FreeBSD General Commands Manual                  LS(1)

NAME
     ls — list directory contents

SYNOPSIS
     ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
        [file ...]

DESCRIPTION
     For each operand that names a file of a type other than directory, ls
     displays its name as well as any requested, associated information.  For
     each operand that names a file of type directory, ls displays the names
     of files contained within that directory, as well as any requested,
     associated information.

Optional values are shown inside square brackets.

The mdoc(7) markup language is not very strict. For clarity and consistency, the FreeBSD Documentation project adds some additional style guidelines:

Add a space before punctuation on a line with macros. Example:

.Sh SEE ALSO
.Xr geom 4 ,
.Xr boot0cfg 8 ,
.Xr geom 8 ,
.Xr gptboot 8

Note how the commas at the end of the .Xr lines have been placed after a space. The .Xr macro expects two parameters to follow it, the name of an external manual page, and a section number. The space separates the punctuation from the section number. Without the space, the external links would incorrectly point to section 4, or 8,.

Some very common macros will be shown here. For more usage examples, see mdoc(7), groff_mdoc(7), or search for actual use in /usr/share/man/man* directories. For example, to search for examples of the .Bd Begin display macro:

% find /usr/share/man/man* | xargs zgrep '.Bd'

The preferred basic structure for a section 1 or 8 command:

.Dd August 25, 2017
.Dt EXAMPLECMD 8
.Os
.Sh NAME
.Nm examplecmd
.Nd "command to demonstrate section 1 and 8 man pages"
.Sh SYNOPSIS
.Nm
.Op Fl v
.Sh DESCRIPTION
The
.Nm
utility does nothing except demonstrate a trivial but complete
manual page for a section 1 or 8 command.
.Sh SEE ALSO
.Xr exampleconf 5
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com

The preferred basic structure for a section 4 device driver:

.Dd August 25, 2017
.Dt EXAMPLEDRIVER 4
.Os
.Sh NAME
.Nm exampledriver
.Nd "driver to demonstrate section 4 man pages"
.Sh SYNOPSIS
To compile this driver into the kernel, add this line to the
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device exampledriver"
.Ed
.Pp
To load the driver as a module at boot, add this line to
.Xr loader.conf 5 :
.Bd -literal -offset indent
exampledriver_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an opportunity to show a skeleton or template
file for section 4 manual pages.
.Sh HARDWARE
The
.Nm
driver supports these cards from the aptly-named Nonexistent
Technologies:
.Pp
.Bl -bullet -compact
.It
NT X149.2 (single and dual port)
.It
NT X149.8 (single port)
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "flashing green light"
Something bad happened.
.It "flashing red light"
Something really bad happened.
.It "solid black light"
Power cord is unplugged.
.El
.Sh SEE ALSO
.Xr example 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 49.2 .
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com

The preferred basic structure for a section 5 configuration file:

.Dd August 25, 2017
.Dt EXAMPLECONF 5
.Os
.Sh NAME
.Nm example.conf
.Nd "config file to demonstrate section 5 man pages"
.Sh DESCRIPTION
.Nm
is an example configuration file.
.Sh SEE ALSO
.Xr example 8
.Sh AUTHORS
.An Firstname Lastname Aq Mt flastname@example.com