<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter id="docbook-markup">
<title>DocBook Markup</title>
<sect1 id="docbook-markup-introduction">
<title>Introduction</title>
<para>This chapter is an introduction to DocBook as it is used for
&os; documentation. DocBook is a large and complex markup
system, but the subset described here covers the parts that are
most widely used for &os; documentation. While a moderate
subset is covered, it is impossible to anticipate every
situation. Please post questions that this document does
not answer to the &a.doc;.</para>
<para>DocBook was originally developed by HaL Computer Systems and
O'Reilly & Associates to be a <acronym>DTD</acronym> for
writing technical documentation <footnote><para>A short history
can be found under <ulink
url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>.
Since 1998 it is maintained by the <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
DocBook Technical Committee</ulink>. As such, and unlike
LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
oriented towards markup that describes <emphasis>what</emphasis>
something is, rather than describing <emphasis>how</emphasis> it
should be presented.</para>
<para>The DocBook <acronym>DTD</acronym> is available from the
Ports Collection in the
<filename role="package">textproc/docbook-xml-450</filename>
port. It is automatically installed as part of the
<filename role="package">textproc/docproj</filename>
port.</para>
<note>
<title>Formal Versus Informal</title>
<para>Some elements may exist in two forms,
<emphasis>formal</emphasis> and <emphasis>informal</emphasis>.
Typically, the formal version of the element will consist of a
title followed by the informal version of the element. The
informal version will not have a title.</para>
</note>
<note>
<title>Inline Versus Block</title>
<para>In the remainder of this document, when describing
elements, <emphasis>inline</emphasis> means that the element
can occur within a block element, and does not cause a line
break. A <emphasis>block</emphasis> element, by comparison,
will cause a line break (and other processing) when it is
encountered.</para>
</note>
</sect1>
<sect1 id="docbook-markup-freebsd-extensions">
<title>&os; Extensions</title>
<para>The &os; Documentation Project has extended the
DocBook <acronym>DTD</acronym> by adding some new elements.
These elements serve to make some of the markup more
precise.</para>
<para>Where a &os;-specific element is listed below, it is
clearly marked.</para>
<para>Throughout the rest of this document, the term
<quote>DocBook</quote> is used to mean the &os;-extended
DocBook <acronym>DTD</acronym>.</para>
<note>
<para>There is nothing about these extensions that is &os;
specific, it was just felt that they were useful
enhancements for this particular project. Should anyone
from any of the other *nix camps (NetBSD, OpenBSD, Linux,
…) be interested in collaborating on a standard
DocBook extension set, please get in touch with
&a.doceng;.</para>
</note>
<para>The &os; extensions are not (currently) in the
Ports Collection. They are stored in the &os; Subversion
tree, as <ulink
url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para>
</sect1>
<sect1 id="docbook-markup-fpi">
<title>Formal Public Identifier (FPI)</title>
<para>In compliance with the DocBook guidelines for writing
<acronym>FPI</acronym>s for DocBook customizations, the
<acronym>FPI</acronym> for the &os; extended DocBook
<acronym>DTD</acronym> is:</para>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
</sect1>
<sect1 id="docbook-markup-document-structure">
<title>Document Structure</title>
<para>DocBook allows structuring documentation in several ways.
The &os; Documentation Project uses two primary types of DocBook
document: the book and the article.</para>
<para>Books are organized into <sgmltag>chapter</sgmltag>s.
This is a mandatory requirement. There may be
<sgmltag>part</sgmltag>s between the book and the chapter to
provide another layer of organization. For example, the
Handbook is arranged in this way.</para>
<para>A chapter may (or may not) contain one or more sections.
These are indicated with the <sgmltag>sect1</sgmltag> element.
If a section contains another section then use the
<sgmltag>sect2</sgmltag> element, and so on, up to
<sgmltag>sect5</sgmltag>.</para>
<para>Chapters and sections contain the remainder of the
content.</para>
<para>An article is simpler than a book, and does not use
chapters. Instead, the content of an article is organized into
one or more sections, using the same <sgmltag>sect1</sgmltag>
(and <sgmltag>sect2</sgmltag> and so on) elements that are used
in books.</para>
<para>The nature of the document being written should be used to
determine whether it is best marked up as a book or an article.
Articles are well suited to information that does not need to be
broken down into several chapters, and that is, relatively
speaking, quite short, at up to 20-25 pages of content. Books
are best suited to information that can be broken up into
several chapters, possibly with appendices and similar content
as well.</para>
<para>The <ulink url="&url.base;/docs.html">&os; tutorials</ulink>
are all marked up as articles, while this
document, the
<ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
and the <ulink url="&url.books.handbook;/index.html">FreeBSD
Handbook</ulink> are all marked up as books, for
example.</para>
<sect2 id="docbook-markup-starting-a-book">
<title>Starting a Book</title>
<para>The content of a book is contained within the
<sgmltag>book</sgmltag> 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.</para>
<para>This additional information is contained within
<sgmltag>bookinfo</sgmltag>.</para>
<example>
<title>Boilerplate <sgmltag>book</sgmltag> with
<sgmltag>bookinfo</sgmltag></title>
<!-- Cannot put this in a marked section because of the
replaceable elements -->
<programlisting><book>
<bookinfo>
<title><replaceable>Your Title Here</replaceable></title>
<author>
<firstname><replaceable>Your first name</replaceable></firstname>
<surname><replaceable>Your surname</replaceable></surname>
<affiliation>
<address><email><replaceable>Your email address</replaceable></email></address>
</affiliation>
</author>
<copyright>
<year><replaceable>1998</replaceable></year>
<holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para><replaceable>Include an abstract of the book's contents here.</replaceable></para>
</abstract>
</bookinfo>
…
</book></programlisting>
</example>
</sect2>
<sect2 id="docbook-markup-starting-an-article">
<title>Starting an Article</title>
<para>The content of the article is contained within the
<sgmltag>article</sgmltag> 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.</para>
<para>This additional information is contained within
<sgmltag>articleinfo</sgmltag>.</para>
<example>
<title>Boilerplate <sgmltag>article</sgmltag> with
<sgmltag>articleinfo</sgmltag></title>
<!-- Cannot put this in a marked section because of the
replaceable elements -->
<programlisting><article>
<articleinfo>
<title><replaceable>Your title here</replaceable></title>
<author>
<firstname><replaceable>Your first name</replaceable></firstname>
<surname><replaceable>Your surname</replaceable></surname>
<affiliation>
<address><email><replaceable>Your email address</replaceable></email></address>
</affiliation>
</author>
<copyright>
<year><replaceable>1998</replaceable></year>
<holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para><replaceable>Include an abstract of the article's contents here.</replaceable></para>
</abstract>
</articleinfo>
…
</article></programlisting>
</example>
</sect2>
<sect2 id="docbook-markup-indicating-chapters">
<title>Indicating Chapters</title>
<para>Use <sgmltag>chapter</sgmltag> to mark up your chapters.
Each chapter has a mandatory <sgmltag>title</sgmltag>.
Articles do not contain chapters, they are reserved for
books.</para>
<example>
<title>A Simple Chapter</title>
<programlisting><![CDATA[<chapter>
<title>The Chapter's Title</title>
...
</chapter>]]></programlisting>
</example>
<para>A chapter cannot be empty; it must contain elements in
addition to <sgmltag>title</sgmltag>. If you need to
include an empty chapter then just use an empty
paragraph.</para>
<example>
<title>Empty Chapters</title>
<programlisting><![CDATA[<chapter>
<title>This is An Empty Chapter</title>
<para></para>
</chapter>]]></programlisting>
</example>
</sect2>
<sect2 id="docbook-markup-sections-below-chapters">
<title>Sections Below Chapters</title>
<para>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
<sgmltag>sect<replaceable>n</replaceable></sgmltag> element.
The <replaceable>n</replaceable> indicates the section number,
which identifies the section level.</para>
<para>The first
<sgmltag>sect<replaceable>n</replaceable></sgmltag> is
<sgmltag>sect1</sgmltag>. You can have one or more of these
in a chapter. They can contain one or more
<sgmltag>sect2</sgmltag> elements, and so on, down to
<sgmltag>sect5</sgmltag>.</para>
<example>
<title>Sections in Chapters</title>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
<note>
<para>This example includes section numbers in the section
titles. You should not do this in your documents. Adding
the section numbers is carried out by the stylesheets (of
which more later), and you do not need to manage them
yourself.</para>
</note>
</sect2>
<sect2 id="docbook-markup-subdividing-part">
<title>Subdividing Using <sgmltag>part</sgmltag>
Elements</title>
<para><sgmltag>part</sgmltag>s introduce another level of
organization between <sgmltag>book</sgmltag> and
<sgmltag>chapter</sgmltag> with one or more
<sgmltag>part</sgmltag>s. This cannot be done in an
<sgmltag>article</sgmltag>.</para>
<programlisting><![CDATA[<part>
<title>Introduction</title>
<chapter>
<title>Overview</title>
...
</chapter>
<chapter>
<title>What is FreeBSD?</title>
...
</chapter>
<chapter>
<title>History</title>
...
</chapter>
</part>]]></programlisting>
</sect2>
</sect1>
<sect1 id="docbook-markup-block-elements">
<title>Block Elements</title>
<sect2 id="docbook-markup-paragraphs">
<title>Paragraphs</title>
<para>DocBook supports three types of paragraphs:
<sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
<sgmltag>simpara</sgmltag>.</para>
<para>Almost all paragraphs in &os; documentation use
<sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag>
includes a <sgmltag>title</sgmltag> element, and
<sgmltag>simpara</sgmltag> disallows some elements from
within <sgmltag>para</sgmltag>. Stick with
<sgmltag>para</sgmltag>.</para>
<example>
<title><sgmltag>para</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<para>This is a paragraph. It can contain just about any
other element.</para> ]]></programlisting>
<para>Appearance:</para>
<para>This is a paragraph. It can contain just about any
other element.</para>
</example>
</sect2>
<sect2 id="docbook-markup-block-quotations">
<title>Block Quotations</title>
<para>A block quotation is an extended quotation from another
document that should not appear within the current
paragraph. These are rarely needed.</para>
<para>Blockquotes can optionally contain a title and an
attribution (or they can be left untitled and
unattributed).</para>
<example>
<title><sgmltag>blockquote</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
</sect2>
<sect2 id="docbook-markup-tips-notes">
<title>Tips, Notes, Warnings, Cautions, Important Information
and Sidebars</title>
<para>Extra information may need to be separated from
the main body of the text. Typically this is
<quote>meta</quote> information of which the user should be
aware.</para>
<para>Depending on the nature of the information, one of
<sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
<sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
<sgmltag>important</sgmltag> should be used. Alternatively,
if the information is related to the main text but is not
one of the above, use <sgmltag>sidebar</sgmltag>.</para>
<para>The circumstances in which to choose one of these
elements over another is loosely defined by the DocBook
documentation, which suggests:</para>
<itemizedlist>
<listitem>
<para>A Note is for information that should be heeded by
all readers.</para>
</listitem>
<listitem>
<para>An Important element is a variation on Note.</para>
</listitem>
<listitem>
<para>A Caution is for information regarding possible data
loss or software damage.</para>
</listitem>
<listitem>
<para>A Warning is for information regarding possible
hardware damage or injury to life or limb.</para>
</listitem>
</itemizedlist>
<example>
<title><sgmltag>warning</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<warning>
<para>Installing FreeBSD may make you want to delete Windows from your
hard disk.</para>
</warning>]]></programlisting>
</example>
<para>Appearance:</para>
<!-- Need to do this outside of the example -->
<warning>
<para>Installing FreeBSD may make you want to delete Windows
from your hard disk.</para>
</warning>
</sect2>
<sect2 id="docbook-markup-lists-and-procedures">
<title>Lists and Procedures</title>
<para>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.</para>
<para>To do this, use <sgmltag>itemizedlist</sgmltag>,
<sgmltag>orderedlist</sgmltag>, or
<sgmltag>procedure</sgmltag><footnote><para>There are other
types of list element in DocBook, but we are not
concerned with those at the
moment.</para></footnote></para>
<para><sgmltag>itemizedlist</sgmltag> and
<sgmltag>orderedlist</sgmltag> are similar to their
counterparts in <acronym>HTML</acronym>, <sgmltag>ul</sgmltag>
and <sgmltag>ol</sgmltag>. Each one consists of one or more
<sgmltag>listitem</sgmltag> elements, and each
<sgmltag>listitem</sgmltag> contains one or more block
elements. The <sgmltag>listitem</sgmltag> elements are
analogous to <acronym>HTML</acronym>'s <sgmltag>li</sgmltag>
tags. However, unlike HTML, they are required.</para>
<para><sgmltag>procedure</sgmltag> is slightly different. It
consists of <sgmltag>step</sgmltag>s, which may in turn
consists of more <sgmltag>step</sgmltag>s or
<sgmltag>substep</sgmltag>s. Each <sgmltag>step</sgmltag>
contains block elements.</para>
<example>
<title><sgmltag>itemizedlist</sgmltag>,
<sgmltag>orderedlist</sgmltag>, and
<sgmltag>procedure</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
<!-- Cannot have <procedure> inside <example>, so this is a
cheat -->
<procedure>
<step>
<para>Do this.</para>
</step>
<step>
<para>Then do this.</para>
</step>
<step>
<para>And now do this.</para>
</step>
</procedure>
</sect2>
<sect2 id="docbook-markup-showing-file-samples">
<title>Showing File Samples</title>
<para>Fragments of a file (or perhaps a complete file) are shown
by wrapping them in the <sgmltag>programlisting</sgmltag>
element.</para>
<para>White space and line breaks within
<sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
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>
<example>
<title><sgmltag>programlisting</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<para>When finished, the program will look like
this:</para>
<programlisting>#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}</programlisting>]]></programlisting>
<para>Notice how the angle brackets in the
<literal>#include</literal> line need to be referenced by
their entities instead of being included literally.</para>
<para>Appearance:</para>
<para>When finished, the program will look like this:</para>
<programlisting>#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}</programlisting>
</example>
</sect2>
<sect2 id="docbook-markup-callouts">
<title>Callouts</title>
<para>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.</para>
<para>To do this, mark areas of interest in the example
(<sgmltag>programlisting</sgmltag>,
<sgmltag>literallayout</sgmltag>, or whatever) with the
<sgmltag>co</sgmltag> element. Each element must have a
unique <literal>id</literal> assigned to it. After the
example include a <sgmltag>calloutlist</sgmltag> that refers
back to the example and provides additional
commentary.</para>
<example>
<title><sgmltag>co</sgmltag> and
<sgmltag>calloutlist</sgmltag></title>
<programlisting><![CDATA[<para>When finished, the program will look like
this:</para>
<programlisting>#include <stdio.h> <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>]]></programlisting>
<para>Appearance:</para>
<para>When finished, the program will look like this:</para>
<programlisting>#include <stdio.h> <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>
</example>
</sect2>
<sect2 id="docbook-markup-tables">
<title>Tables</title>
<para>Unlike <acronym>HTML</acronym>, DocBook does not need
tables for layout purposes, as the stylesheet handles those
issues. Instead, just use tables for marking up tabular
data.</para>
<para>In general terms (and see the DocBook documentation for
more detail) a table (which can be either formal or informal)
consists of a <sgmltag>table</sgmltag> element. This contains
at least one <sgmltag>tgroup</sgmltag> element, which
specifies (as an attribute) the number of columns in this
table group. Within the tablegroup there is one
<sgmltag>thead</sgmltag> element, which contains elements for
the table headings (column headings), and one
<sgmltag>tbody</sgmltag> which contains the body of the
table.</para>
<para>Both <sgmltag>tgroup</sgmltag> and
<sgmltag>thead</sgmltag> contain <sgmltag>row</sgmltag>
elements, which in turn contain <sgmltag>entry</sgmltag>
elements. Each <sgmltag>entry</sgmltag> element specifies
one cell in the table.</para>
<example>
<title><sgmltag>informaltable</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
<para>Always use the <literal>pgwide</literal> attribute with
a value of <literal>1</literal> with the
<sgmltag>informaltable</sgmltag> element. A bug in Internet
Explorer can cause the table to render incorrectly if this
is omitted.</para>
<para>Table borders can be suppressed by setting the
<literal>frame</literal> attribute to <literal>none</literal>
in the <sgmltag>informaltable</sgmltag> element. For example,
<literal><informaltable frame="none"></literal>.</para>
<example>
<title>Tables Where <literal>frame="none"</literal></title>
<para>Appearance:</para>
<informaltable frame="none" 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>
</example>
</sect2>
<sect2 id="docbook-markup-examples">
<title>Examples for the User to Follow</title>
<para>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.</para>
<para>A number of distinct elements and entities come into
play here.</para>
<variablelist>
<varlistentry>
<term><sgmltag>screen</sgmltag></term>
<listitem>
<para>Everything the user sees in this example will be
on the computer screen, so the next element is
<sgmltag>screen</sgmltag>.</para>
<para>Within <sgmltag>screen</sgmltag>, white space is
significant.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>prompt</sgmltag>,
<literal>&prompt.root;</literal> and
<literal>&prompt.user;</literal></term>
<listitem>
<para>Some of the things the user will be seeing on the
screen are prompts from the computer (either from the
operating system, command shell, or application). These
should be marked up using
<sgmltag>prompt</sgmltag>.</para>
<para>As a special case, the two shell prompts for the
normal user and the root user have been provided as
entities. To indicate the user is at a shell prompt,
use one of <literal>&prompt.root;</literal> and
<literal>&prompt.user;</literal> as necessary. They
do not need to be inside
<sgmltag>prompt</sgmltag>.</para>
<note>
<para><literal>&prompt.root;</literal> and
<literal>&prompt.user;</literal> are &os;
extensions to DocBook, and are not part of the
original <acronym>DTD</acronym>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>userinput</sgmltag></term>
<listitem>
<para>When displaying text that the user should type in,
wrap it in <sgmltag>userinput</sgmltag> tags. It will
be displayed differently than system output text.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>,
and <sgmltag>userinput</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
<note>
<para>Even though we are displaying the contents of the file
<filename>foo2</filename>, it is <emphasis>not</emphasis>
marked up as <sgmltag>programlisting</sgmltag>. Reserve
<sgmltag>programlisting</sgmltag> for showing fragments of
files outside the context of user actions.</para>
</note>
</sect2>
</sect1>
<sect1 id="docbook-markup-inline-elements">
<title>In-line Elements</title>
<sect2 id="docbook-markup-inline-emphasizing">
<title>Emphasizing Information</title>
<para>To emphasize a particular word or phrase, use
<sgmltag>emphasis</sgmltag>. This may be presented as
italic, or bold, or might be spoken differently with a
text-to-speech system.</para>
<para>There is no way to change the presentation of the
emphasis within the document, no equivalent of
<acronym>HTML</acronym>'s <sgmltag>b</sgmltag> and
<sgmltag>i</sgmltag>. If the information being presented is
important, then consider presenting it in
<sgmltag>important</sgmltag> rather than
<sgmltag>emphasis</sgmltag>.</para>
<example>
<title><sgmltag>emphasis</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<para>FreeBSD is without doubt <emphasis>the</emphasis>
premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
<para>Appearance:</para>
<para>FreeBSD is without doubt <emphasis>the</emphasis>
premiere Unix like operating system for the Intel
architecture.</para>
</example>
</sect2>
<sect2 id="docbook-markup-quotations">
<title>Quotations</title>
<para>To quote text from another document or source, or to
denote a phrase that is used figuratively, use
<sgmltag>quote</sgmltag>. Most of the markup tags available
for normal text are also available from within a
<sgmltag>quote</sgmltag>.</para>
<example>
<title>Quotations</title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
</sect2>
<sect2 id="docbook-markup-keys">
<title>Keys, Mouse Buttons, and Combinations</title>
<para>To refer to a specific key on the keyboard, use
<sgmltag>keycap</sgmltag>. To refer to a mouse button, use
<sgmltag>mousebutton</sgmltag>. And to refer to
combinations of key presses or mouse clicks, wrap them all
in <sgmltag>keycombo</sgmltag>.</para>
<para><sgmltag>keycombo</sgmltag> has an attribute called
<literal>action</literal>, which may be one of
<literal>click</literal>, <literal>double-click</literal>,
<literal>other</literal>, <literal>press</literal>,
<literal>seq</literal>, or <literal>simul</literal>. The
last two values denote whether the keys or buttons should be
pressed in sequence, or simultaneously.</para>
<para>The stylesheets automatically add any connecting
symbols, such as <literal>+</literal>, between the key
names, when wrapped in <sgmltag>keycombo</sgmltag>.</para>
<example>
<title>Keys, Mouse Buttons, and Combinations</title>
<para>Usage:</para>
<programlisting><![CDATA[<para>To switch to the second virtual terminal, press
<keycombo action="simul"><keycap>Alt</keycap>
<keycap>F1</keycap></keycombo>.</para>
<para>To exit <command>vi</command> without saving changes, type
<keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
<keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
<para>My window manager is configured so that
<keycombo action="simul"><keycap>Alt</keycap>
<mousebutton>right</mousebutton>
</keycombo> mouse button is used to move windows.</para>]]></programlisting>
<para>Appearance:</para>
<para>To switch to the second virtual terminal, press
<keycombo action="simul"><keycap>Alt</keycap>
<keycap>F1</keycap></keycombo>.</para>
<para>To exit <command>vi</command> without saving changes,
type <keycombo action="seq">
<keycap>Esc</keycap>
<keycap>:</keycap>
<keycap>q</keycap>
<keycap>!</keycap></keycombo>.</para>
<para>My window manager is configured so that
<keycombo action="simul">
<keycap>Alt</keycap>
<mousebutton>right</mousebutton></keycombo> mouse button
is used to move windows.</para>
</example>
</sect2>
<sect2 id="docbook-markup-applications">
<title>Applications, Commands, Options, and Cites</title>
<para>Both applications and commands are frequently referred to
when writing documentation. The distinction between them is
that an application is the name of a program or suite of
programs that fulfill a particular task. A command is the
filename of a program that the user can type and run at a
command line.</para>
<para>It is often necessary to show some of the options that a
command might take.</para>
<para>Finally, it is often useful to list a command with its
manual section number, in the <quote>command(number)</quote>
format so common in Unix manuals.</para>
<para>Mark up application names with
<sgmltag>application</sgmltag>.</para>
<para>To list a command with its manual section
number (which should be most of the time) the DocBook
element is <sgmltag>citerefentry</sgmltag>. This will
contain a further two elements,
<sgmltag>refentrytitle</sgmltag> and
<sgmltag>manvolnum</sgmltag>. The content of
<sgmltag>refentrytitle</sgmltag> is the name of the command,
and the content of <sgmltag>manvolnum</sgmltag> is the
manual page section.</para>
<para>This can be cumbersome to write, and so a series of
<link linkend="xml-primer-general-entities">general
entities</link> have been created to make this easier.
Each entity takes the form
<literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
<para>The file that contains these entities is in
<filename>doc/share/xml/man-refs.ent</filename>, and can be
referred to using this <acronym>FPI</acronym>:</para>
<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
<para>Therefore, the introduction to &os; documentation will
usually include this:</para>
<programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
…
]></programlisting>
<para>Use <sgmltag>command</sgmltag> when to include a command
name <quote>in-line</quote> but present it as something the
user should type in.</para>
<para>Use <sgmltag>option</sgmltag> to mark up the options
which will be passed to a command.</para>
<para>When referring to the same command multiple times in
close proximity, it is preferred to use the
<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
notation to markup the first reference and use
<sgmltag>command</sgmltag> to markup subsequent references.
This makes the generated output, especially
<acronym>HTML</acronym>, appear visually better.</para>
<para>This can be confusing, and sometimes the choice is not
always clear. Hopefully this example makes it
clearer.</para>
<example>
<title>Applications, Commands, and Options</title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
<note>
<para>Notice how the
<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
notation is easier to follow.</para>
</note>
</sect2>
<sect2 id="docbook-markup-files">
<title>Files, Directories, Extensions</title>
<para>To refer to the name of a file, a directory, or a file
extension, use <sgmltag>filename</sgmltag>.</para>
<example>
<title><sgmltag>filename</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<para>The XML source for the Handbook in English is
found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first
file is called <filename>book.xml</filename> in that
directory. There is also a <filename>Makefile</filename>
and a number of files with a <filename>.ent</filename>
extension.</para>]]></programlisting>
<para>Appearance:</para>
<para>The XML source for the Handbook in English can be
found in <filename>/usr/doc/en/handbook/</filename>. The
first file is called <filename>handbook.xml</filename> in
that directory. There is also a
<filename>Makefile</filename> and a number of files with a
<filename>.ent</filename> extension.</para>
</example>
</sect2>
<sect2 id="docbook-markup-name-of-ports">
<title>The Name of Ports</title>
<note>
<title>&os; Extension</title>
<para>These elements are part of the &os; extension to
DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>
</note>
<para>To include the name of a program from the &os;
Ports Collection in the document, use the
<sgmltag>filename</sgmltag> tag with the
<literal>role</literal> attribute set to
<literal>package</literal>. Since ports can be installed in
any number of locations, only include the category and the
port name; do not include
<filename>/usr/ports</filename>.</para>
<example>
<title><sgmltag>filename</sgmltag> Tag with
<literal>package</literal> Role</title>
<para>Usage:</para>
<programlisting><![CDATA[<para>Install the <filename role="package">net/wireshark</filename> port to view network traffic.</para>]]></programlisting>
<para>Appearance:</para>
<para>Install the <filename
role="package">net/wireshark</filename> port to view
network traffic.</para>
</example>
</sect2>
<sect2 id="docbook-markup-devices">
<title>Devices</title>
<note>
<title>&os; Extension</title>
<para>These elements are part of the &os; extension to
DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>
</note>
<para>There are two names for devices: the device name as it
appears in <filename>/dev</filename>, or the name of the
device as it appears in the kernel. For this latter course,
use <sgmltag>devicename</sgmltag>.</para>
<para>Sometimes there is no choice. Some devices, such as
network cards, do not have entries in
<filename>/dev</filename>, or the entries are markedly
different from their kernel device names.</para>
<example>
<title><sgmltag>devicename</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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, network 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>]]></programlisting>
<para>Appearance:</para>
<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, network 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>
</example>
</sect2>
<sect2 id="docbook-markup-hosts">
<title>Hosts, Domains, IP Addresses, and So Forth</title>
<note>
<title>&os; Extension</title>
<para>These elements are part of the &os; extension to
DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>
</note>
<para>Identification information for networked computers (hosts)
can be marked up in several ways, depending on the nature of
the information. All of them use <sgmltag>hostid</sgmltag> as
the element, with the <literal>role</literal> attribute
selecting the type of the marked up information.</para>
<variablelist>
<varlistentry>
<term>No <literal>role</literal> attribute, or
<literal>role="hostname"</literal></term>
<listitem>
<para>With no <literal>role</literal> attribute (i.e.,
<sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>)
the marked up information is the simple hostname, such
as <literal>freefall</literal> or
<literal>wcarchive</literal>. The hostname can be
explicitly specified with
<literal>role="hostname"</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="domainname"</literal></term>
<listitem>
<para>The text is a domain name, such as
<literal>FreeBSD.org</literal> or
<literal>ngo.org.uk</literal>. There is no hostname
component.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="fqdn"</literal></term>
<listitem>
<para>The text is a Fully Qualified Domain Name, with
both hostname and domain name parts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="ipaddr"</literal></term>
<listitem>
<para>The text is an <acronym>IP</acronym> address,
probably expressed as a dotted quad.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="ip6addr"</literal></term>
<listitem>
<para>The text is an <acronym>IPv6</acronym>
address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="netmask"</literal></term>
<listitem>
<para>The text is a network mask, which might be
expressed as a dotted quad, a hexadecimal string, or as
a <literal>/</literal> followed by a number
(<acronym>CIDR</acronym> notation).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="mac"</literal></term>
<listitem>
<para>The text is an Ethernet <acronym>MAC</acronym>
address, expressed as a series of 2 digit hexadecimal
numbers separated by colons.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><sgmltag>hostid</sgmltag> and Roles</title>
<para>Usage:</para>
<programlisting><![CDATA[<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">bento.FreeBSD.org</hostid>.</para>
<para>When adding an <acronym>IP</acronym> 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 <acronym>MAC</acronym> address uniquely identifies
every network card in existence. A typical
<acronym>MAC</acronym> address looks like
<hostid role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
<para>Appearance:</para>
<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">bento.FreeBSD.org</hostid>.</para>
<para>When adding an <acronym>IP</acronym> 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 <acronym>MAC</acronym> address uniquely identifies
every network card in existence. A typical
<acronym>MAC</acronym> address looks like
<hostid role="mac">08:00:20:87:ef:d0</hostid>.</para>
</example>
</sect2>
<sect2 id="docbook-markup-usernames">
<title>Usernames</title>
<note>
<title>&os; Extension</title>
<para>These elements are part of the &os; extension to
DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>
</note>
<para>To refer to a specific username, such as
<literal>root</literal> or <literal>bin</literal>, use
<sgmltag>username</sgmltag>.</para>
<example>
<title><sgmltag>username</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<para>To carry out most system administration functions
requires logging in as <username>root</username>.</para>]]></programlisting>
<para>Appearance:</para>
<para>To carry out most system administration functions
requires logging in as <username>root</username>.</para>
</example>
</sect2>
<sect2 id="docbook-markup-describing-makefiles">
<title>Describing <filename>Makefile</filename>s</title>
<note>
<title>&os; Extension</title>
<para>These elements are part of the &os; extension to
DocBook, and do not exist in the original DocBook
<acronym>DTD</acronym>.</para>
</note>
<para>Two elements exist to describe parts of
<filename>Makefile</filename>s,
<sgmltag>maketarget</sgmltag> and
<sgmltag>makevar</sgmltag>.</para>
<para><sgmltag>maketarget</sgmltag> identifies a build target
exported by a <filename>Makefile</filename> that can be
given as a parameter to <command>make</command>.
<sgmltag>makevar</sgmltag> identifies a variable that can be
set (in the environment, on the <command>make</command>
command line, or within the <filename>Makefile</filename>)
to influence the process.</para>
<example>
<title><sgmltag>maketarget</sgmltag> and
<sgmltag>makevar</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
</sect2>
<sect2 id="docbook-markup-literal-text">
<title>Literal Text</title>
<para>Literal text, or text which should be entered verbatim, is
often needed in documentation. This is text that is excerpted
from another file, or which should be copied exactly as shown
from the documentation into another file.</para>
<para>Some of the time, <sgmltag>programlisting</sgmltag> will
be sufficient to denote this text. But
<sgmltag>programlisting</sgmltag> is not always appropriate,
particularly when you want to include a portion of a file
<quote>in-line</quote> with the rest of the
paragraph.</para>
<para>On these occasions, use
<sgmltag>literal</sgmltag>.</para>
<example>
<title><sgmltag>literal</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
</sect2>
<sect2 id="docbook-markup-replaceable">
<title>Showing Items That the User <emphasis>Must</emphasis>
Fill In</title>
<para>There will often be times when the user is shown
what to do, or referred to a file or command line, but
cannot simply copy the example provided. Instead, they
must supply some information themselves.</para>
<para><sgmltag>replaceable</sgmltag> is designed for this
eventuality. Use it <emphasis>inside</emphasis> other
elements to indicate parts of that element's content that
the user must replace.</para>
<example>
<title><sgmltag>replaceable</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
<para>Appearance:</para>
<informalexample>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>
<para><sgmltag>replaceable</sgmltag> can be used in many
different elements, including <sgmltag>literal</sgmltag>.
This example also shows that
<sgmltag>replaceable</sgmltag> should only be wrapped
around the content that the user <emphasis>is</emphasis>
meant to provide. The other content should be left
alone.</para>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
</sect2>
<sect2 id="docbook-markup-system-errors">
<title>Quoting System Errors</title>
<para>System errors generated by &os; are marked with
<sgmltag>errorname</sgmltag>. This indicates the exact error
that appears.</para>
<example>
<title><sgmltag>errorname</sgmltag></title>
<para>Usage:</para>
<programlisting><![CDATA[<screen><errorname>Panic: cannot mount root</errorname></screen>]]></programlisting>
<para>Appearance:</para>
<informalexample>
<screen><errorname>Panic: cannot mount root</errorname></screen>
</informalexample>
</example>
</sect2>
</sect1>
<sect1 id="docbook-markup-images">
<title>Images</title>
<important>
<para>Image support in the documentation is currently
extremely experimental. The mechanisms described here are
unlikely to change, but that is not guaranteed.</para>
<para>Installation of the
<filename role="package">graphics/ImageMagick</filename>
port is required. It is used to convert between the different
image formats. This port is <emphasis>not</emphasis> in
the <filename role="package">textproc/docproj</filename> meta
port, it must be installed by hand.</para>
<para>The best example of what follows in practice is the
<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
document. If the description that follows is unclear, take a
look at the files in that directory to see how everything
hangs together. Experiment with creating different formatted
versions of the document to see how the image markup appears
in the formatted output.</para>
</important>
<sect2 id="docbook-markup-image-formats">
<title>Image Formats</title>
<para>Two image formats are currently supported. Which to
choose will depend on the nature of the image.</para>
<para>Images that are primarily vector based, such as network
diagrams, time lines, and similar, should be in
<acronym>EPS</acronym> (Encapsulated Postscript) format.
These images have a <filename>.eps</filename>
extension.</para>
<para>For bitmaps, such as screen captures, use the
<acronym>PNG</acronym> (Portable Network Graphic) format.
These images have the <filename>.png</filename>
extension.</para>
<para>These are the <emphasis>only</emphasis> formats in which
images should be committed to the Subversion
repository.</para>
<para>Use the appropriate format for each image. It is to be
expected that documentation will have a mix of
<acronym>EPS</acronym> and <acronym>PNG</acronym> images. The
<filename>Makefile</filename>s ensure that the correct format
image is chosen depending on the output format that you use
for your documentation. <emphasis>Do not commit the same
image to the repository in two different
formats</emphasis>.</para>
<important>
<para>It is anticipated that the Documentation Project will
switch to using the <acronym>SVG</acronym> (Scalable Vector
Graphic) format for vector images. However, the current
state of <acronym>SVG</acronym> capable editing tools makes
this impractical.</para>
</important>
</sect2>
<sect2 id="docbook-markup-image-markup">
<title>Image Markup</title>
<para>The markup for an image is relatively simple. First,
markup a <sgmltag>mediaobject</sgmltag>. The
<sgmltag>mediaobject</sgmltag> can contain other, more
specific objects. We are concerned with two, the
<sgmltag>imageobject</sgmltag> and the
<sgmltag>textobject</sgmltag>.</para>
<para>Include one <sgmltag>imageobject</sgmltag>,
and two <sgmltag>textobject</sgmltag> elements. The
<sgmltag>imageobject</sgmltag> will point to the name of the
image file (without the extension). The
<sgmltag>textobject</sgmltag> elements contain information
that will be presented to the user as well as, or instead of,
the image itself.</para>
<para>There are two circumstances where this can
happen.</para>
<itemizedlist>
<listitem>
<para>When the reader is viewing the documentation in
<acronym>HTML</acronym>. In this case, each image will
need associated alternate text to show the user, typically
while the image is loading, or if they hover the mouse
pointer over the image.</para>
</listitem>
<listitem>
<para>When the reader is viewing the documentation in
plain text. In this case, each image should have an
<acronym>ASCII</acronym> art equivalent to show the
user.</para>
</listitem>
</itemizedlist>
<para>An example will make things easier to understand. Suppose
there is an image called <filename>fig1.png</filename> that is
to be included in the document. This image is of a rectangle
with an A inside it. The markup for this would be as
follows.</para>
<programlisting><mediaobject>
<imageobject>
<imagedata fileref="fig1"> <co id="co-image-ext"/>
</imageobject>
<textobject>
<literallayout class="monospaced">+---------------+ <co id="co-image-literal"/>
| A |
+---------------+</literallayout>
</textobject>
<textobject>
<phrase>A picture</phrase> <co id="co-image-phrase"/>
</textobject>
</mediaobject></programlisting>
<calloutlist>
<callout arearefs="co-image-ext">
<para>Include an <sgmltag>imagedata</sgmltag> element
inside the <sgmltag>imageobject</sgmltag> element. The
<literal>fileref</literal> attribute should contain the
filename of the image to include, without the extension.
The stylesheets will work out which extension should be
added to the filename automatically.</para>
</callout>
<callout arearefs="co-image-literal">
<para>The first <sgmltag>textobject</sgmltag> contains a
<sgmltag>literallayout</sgmltag> element, where the
<literal>class</literal> attribute is set to
<literal>monospaced</literal>. This is an opportunity to
demonstrate <acronym>ASCII</acronym> art skills. This
content will be used if the document is converted to plain
text.</para>
<para>Notice how the first and last lines of the content
of the <sgmltag>literallayout</sgmltag> element butt up
next to the element's tags. This ensures no extraneous
white space is included.</para>
</callout>
<callout arearefs="co-image-phrase">
<para>The second <sgmltag>textobject</sgmltag> contains a
single <sgmltag>phrase</sgmltag> element. The contents of
this phrase will become the <literal>alt</literal>
attribute for the image when this document is converted to
<acronym>HTML</acronym>.</para>
</callout>
</calloutlist>
</sect2>
<sect2 id="docbook-markup-image-makefile-entries">
<title>Image <filename>Makefile</filename> Entries</title>
<para>Images must be listed in the <filename>Makefile</filename>
in the <makevar>IMAGES</makevar> variable. This variable must
contain the names of all the <emphasis>source</emphasis>
images. For example, if there are three figures,
<filename>fig1.eps</filename>, <filename>fig2.png</filename>,
<filename>fig3.png</filename>, then the
<filename>Makefile</filename> should have lines like this in
it.</para>
<programlisting>…
IMAGES= fig1.eps fig2.png fig3.png
…</programlisting>
<para>or</para>
<programlisting>…
IMAGES= fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
…</programlisting>
<para>Again, the <filename>Makefile</filename> will work out
the complete list of images it needs to build the source
document, you only need to list the image files
<emphasis>you</emphasis> provided.</para>
</sect2>
<sect2 id="docbook-markup-images-in-subdirectories">
<title>Images and Chapters in Subdirectories</title>
<para>Be careful when separating documentation into smaller
files in different directories (see <xref
linkend="xml-primer-include-using-gen-entities"/>).</para>
<para>Suppose there is a book with three chapters, and the
chapters are stored in their own directories, called
<filename>chapter1/chapter.xml</filename>,
<filename>chapter2/chapter.xml</filename>, and
<filename>chapter3/chapter.xml</filename>. If each chapter
has images associated with it, it is suggested to place
those images in each chapter's subdirectory
(<filename>chapter1/</filename>,
<filename>chapter2/</filename>, and
<filename>chapter3/</filename>).</para>
<para>However, doing this requires including the directory
names in the <makevar>IMAGES</makevar> variable in the
<filename>Makefile</filename>, <emphasis>and</emphasis>
including the directory name in the
<sgmltag>imagedata</sgmltag> element in the document
document.</para>
<para>For example, if the book has
<filename>chapter1/fig1.png</filename>, then
<filename>chapter1/chapter.xml</filename> should
contain:</para>
<programlisting><mediaobject>
<imageobject>
<imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/>
</imageobject>
…
</mediaobject></programlisting>
<calloutlist>
<callout arearefs="co-image-dir">
<para>The directory name must be included in the
<literal>fileref</literal> attribute.</para>
</callout>
</calloutlist>
<para>The <filename>Makefile</filename> must contain:</para>
<programlisting>…
IMAGES= chapter1/fig1.png
…</programlisting>
<para>Then everything will work.</para>
</sect2>
</sect1>
<sect1 id="docbook-markup-links">
<title>Links</title>
<note>
<para>Links are also in-line elements.</para>
</note>
<sect2 id="docbook-markup-links-ids">
<title><literal>id</literal> Attributes</title>
<para>Most DocBook elements accept an <literal>id</literal>
attribute to give that part of the document a unique name.
The <literal>id</literal> can be used as a target for a
crossreference or link.</para>
<para>Any portion of the document that will be a link target
must have an <literal>id</literal> attribute. Assigning an
<literal>id</literal> to all chapters and sections, even if
there are no current plans to link to them, is a good idea.
These <literal>id</literal>s can be used as unique anchor
reference points by anyone referring to the
<acronym>HTML</acronym> version of the document.</para>
<example>
<title><literal>id</literal> on Chapters and
Sections</title>
<programlisting><![CDATA[<chapter id="introduction">
<title>Introduction</title>
<para>This is the introduction. It contains a subsection,
which is identified as well.</para>
<sect1 id="introduction-moredetails">
<title>More Details</title>
<para>This is a subsection.</para>
</sect1>
</chapter>]]></programlisting>
</example>
<para>Use descriptive values for <literal>id</literal> names.
The values must be unique within the entire document, not just
in a single file. In the example, the subsection
<literal>id</literal> is constructed by appending text to the
chapter <literal>id</literal>. This ensures that the
<literal>id</literal>s 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.</para>
<para>To allow the user to jump into a specific portion of the
document, even in the middle of a paragraph or an example, use
<sgmltag>anchor</sgmltag>. This element has no content, but
takes an <literal>id</literal> attribute.</para>
<example>
<title><sgmltag>anchor</sgmltag></title>
<programlisting><![CDATA[<para>This paragraph has an embedded
<anchor id="para1">link target in it. It will not
show up in the document.</para>]]></programlisting>
</example>
</sect2>
<sect2 id="docbook-markup-links-crossreferences">
<title>Crossreferences with <literal>xref</literal></title>
<para><sgmltag>xref</sgmltag> provides the reader with a link to
jump to another section of the document. The target
<literal>id</literal> is specified in the
<literal>linkend</literal> attribute, and
<sgmltag>xref</sgmltag> generates the link text
automatically.</para>
<example>
<title>Using <sgmltag>xref</sgmltag></title>
<para>Assume that this fragment appears somewhere in a
document that includes the <literal>id</literal>
example shown above:</para>
<programlisting><![CDATA[<para>More information can be found
in <xref linkend="introduction"/>.</para>
<para>More specific information can be found
in <xref linkend="introduction-moredetails"/>.</para>]]></programlisting>
<para>The link text will be generated automatically, looking
like (<emphasis>emphasized</emphasis> text indicates the
link text):</para>
<blockquote>
<para>More information can be found in <emphasis>Chapter
1, Introduction</emphasis>.</para>
<para>More specific information can be found in
<emphasis>Section 1.1,
<quote>More Details</quote></emphasis>.</para>
</blockquote>
</example>
<para>The link text is generated automatically from the chapter
and section number and <literal>title</literal>
elements.</para>
<note>
<para><sgmltag>xref</sgmltag> cannot link to an
<literal>id</literal> attribute on an
<sgmltag>anchor</sgmltag> element. The
<sgmltag>anchor</sgmltag> has no content, so the
<sgmltag>xref</sgmltag> cannot generate the link
text.</para>
</note>
</sect2>
<sect2 id="docbook-markup-links-to-same-or-web-documents">
<title>Linking to the Same Document or Other Documents on the
Web</title>
<para>The link elements described here allow the writer to
define the link text. It is very important to use descriptive
link text to give the reader an idea of where the link will
take them. Remember that DocBook can be rendered to multiple
types of media. The reader may be looking at a printed book
or other form of media where there are no links. If the link
text is not descriptive enough, the reader may not be able to
locate the linked section.</para>
<sect3 id="docbook-markup-links-to-same-document">
<title>Links to the Same Document</title>
<para><sgmltag>link</sgmltag> is used to create a link
within the same document. The target <literal>id</literal>
is specified in the <literal>linkend</literal> attribute.
This element wraps content, which is used for the link
text.</para>
<example>
<title>Using <sgmltag>link</sgmltag></title>
<para>Assume that this fragment appears somewhere in a
document that includes the <literal>id</literal>
example.</para>
<programlisting><![CDATA[<para>More information can be found in the
<link linkend="introduction">sample introduction</link>.</para>
<para>More specific information can be found in the
<link linkend="introduction-moredetails">sample introduction with more details</link> section.</para>]]></programlisting>
<para>This output will be generated
(<emphasis>emphasized</emphasis> text is used to show the
link text):</para>
<blockquote>
<para>More information can be found in the
<emphasis>sample introduction</emphasis>.</para>
<para>More specific information can be found in the
<emphasis>sample introduction with more details</emphasis> section.</para>
</blockquote>
</example>
<note>
<para><sgmltag>link</sgmltag> can be used to include links
to the <literal>id</literal> of an
<sgmltag>anchor</sgmltag> element, since the
<sgmltag>link</sgmltag> content defines the link
text.</para>
</note>
</sect3>
<sect3 id="docbook-markup-links-to-web-documents">
<title>Linking to Other Documents on the Web</title>
<para>The <sgmltag>ulink</sgmltag> is used to link to
external documents on the web. The <literal>url</literal>
attribute is the <acronym>URL</acronym> 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>
<example>
<title><sgmltag>ulink</sgmltag> to a &os; Documentation Web
Page</title>
<para>Link to the book or article <acronym>URL</acronym>
entity. To link to a specific chapter in a book, add a
slash and the chapter file name, followed by an optional
anchor within the chapter. For articles, link to the
article <acronym>URL</acronym> entity, followed by an
optional anchor within the article.
<acronym>URL</acronym> entities can be found in
<filename>doc/share/xml/urls.ent</filename>.</para>
<para>Usage for book links:</para>
<programlisting><![CDATA[<para>Read the <ulink
url="&url.books.handbook;/svn.html#svn-intro">SVN
introduction</ulink>, then pick the nearest mirror from
the list of <ulink
url="&url.books.handbook;/subversion-mirrors.html">Subversion
mirror sites</ulink>.</para>]]></programlisting>
<para>Appearance:</para>
<para>Read the <ulink
url="&url.books.handbook;/svn.html#svn-intro">SVN
introduction</ulink>, then pick the nearest mirror from
the list of <ulink
url="&url.books.handbook;/subversion-mirrors.html">Subversion
mirror sites</ulink>.</para>
<para>Usage for article links:</para>
<programlisting><![CDATA[<para>Read this <ulink url="&url.articles.bsdl-gpl;">article
about the BSD license</ulink>, or just the <ulink
url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>]]></programlisting>
<para>Appearance:</para>
<para>Read this <ulink url="&url.articles.bsdl-gpl;">article
about the BSD license</ulink>, or just the <ulink
url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>
</example>
<example>
<title><sgmltag>ulink</sgmltag> to a &os; Web Page</title>
<para>Usage:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Appearance:</para>
<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>
</example>
<example>
<title><sgmltag>ulink</sgmltag> to an External Web
Page</title>
<para>Usage:</para>
<programlisting><![CDATA[<para>Wikipedia has an excellent reference on
<ulink
url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</ulink>.</para>]]></programlisting>
<para>Appearance:</para>
<para>Wikipedia has an excellent reference on
<ulink
url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</ulink>.</para>
</example>
</sect3>
</sect2>
</sect1>
</chapter>