3.3.1.1 catalog Files

If you use the syntax above and process this document using an SGML 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:

PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"

The SGML processor would know to look up the DTD from strict.dtd in the 4.0 subdirectory of whichever directory held the catalog file that contained that line.

Look at the contents of /usr/local/share/sgml/html/catalog. This is the catalog file for the HTML DTDs that will have been installed as part of the textproc/docproj port.

3.3.1.2 SGML_CATALOG_FILES

In order to locate a catalog file, your SGML 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:

• /usr/local/share/sgml/docbook/4.1/catalog

• /usr/local/share/sgml/html/catalog

• /usr/local/share/sgml/iso8879/catalog

• /usr/local/share/sgml/jade/catalog

You should already have done this.

3.7.3.1 Use General Entities to Include Files

3.7.3.2 Use Parameter Entities to Include Files

3.8.1.1 CDATA, RCDATA

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

When an SGML 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 two content models you will probably find most useful are CDATA and RCDATA.

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.

RCDATA is for “Entity references and character data”. If the parser is in this content model then it is expecting to see characters and entities. < loses its special status, but & will still be treated as starting the beginning of a general entity.

This is particularly useful if you are including some verbatim text that contains lots of < and & characters. While you could go through the text ensuring that every < is converted to a &lt; and every & is converted to a &amp;, it can be easier to mark the section as only containing CDATA. When the SGML parser encounters this it will ignore the < and & symbols embedded in the content.

<para>Here is an example of how you would include some text
  that contained many <literal>&lt;</literal>
  and <literal>&amp;</literal> symbols.  The sample
  text is a fragment of HTML.  The surrounding text (<para> and
  <programlisting>) are from DocBook.</para>

<programlisting>
  <![ CDATA [  
    <p>This is a sample that shows you some of the elements within
      HTML.  Since the angle brackets are used so many times, it is
      simpler to say the whole example is a CDATA marked section
      than to use the entity names for the left and right angle
      brackets throughout.</p>

    <ul>
      <li>This is a listitem</li>
      <li>This is a second listitem</li>
      <li>This is a third listitem</li>
    </ul>

    <p>This is the end of the example.</p>
  ]]>
</programlisting>

3.8.1.2 INCLUDE and IGNORE

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.

<![ INCLUDE [
  This text will be processed and included.
]]>

<![ IGNORE [
  This text will not be processed or included.
]]>

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. Remember that parameter entities can only be used in SGML contexts, and the keyword of a marked section is an SGML context.

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 a parameter entity, and set its value to INCLUDE. Write your document, using marked sections to delimit content that should only appear in the electronic version. In these marked sections use the parameter entity in place of the keyword.

When you want to produce the hard-copy version of the document, change the parameter entity's value to IGNORE and reprocess the document.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % electronic.copy "INCLUDE">         
]]>

...

<![ %electronic.copy [
  This content should only appear in the electronic
  version of the document.
]]>

<!ENTITY % electronic.copy "IGNORE">

4.1.3.1 Headings

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

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

<h1>First section</h1>

<!-- Document introduction -->

<h3>Sub-section</h3>

<!-- This is bad, <h2> has been left out -->

4.1.3.2 Paragraphs

HTML supports a single paragraph element, <p>.

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

4.1.3.3 Block Quotations

A block quotation is an extended quotation from another document that should not appear within the current 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>

4.1.3.4 Lists

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.

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

4.1.3.5 Pre-formatted Text

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.

<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:http://people.FreeBSD.org/~nik/primer/index.html&gt;

  Comments appreciated.

  N</pre>

4.1.3.6 Tables

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.

<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. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows or columns that should 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>

4.1.4.1 Emphasizing Information

You have two levels of emphasis available in HTML, <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.

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

4.1.4.2 Bold and Italics

Because HTML includes presentational markup, you can also indicate that particular content should be rendered in bold or italic. The elements are <b> and <i> respectively.

<p><b>This</b> is in bold, while <i>this</i> is
  in italics.</p>

4.1.4.3 Indicating Fixed-Pitch Text

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

<p>This document was originally written by
  Nik Clayton, who can be reached by email as
  <tt>nik@FreeBSD.org</tt>.</p>

4.1.4.4 Content Size

