FreeBSD Documentation Project Primer for New Contributors

If you use the syntax above and process this document using an XML processor, the processor will need to have some way of turning the FPI into the name of the file on your computer that contains the DTD.

In order to do this it can use a catalog file. A catalog file (typically called catalog) contains lines that map FPIs to filenames. For example, if the catalog file contained the line:

The XML processor would know to look up the DTD from transitional.dtd in the 1.0 subdirectory of whichever directory held the catalog file that contained that line.

Look at the contents of /usr/local/share/xml/dtd/xhtml/catalog.xml. This is the catalog file for the XHTML DTDs that will have been installed as part of the textproc/docproj port.

In order to locate a catalog file, your XML processor will need to know where to look. Many of them feature command line parameters for specifying the path to one or more catalogs.

In addition, you can set SGML_CATALOG_FILES to point to the files. This environment variable should consist of a colon-separated list of catalog files (including their full path).

Typically, you will want to include the following files:

You should already have done this.

These keywords denote the marked sections content model, and allow you to change it from the default.

When an XML parser is processing a document it keeps track of what is called the “content model”.

Briefly, the content model describes what sort of content the parser is expecting to see, and what it will do with it when it finds it.

The content model you will probably find most useful is CDATA.

CDATA is for “Character Data”. If the parser is in this content model then it is expecting to see characters, and characters only. In this model the < and & symbols lose their special status, and will be treated as ordinary characters.

If the keyword is INCLUDE then the contents of the marked section will be processed. If the keyword is IGNORE then the marked section is ignored and will not be processed. It will not appear in the output.

By itself, this is not too useful. If you wanted to remove text from your document you could cut it out, or wrap it in comments.

It becomes more useful when you realize you can use parameter entities to control this, yet this usage is limited to entity files.

For example, suppose that you produced a hard-copy version of some documentation and an electronic version. In the electronic version you wanted to include some extra content that was not to appear in the hard-copy.

Create an entity file that defines general entities to include each chapter and guard these definitions with a parameter entity that can be set to either INCLUDE or IGNORE to control whether the entity is defined. After these conditional general entity definitions, place one more definition for each general entity to set them to an empty value. This technique makes use of the fact that entity definitions cannot be overridden but always the first definition takes effect. So you can control the inclusion of your chapter with the corrsponding parameter entity; if you set it to INCLUDE, the first general entity definition will be read and the second one will be ignored but if you set it to IGNORE, the first definition will be ignored and the second one will take effect.

XHTML allows you to denote headings in your 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. Each hn element should have the same element, but one further up the hierarchy, preceding it. Leaving gaps in the numbering is to be avoided.

XHTML supports a single paragraph element, p.

A block quotation is an extended quotation from another document that should not appear within the current paragraph.

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

Typically, each entry in an ordered list will be numbered, while each entry in an unordered list will be preceded by a bullet point. Definition lists are composed of two sections for each entry. The first section is the term being defined, and the second section is the definition of the term.

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.

You can indicate that text should be shown to the user exactly as it is in the file. Typically, this means that the text is shown in a fixed font, multiple spaces are not merged into one, and line breaks in the text are significant.

In order to do this, wrap the content 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 you do not need to include the p element.

A cell can span multiple rows and columns. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows or columns that should be spanned.

You have two levels of emphasis available in XHTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis.

Typically, em is rendered in italic and strong is rendered in bold. This is not always the case, however, and you should not rely on it. According to best practices, webpages only hold structural and semantical information and stylesheets are later applied to use these two so you should think of semantics not formatting when using these tags.

If you have content that should be rendered in a fixed pitch (typewriter) typeface, use tt (for “teletype”).

In order to include a link to another document on the WWW you must know the URL of the document you want to link to.

The link is indicated with a, and the href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of color, different mouse cursor when over the link, and so on).

These links will take the user to the top of the chosen document.

Linking to a point within another document (or within the same document) requires that the document author include anchors that you can link to.

Anchors are indicated with a and the id attribute instead of href.

To link to a named part of a document, write a normal link to that document, but include the id of the anchor after a # symbol.

If you are linking to a named anchor within the same document then you can omit the document's URL, and just include the name of the anchor (with the preceding #).

The content of the 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 should be 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 should be 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.

You can introduce another layer 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.

Most of the time you will only need to 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. You will probably only need it infrequently.

Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed).

You may need to include extra information separate from the main body of the text. Typically this is “meta” information that the user should be aware of.

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 unclear. The DocBook documentation suggests:

Appearance:

You will often need to list pieces of information to the user, or present them with a number of steps that must be carried out in order to accomplish a particular goal.

In order to do this, use itemizedlist, orderedlist, or procedure^[3]

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

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

