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.

These Makefiles usually take the form of:

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:

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:

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

Before running the examples in this document, application software must be installed and the catalog environment variable configured.

FPIs must follow a specific syntax:

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:

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:

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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

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

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

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.

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.

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

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.

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

Extra information may need to be separated from the main body of the text. Typically this is “meta” information of which the user should be aware.

Depending on the nature of the information, one of tip, note, warning, caution, and important should be used. Alternatively, if the information is related to the main text but is not one of the above, use sidebar.

The circumstances in which to choose one of these elements over another is loosely defined by the DocBook documentation, which suggests:

Appearance:

Information often needs to be presented as lists, or as a number of steps that must be carried out in order to accomplish a particular goal.

To do this, use itemizedlist, orderedlist, or procedure^[2]

itemizedlist and orderedlist are similar to their counterparts in HTML, ul and ol. Each one consists of one or more listitem elements, and each listitem contains one or more block elements. The listitem elements are analogous to HTML's li tags. However, unlike HTML, they are required.

procedure is slightly different. It consists of steps, which may in turn consists of more steps or substeps. Each step contains block elements.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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

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

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.

To refer to the name of a file, a directory, a file extension, or a device name, use filename. For directory names, set the class attribute to directory.

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.

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

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.

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

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.

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.

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.

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.

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

Two image formats are currently supported. The type of image determines which format to use.

Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in EPS (Encapsulated Postscript) format. These images have a .eps extension.

For bitmaps, such as screen captures, use the PNG (Portable Network Graphic) format. These images have the .png extension.

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:

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.

or

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:

The Makefile must contain:

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.

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.

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.

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.

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:

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:

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

Add these lines to the new ~/.nanorc.

Process the file to create embedded tabs:

Specify additional helpful options when running the editor:

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

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