You can indicate that content should be shown in a larger or smaller font. There are three ways of doing this.

1. Use <big> and <small> around the content you wish to change size. These tags can be nested, so <big><big>This is much bigger</big></big> is possible.

2. Use <font> with the size attribute set to +1 or -1 respectively. This has the same effect as using <big> or <small>. However, the use of this approach is deprecated.

3. Use <font> with the size attribute set to a number between 1 and 7. The default font size is 3. This approach is deprecated.

<p>This text is <small>slightly smaller</small>.  But
  this text is <big>slightly bigger</big>.</p>

<p>This text is <font size="-1">slightly smaller</font>.  But
  this text is <font size="+1">slightly bigger</font>.</p>

<p>This text is <font size="2">slightly smaller</font>.  But
  this text is <font size="4">slightly bigger</font>.</p>

4.1.5.1 Linking to Other Documents on the WWW

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

<p>More information is available at the
  <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>

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

4.1.5.2 Linking to Other Parts of Documents

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 name attribute instead of href.

<p><a name="para1">This</a> paragraph can be referenced
  in other links with the name <tt>para1</tt>.</p>

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

<p>More information can be found in the
  <a href="foo.html#para1">first paragraph</a> of
  <tt>foo.html</tt>.</p>

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

<p>More information can be found in the
  <a href="#para1">first paragraph</a> of this
  document.</p>

4.2.3.1 Starting a Book

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

<book>
  <bookinfo>
    <title>Your Title Here</title>
    
    <author>
      <firstname>Your first name</firstname>
      <surname>Your surname</surname>
      <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>
  </bookinfo>

  ...

</book>

4.2.3.2 Starting an Article

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

<article>
  <articleinfo>
    <title>Your title here</title>
    
    <author>
      <firstname>Your first name</firstname>
      <surname>Your surname</surname>
      <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 article's contents here.</para>
    </abstract>
  </articleinfo>

  ...

</article>

4.2.3.3 Indicating Chapters

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>

4.2.3.4 Sections Below Chapters

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 (1.1)</title>

    ...
  </sect1>

  <sect1>
    <title>Second Section (1.2)</title>

    <sect2>
      <title>First Sub-Section (1.2.1)</title>

      <sect3>
        <title>First Sub-Sub-Section (1.2.1.1)</title>

        ...
      </sect3>
    </sect2>

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

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

4.2.3.5 Subdividing Using <part> Elements

You can introduce another layer of organization between <book> and <chapter> with one or more <part>s. 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>

4.2.4.1 Paragraphs

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

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

4.2.4.2 Block Quotations

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

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

4.2.4.3 Tips, Notes, Warnings, Cautions, Important Information and Sidebars

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:

• A Note is for information that should be heeded by all readers.

• An Important element is a variation on Note.

• A Caution is for information regarding possible data loss or software damage.

• A Warning is for information regarding possible hardware damage or injury to life or limb.

<warning>
  <para>Installing FreeBSD may make you want to delete Windows from your
    hard disk.</para>
</warning>

Appearance:

4.2.4.4 Lists and Procedures

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>[4]

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

<procedure> is slightly different. It consists of <step>s, which may in turn consists of more <step>s or <substep>s. Each <step> contains block elements.

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

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

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

  <step>
    <para>And now do this.</para>
  </step>
</procedure>

4.2.4.5 Showing File Samples

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.

<para>When you have finished, your program should look like
  this:</para>

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

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

#include <stdio.h>

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

4.2.4.6 Callouts

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.

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

#include <stdio.h> 

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

4.2.4.7 Tables

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.

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

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

4.2.4.8 Examples for the User to Follow

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.

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

4.2.5.1 Emphasizing Information

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

<para>FreeBSD is without doubt <emphasis>the</emphasis>
  premiere Unix like operating system for the Intel architecture.</para>

4.2.5.2 Quotations

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.

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

4.2.5.3 Keys, Mouse Buttons, and Combinations

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 your work, 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>

4.2.5.4 Applications, Commands, Options, and Cites

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 fulfil 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/sgml/man-refs.ent, and can be referred to using this FPI:

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

Therefore, the introduction to your documentation will probably look like 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> 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.

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