If you want to show a fragment of a file (or perhaps a complete file) to the user, wrap it 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 mechanism for referring back to an earlier piece of text or specific position within an earlier example without linking to it within the text.

To do this, mark areas of interest in your example (programlisting, literallayout, or whatever) with the co element. Each element must have a unique id assigned to it. After the example include a calloutlist that refers back to the example and provides additional commentary.

Example 4.29. co and calloutlist

<para>When you have finished, your program should look like this:</para> <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/> int <co id="co-ex-return"/> main(void) { printf("hello, world\n"); <co id="co-ex-printf"/> }</programlisting> <calloutlist> <callout arearefs="co-ex-include"> <para>Includes the standard IO header file.</para> </callout> <callout arearefs="co-ex-return"> <para>Specifies that <function>main()</function> returns an int.</para> </callout> <callout arearefs="co-ex-printf"> <para>The <function>printf()</function> call that writes <literal>hello, world</literal> to standard output.</para> </callout> </calloutlist>

Appearance:

When you have finished, your program should look like this:

#include <stdio.h> int main(void) { printf("hello, world\n"); }

	Includes the standard IO header file.
	Specifies that main() returns an int.
	The printf() call that writes hello, world to standard output.

Unlike HTML, you do not need to use tables for layout purposes, as the stylesheet handles those issues for you. 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 you can then have 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.

If you do not want a border around the table the frame attribute can be added to the informaltable element with a value of none (i.e., <informaltable frame="none">).

A lot of the time you need to show examples for the user to follow. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, they type in another command, and so on.

A number of distinct elements and entities come into play here.

When you want 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 your document, no equivalent of HTML's b and i. If the information you are presenting is important then consider presenting it in important rather than emphasis.

To quote text from another document or source, or to denote a phrase that is used figuratively, use quote. Within a quote tag, you may use most of the markup tags available for normal text.

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.

You will frequently want to refer to both applications and commands when writing documentation. The distinction between them is simple: an application is the name for a suite (or possibly just 1) of programs that fulfill a particular task. A command is the name of a program that the user can run.

In addition, you will occasionally need to list one or more of the options that a command might take.

Finally, you will often want 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.

When you want 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 your documentation will probably look like this:

Use command when you want 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.

This can be confusing, and sometimes the choice is not always clear. Hopefully this example makes it clearer.

Whenever you wish to refer to the name of a file, a directory, or a file extension, use filename.

You might need to include the name of a program from the FreeBSD Ports Collection in the documentation. Use the filename tag with the role attribute set to package to identify these. Since ports can be installed in any number of locations, only include the category and the port name; do not include /usr/ports.

When referring to devices you have two choices. You can either refer to the device as it appears in /dev, or you can use the name of the device as it appears in the kernel. For this latter course, use devicename.

Sometimes you will not have a choice. Some devices, such as networking cards, do not have entries in /dev, or the entries are markedly different from those entries.

You can markup identification information for networked computers (hosts) in several ways, depending on the nature of the information. All of them use hostid as the element, with the role attribute selecting the type of the marked up information.

When you need to refer to a specific username, such as root or bin, use username.

Two elements exist to describe parts of Makefiles, maketarget and makevar.

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

You will often need to include “literal” text in the documentation. This is text that is excerpted from another file, or which should be copied from the documentation into another file verbatim.

Some of the time, programlisting will be sufficient to denote this text. 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 you want to show the user what to do, or refer to a file, or command line, or similar, where the user cannot simply copy the examples that you provide, but must instead include 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.

You might want to show errors generated by FreeBSD. Mark these with errorname. This indicates the exact error that appears.

We currently support two formats for images. The format you should use will depend on the nature of your image.

For images that are primarily vector based, such as network diagrams, time lines, and similar, use Encapsulated Postscript, and make sure that your images have the .eps extension.

For bitmaps, such as screen captures, use the Portable Network Graphic format, and make sure that your images have the .png extension.

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

Use the right format for the right image. It is to be expected that your documentation will have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format that you use for your documentation. Do not commit the same image to the repository in two different formats.

The markup for an image is relatively simple. First, markup a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject.

You should include one imageobject, and two textobject elements. The imageobject will point to the name of the image file that will be used (without the extension). The textobject elements contain information that will be presented to the user as well as, or instead of, the image.

There are two circumstances where this can happen.

An example will probably make things easier to understand. Suppose you have an image, called fig1.png, that you want to include in the document. This image is of a rectangle with an A inside it. The markup for this would be as follows.

<mediaobject> <imageobject> <imagedata fileref="fig1"> </imageobject> <textobject> <literallayout class="monospaced">+---------------+ | A | +---------------+</literallayout> </textobject> <textobject> <phrase>A picture</phrase> </textobject> </mediaobject>