4.2.5.5 Files, Directories, Extensions

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

<para>The SGML source for the Handbook in English can be
  found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.  The first
  file is called <filename>book.sgml</filename> in that
  directory.  You should also see a <filename>Makefile</filename>
  and a number of files with a <filename>.ent</filename>
  extension.</para>

4.2.5.6 The Name of Ports

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.

<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>

4.2.5.7 Devices

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.

<para><devicename>sio</devicename> is used for serial
  communication in FreeBSD.  <devicename>sio</devicename> manifests
  through a number of entries in <filename>/dev</filename>, including
  <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>

<para>By contrast, the networking devices, such as
  <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>

<para>In MS-DOS, the first floppy drive is referred to as
  <devicename>a:</devicename>.  In FreeBSD it is
  <filename>/dev/fd0</filename>.</para>

4.2.5.8 Hosts, Domains, IP Addresses, and So Forth

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.

<para>The local machine can always be referred to by the
  name <hostid>localhost</hostid>, which will have the IP address
  <hostid role="ipaddr">127.0.0.1</hostid>.</para>

<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
  contains a number of different hosts, including
  <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
  <hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>

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

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

4.2.5.9 Usernames

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

<para>To carry out most system administration functions you
  will need to be <username>root</username>.</para>

4.2.5.10 Describing Makefiles

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.

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

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

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

4.2.5.11 Literal Text

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

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

4.2.5.12 Showing Items That the User Must Fill In

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.

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

4.2.5.13 Quoting System Errors

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

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

“Panic: cannot mount root”

4.2.6.1 Image Formats

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

4.2.6.2 Markup

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.

• When the reader is viewing the documentation in HTML. In this case, each image will need to have associated alternate text to show the user, typically whilst the image is loading, or if they hover the mouse pointer over the image.

• When the reader is viewing the documentation in plain text. In this case, each image should have an ASCII art equivalent to show the user.

An example will probably make things easier to understand. Suppose you have an image, called fig1, 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>

4.2.6.3 Makefile Entries

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.

...
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 your source document, you only need to list the image files you provided.

4.2.6.4 Images and Chapters in Subdirectories

You must be careful when you separate your documentation into smaller files (see Section 3.7.1) in different directories.

Suppose you have a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.sgml, chapter2/chapter.sgml, and chapter3/chapter.sgml. 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.sgml should contain:

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

  ...

</mediaobject>

The Makefile must contain:

...
IMAGES=  chapter1/fig1.png
...

Then everything should just work.

4.2.7.1 Linking to Other Parts of the Same Document

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.

<chapter id="chapter1">
  <title>Introduction</title>

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

  <sect1 id="chapter1-sect1">
    <title>Sub-sect 1</title>

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

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.

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

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.

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

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

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.

<para>More information can be found in
  <link linkend="chapter1">the first chapter</link>.</para>

<para>More specific information can be found in
  <link linkend="chapter1-sect1">this</link> section.</para>

4.2.7.2 Linking to Documents on the WWW

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.

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

6.3.1.1 Physical Organization

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

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

7.3.1.1 Variables

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.

7.3.1.2 Conditionals

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.

7.3.2.1 Variables

• SUBDIR is a list of subdirectories that the build process should go further down into.

• ROOT_SYMLINKS is the name of directories that should be linked to the document install root from their actual locations, if the current language is the primary language (specified by PRI_LANG).

• COMPAT_SYMLINK is described in the Subdirectory Makefile section.

7.3.2.2 Targets and macros

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.

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

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.

clean: _SUBDIRUSE
    rm -f ${CLEANFILES}

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.

7.3.2.3 More on conditionals

• exists is another condition function which returns true if the given file exists.

• empty returns true if the given variable is empty.

• target returns true if the given target does not already exist.

7.3.2.4 Looping constructs in make (.for)

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

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

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.

10.1.4.1 Tag Spacing

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:

<article>
  <articleinfo>
    <title>NIS</title>

    <pubdate>October 1999</pubdate>

    <abstract>
      <para>...
    ...
    ...</para>
    </abstract>
  </articleinfo>

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

    <para>...</para>
  </sect1>

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

    <para>...</para>
  </sect1>
</article>

10.1.4.2 Separating Tags

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.