Your images must be listed in the Makefile in the IMAGES variable. This variable should contain the name of all your source images. For example, if you have created three figures, fig1.eps, fig2.png, fig3.png, then your Makefile should have lines like this in it.

or

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

You must be careful when you separate your documentation into smaller files (see Section 3.7.1, “Using General Entities to Include Files”) in different directories.

Suppose you have 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, it is suggested to place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/).

However, if you do this you must include the directory names in the IMAGES variable in the Makefile, and you must include the directory name in the imagedata element in your document.

For example, if you have chapter1/fig1.png, then chapter1/chapter.xml should contain:

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

The Makefile must contain:

Then everything should just work.

Linking within the same document requires you to specify where you are linking from (i.e., the text the user will click, or otherwise indicate, as the source of the link) and where you are linking to (the link's destination).

Each element within DocBook has an attribute called id. You can place text in this attribute to uniquely name the element it is attached to.

This value will be used when you specify the link source.

Normally, you will only be linking to chapters or sections, so you would add the id attribute to these elements.

Obviously, you should use more descriptive values. The values must be unique within the document (i.e., not just the file, but the document the file might be included in as well). Notice how the id for the subsection is constructed by appending text to the id of the chapter. This helps to ensure that they are unique.

If you want to allow the user to jump into a specific portion of the document (possibly in the middle of a paragraph or an example), use anchor. This element has no content, but takes an id attribute.

When you want to provide the user with a link they can activate (probably by clicking) to go to a section of the document that has an id attribute, you can use either xref or link.

Both of these elements have a linkend attribute. The value of this attribute should be the value that you have used in a id attribute (it does not matter if that value has not yet occurred in your document; this will work for forward links as well as backward links).

If you use xref then you have no control over the text of the link. It will be generated for you.

Notice how the text from the link is derived from the section title or the chapter number.

If you want to control the text of the link then use link. This element wraps content, and the content will be used for the link.

Linking to external documents is much simpler, as long as you know the URL of the document you want to link to. Use ulink. The url attribute is the URL of the page that the link points to, and the content of the element is the text that will be displayed for the user to activate.

There are a number of files and directories within the handbook directory.

DOCFORMAT and MAINTAINER are assigned default values, if these are not set by the document make file.

PREFIX is the prefix under which the documentation building tools are installed. For normal package and port installation, this is /usr/local.

PRI_LANG should be set to whatever language and encoding is natural amongst users these documents are being built for. US English is the default.

The .if defined(DOC) line is an example of a make conditional which, like in other programs, defines behavior if some condition is true or if it is false. defined is a function which returns whether the variable given is defined or not.

.if ${DOCFORMAT} == "docbook", next, tests whether the DOCFORMAT variable is "docbook", and in this case, includes doc.docbook.mk.

The two .endifs close the two above conditionals, marking the end of their application.

Dependencies are described by target: dependency1 dependency2 ... tuples, where to build target, you need to build the given dependencies first.

After that descriptive tuple, instructions on how to build the target may be given, if the conversion process between the target and its dependencies are not previously defined, or if this particular conversion is not the same as the default conversion method.

A special dependency .USE defines the equivalent of a macro.

In the above, _SUBDIRUSE is now a macro which will execute the given commands when it is listed as a dependency.

What sets this macro apart from other targets? Basically, it is executed after the instructions given in the build procedure it is listed as a dependency to, and it does not adjust .TARGET, which is the variable which contains the name of the target currently being built.

In the above, clean will use the _SUBDIRUSE macro after it has executed the instruction rm -f ${CLEANFILES}. In effect, this causes clean to go further and further down the directory tree, deleting built files as it goes down, not on the way back up.

.for provides a way to repeat a set of instructions for each space-separated element in a variable. It does this by assigning a variable to contain the current element in the list being examined.

In the above, if SUBDIR is empty, no action is taken; if it has one or more elements, the instructions between .for and .endfor would repeat for every element, with entry being replaced with the value of the current element.

Tags that start at the same indent as a previous tag should be separated by a blank line, and those that are not at the same indent as a previous tag should not:

Tags like itemizedlist which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves.

Tags like para and term do not need other tags to contain normal character data, and their contents begin immediately after the tag, on the same line.

The same applies to when these two types of tags close.

This leads to an obvious problem when mixing these tags.

When a starting tag which cannot contain character data directly follows a tag of the type that requires other tags within it to use character data, they are on separate lines. The second tag should be properly indented.

When a tag which can contain character data closes directly after a tag which cannot contain character data closes, they co-exist on the same line.