aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml2210
1 files changed, 2210 insertions, 0 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
new file mode 100644
index 0000000000..e749463375
--- /dev/null
+++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -0,0 +1,2210 @@
+<!-- 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.
+-->
+
+<chapter id="sgml-markup">
+ <title>SGML Markup</title>
+
+ <para>This chapter describes the three markup languages you will encounter
+ when you contribute to the FreeBSD documentation project. Each section
+ describes the markup language, and details the markup that you are likely
+ to want to use, or that is already in use.</para>
+
+ <para>These markup languages contain a large number of elements, and it can
+ be confusing sometimes to know which element to use for a particular
+ situation. This section goes through the elements you are most likely to
+ need, and gives examples of how you would use them.</para>
+
+ <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
+ that would just reiterate the documentation for each language. The aim of
+ this section is to list those elements more likely to be useful to you. If
+ you have a question about how best to markup a particular piece of
+ content, please post it to the FreeBSD Documentation Project mailing list
+ <email>freebsd-doc@freebsd.org</email>.</para>
+
+ <note>
+ <title>Inline vs. 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>
+ <title>HTML</title>
+
+ <para>HTML, the HyperText Markup Language, is the markup language of
+ choice on the World Wide Web. More information can be found at
+ &lt;URL:<ulink
+ url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</para>
+
+ <para>HTML is used to markup pages on the FreeBSD web site. It should not
+ (generally) be used to mark up other documention, since DocBook offers a
+ far richer set of elements to choose from. Consequently, you will
+ normally only encounter HTML pages if you are writing for the web
+ site.</para>
+
+ <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
+ latest, 4.0 (available in both <emphasis>strict</emphasis> and
+ <emphasis>loose</emphasis> variants).</para>
+
+ <para>The HTML DTDs are available from the ports collection in the
+ <filename>textproc/html</filename> port. They are automatically
+ installed as part of the <filename>textproc/docproj</filename> port.</para>
+
+ <sect2>
+ <title>Formal Public Identifier (FPI)</title>
+
+ <para>There are a number of HTML FPIs, depending upon the version (also
+ known as the level) of HTML that you want to declare your document to
+ be compliant with.</para>
+
+ <para>The majority of HTML documents on the FreeBSD web site comply with
+ the loose version of HTML 4.0.</para>
+
+ <programlisting>
+PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Sectional elements</title>
+
+ <para>An HTML document is normally split in to two sections. The first
+ section, called the <emphasis>head</emphasis>, contains
+ meta-information about the document, such as its title, the name of
+ the author, the parent document, and so on. The second section, the
+ <emphasis>body</emphasis>, contains the content that will be displayed
+ to the user.</para>
+
+ <para>These sections are indicated with <sgmltag>head</sgmltag> and
+ <sgmltag>body</sgmltag> elements respectively. These elements are
+ contained within the top-level <sgmltag>html</sgmltag> element.</para>
+
+ <example>
+ <title>Normal HTML document structure</title>
+
+ <programlisting>
+&lt;html>
+ &lt;head>
+ &lt;title><replaceable>The document's title</replaceable>&lt;/title>
+ &lt;/head>
+
+ &lt;body>
+
+ &hellip;
+
+ &lt;/body>
+&lt;/html></programlisting>
+ </example>
+ </sect2>
+
+ <sect2>
+ <title>Block elements</title>
+
+ <sect3>
+ <title>Headings</title>
+
+ <para>HTML allows you to denote headings in your document, at up to
+ six different levels.</para>
+
+ <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>,
+ then <sgmltag>h2</sgmltag>, continuing down to
+ <sgmltag>h6</sgmltag>.</para>
+
+ <para>The element's content is the text of the heading.</para>
+
+ <example>
+ <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<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 -->]]></programlisting>
+ </example>
+
+ <para>Generally, an HTML page should have one first level heading
+ (<sgmltag>h1</sgmltag>). This can contain many second level headings
+ (<sgmltag>h2</sgmltag>), which can in turn contain many third level
+ headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag>
+ element should have the same element, but one further up the
+ hierarchy, preceeding it. Leaving gaps in the numbering is to be
+ avoided.</para>
+
+ <example>
+ <title>Bad ordering of
+ <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<h1>First section</h1>
+
+<!-- Document introduction -->
+
+<h3>Sub-section</h3>
+
+<!-- This is bad, <h2> has been left out -->]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Paragraphs</title>
+
+ <para>HTML supports a single paragraph element,
+ <sgmltag>p</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>p</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>This is a paragraph. It can contain just about any
+ other element.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Block quotations</title>
+
+ <para>A block quotation is an extended quotation from another document
+ that should not appear within the current paragraph.</para>
+
+ <example>
+ <title><sgmltag>blockquote</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<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>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Lists</title>
+
+ <para>You can present the user with three types of lists, ordered,
+ unordered, and definition.</para>
+
+ <para>Typically, each entry in an ordered list will be numbered, while
+ each entry in an unordered list will be proceeded 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.</para>
+
+ <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
+ element, unordered lists by the <sgmltag>ul</sgmltag> element, and
+ definition lists by the <sgmltag>dl</sgmltag> element.</para>
+
+ <para>Ordered and unordered lists contain listitems, indicated by the
+ <sgmltag>li</sgmltag> element. A listitem can contain textual
+ content, or it may be further wrapped in one or more
+ <sgmltag>p</sgmltag> elements.</para>
+
+ <para>Definition lists contain definition terms
+ (<sgmltag>dt</sgmltag>) and definition descriptions
+ (<sgmltag>dd</sgmltag>). A definition term can only contain inline
+ elements. A definition description can contain other block
+ elements.</para>
+
+ <example>
+ <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>An unordered list. Listitems will probably be
+ preceeded 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>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Definition lists with <sgmltag>dl</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<dl>
+ <dt>Term 1</dt>
+
+ <dd><p>Paragraph 1 of definition 1.</p></dd>
+
+ <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>Paragraph 1 of definition 3. Note that the &lt;p&gt;
+ element is not required in the single paragraph case.</dd>
+</dl>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Pre-formatted text</title>
+
+ <para>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 in to one, and line
+ breaks in the text are significant.</para>
+
+ <para>In order to do this, wrap the content in the
+ <sgmltag>pre</sgmltag> element.</para>
+
+ <example>
+ <title><sgmltag>pre</sgmltag></title>
+
+ <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
+ message;</para>
+
+ <programlisting>
+<![ CDATA [<pre>
+ From: nik@freebsd.org
+ To: freebsd-doc@freebsd.org
+ Subject: New documentation available
+
+ There's a new copy of my primer for contributers to the FreeBSD
+ Documentation Project available at
+
+ <URL:http://www.freebsd.org/~nik/primer/index.html>
+
+ Comments appreciated.
+
+ N
+</pre>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Tables</title>
+
+ <note>
+ <para>Most text-mode browsers (such as Lynx) do not render tables
+ particularly effectively. If you are relying on the tabular
+ display of your content, you should consider using alternative
+ markup to prevent confusion.</para>
+ </note>
+
+ <para>Mark up tabular information using the <sgmltag>table</sgmltag>
+ element. A table consists of one or more table rows
+ (<sgmltag>tr</sgmltag>), each containing one or more cells of table
+ data (<sgmltag>td</sgmltag>). 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
+ <sgmltag>p</sgmltag> element.</para>
+
+ <example>
+ <title>Simple use of <sgmltag>table</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<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>]]></programlisting></example>
+
+ <para>A cell can span multiple rows and columns. To indicate this, add
+ the <literal>rowspan</literal> and/or <literal>colspan</literal>
+ attributes, with values indicating the number of rows of columns
+ that should be spanned.</para>
+
+ <example>
+ <title>Using <literal>rowspan</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<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>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Using <literal>colspan</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<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>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Using <literal>rowspan</literal> and
+ <literal>colspan</literal> together</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
+ cells merged in to 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 in to
+ 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>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>In-line elements</title>
+
+ <sect3>
+ <title>Emphasising information</title>
+
+ <para>You have two levels of emphasis available in HTML,
+ <sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal
+ level of emphasis and <sgmltag>strong</sgmltag> indicates stronger
+ emphasis.</para>
+
+ <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
+ <sgmltag>strong</sgmltag> is rendered in bold. This is not always
+ the case however, and you should not rely on it.</para>
+
+ <example>
+ <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p><em>This</em> has been emphasised, while
+ <strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Bold and italics</title>
+
+ <para>Because HTML includes presentational markup, you can also
+ indicate that particular content should be rendered in bold or
+ italic. The elements are <sgmltag>b</sgmltag> and
+ <sgmltag>i</sgmltag> respectively.</para>
+
+ <example>
+ <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
+
+ <programlisting>
+<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
+ in italics.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Indicating fixed pitch text</title>
+
+ <para>If you have content that should be rendered in a fixed pitch
+ (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
+ &ldquo;teletype&rdquo;).</para>
+
+ <example>
+ <title><sgmltag>tt</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>This document was originally written by
+ Nik Clayton, who can be reached by e-mail as
+ <tt>nik@freebsd.org</tt>.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Content size</title>
+
+ <para>You can indicate that content should be shown in a larger or
+ smaller font. There are three ways of doing this.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag>
+ around the content you wish to change size. These tags can be
+ nested, so <literal>&lt;big&gt;&lt;big&gt;This is much
+ bigger&lt;/big&gt;&lt;/big&gt;</literal> is possible.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
+ attribute set to <literal>+1</literal> or <literal>-1</literal>
+ respectively. This has the same effect as using
+ <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the
+ use of this approach is deprecated.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
+ attribute set to a number between 1 and 7. The default font size
+ is <literal>3</literal>. This approach is deprecated.</para>
+ </listitem>
+ </orderedlist>
+
+ <example>
+ <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
+ <sgmltag>font</sgmltag></title>
+
+ <para>The following fragments all do the same thing.</para>
+
+ <programlisting>
+<![ CDATA [<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>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Links</title>
+
+ <note>
+ <para>Links are also in-line elements.</para>
+ </note>
+
+ <sect3>
+ <title>Linking to other documents on the WWW</title>
+
+ <para>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.</para>
+
+ <para>The link is indicated with <sgmltag>a</sgmltag>, and the
+ <literal>href</literal> 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
+ colour, different mouse cursor when over the link, and so on).</para>
+
+ <example>
+ <title>Using <literal>&lt;a href="..."&gt;</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>More information is available at the
+ <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting>
+ </example>
+
+ <para>These links will take the user to the top of the chosen
+ document.</para>
+ </sect3>
+
+ <sect3>
+ <title>Linking to other parts of documents</title>
+
+ <para>Linking to a point within another document (or within the same
+ document) requires that the document author include anchors that you
+ can link to.</para>
+
+ <para>Anchors are indicated with <sgmltag>a</sgmltag> and the
+ <literal>name</literal> attribute instead of
+ <literal>href</literal>.</para>
+
+ <example>
+ <title>Using <literal>&lt;a name="..."&gt;</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
+ in other links with the name <tt>para1</tt>.</p>]]></programlisting>
+ </example>
+
+ <para>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
+ <literal>#</literal> symbol.</para>
+
+ <example>
+ <title>Linking to a named part of another document</title>
+
+ <para>Assume that the <literal>para1</literal> example resides in a
+ document called <filename>foo.html</filename>.</para>
+
+ <programlisting>
+<![ CDATA [<p>More information can be found in the
+ <a href="foo.html#para1">first paragraph</a> of
+ <tt>foo.html</tt>.</p>]]></programlisting>
+ </example>
+
+ <para>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 preceeding <literal>#</literal>).</para>
+
+ <example>
+ <title>Linking to a named part of another document</title>
+
+ <para>Assume that the <literal>para1</literal> example resides in
+ this document</para>
+
+ <programlisting>
+<![ CDATA [<p>More information can be found in the
+ <a href="#para1">first paragraph</a> of this
+ document.</p>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>DocBook</title>
+
+ <para>DocBook was designed by the <ulink
+ url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be
+ a DTD for writing technical documentation. As such, and unlike LinuxDoc
+ and HTML, DocBook is very heavily orientated towards markup that
+ describes <emphasis>what</emphasis> something is, rather than describing
+ <emphasis>how</emphasis> it should be presented.</para>
+
+ <note>
+ <title><literal>formal</literal> vs. <literal>informal</literal></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 information
+ version of the element. The informal version will not have a
+ title.</para>
+ </note>
+
+ <para>The DocBook DTD is available from the ports collection in the
+ <filename>textproc/docbook</filename> port. It is automatically
+ installed as part of the <filename>textproc/docproj</filename>
+ port.</para>
+
+ <sect2>
+ <title>FreeBSD extensions</title>
+
+ <para>The FreeBSD Documentation Project has extended the DocBook DTD by
+ adding some new elements. These elements serve to make some of the
+ markup more precise.</para>
+
+ <para>Where a FreeBSD specific element is listed below it is clearly
+ marked.</para>
+
+ <para>Throughout the rest of this document, the term
+ &ldquo;DocBook&rdquo; is used to mean the FreeBSD extended DocBook
+ DTD.</para>
+
+ <note>
+ <para>There is nothing about these extensions that is FreeBSD
+ 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, &hellip;) be interested in
+ collaborating on a standard DocBook extension set, please get in
+ touch with Nik Clayton <email>nik@freebsd.org</email>.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Formal Public Identifier (FPI)</title>
+
+ <para>In compliance with the DocBook guidelines for writing FPIs for
+ DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
+ is;</para>
+
+ <programlisting>
+PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Sectional elements</title>
+
+ <para>DocBook contains a number of elements for marking up the structure
+ of a book.</para>
+
+ <para>Generally, the top level (first) element will be
+ <sgmltag>book</sgmltag>.</para>
+
+ <para>A book is organised 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 organisation. 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>
+
+ <sect3>
+ <title>Starting a book</title>
+
+ <para>The content of the 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 should be contained within
+ <sgmltag>bookinfo</sgmltag>.</para>
+
+ <example>
+ <title>Boilerplate <sgmltag>book</sgmltag> with
+ <sgmltag>bookinfo</sgmltag></title>
+
+ <!-- Can't put this in a marked section because of the
+ replaceable elements -->
+ <programlisting>
+&lt;book>
+ &lt;bookinfo>
+ &lt;title><replaceable>Your title here</replaceable>&lt;/title>
+
+ &lt;author>
+ &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
+ &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
+ &lt;affiliation>
+ &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
+ &lt;/affiliation>
+ &lt;/author>
+
+ &lt;copyright>
+ &lt;year><replaceable>1998</replaceable>&lt;/year>
+ &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
+ &lt;/copyright>
+
+ &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
+
+ &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
+
+ &lt;abstract>
+ &lt;para><replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para>
+ &lt;/abstract>
+ &lt;/bookinfo>
+
+ &hellip;
+
+&lt;/book></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Indicating chapters</title>
+
+ <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each
+ chapter has a mandatory <sgmltag>title</sgmltag>.</para>
+
+ <example>
+ <title>A simple chapter</title>
+
+ <programlisting>
+<![ CDATA [<chapter>
+ <title>The chapter's title</title>
+
+ ...
+</chapter>]]></programlisting>
+ </example>
+
+ <para>A chapter can not 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>
+ </sect3>
+
+ <sect3>
+ <title>Sections below chapters</title>
+
+ <para>Chapters can be broken up into sections, subsections, and so
+ on. 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>
+ </sect3>
+
+ <sect3>
+ <title>Subdividing using <sgmltag>part</sgmltag>s</title>
+
+ <para>You can introduce another layer of organisation between
+ <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
+ more <sgmltag>part</sgmltag>s.</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>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Block elements</title>
+
+ <sect3>
+ <title>Paragraphs</title>
+
+ <para>DocBook supports three types of paragraphs;
+ <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
+ <sgmltag>simpara</sgmltag>.</para>
+
+ <para>Most of the time you will only need to 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>Use:</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>
+ </sect3>
+
+ <sect3>
+ <title>Block quotations</title>
+
+ <para>A block quotation is an extended quotation from another document
+ that should not appear within the current paragraph. You will
+ probably only need it infrequently.</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>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>A small excerpt from the US Constitution;</para>
+
+<blockquote>
+ <title>Preamble to the Constitution of the United States</para>
+
+ <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>
+
+ <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>
+ </sect3>
+
+ <sect3>
+ <title>Tips, notes, warnings, cautions, important information and
+ sidebars.</title>
+
+ <para>You may need to include extra information separate from the
+ main body of the text. Typically this is &ldquo;meta&rdquo;
+ information that the user should be aware of.</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 unclear. The DocBook documentation 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>Use:</para>
+
+ <programlisting>
+<![ CDATA [<warning>
+ <para>Installing FreeBSD may make you want to delete Windows from your
+ harddisk.</para>
+</warning>]]></programlisting>
+ </example>
+
+ <!-- Need to do this outside of the example -->
+ <warning>
+ <para>Installing FreeBSD may make you want to delete Windows from
+ your harddisk.</para>
+ </warning>
+ </sect3>
+
+ <sect3>
+ <title>Lists and procedures</title>
+
+ <para>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.</para>
+
+ <para>In order 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're not concerned with those at
+ the moment.</para>
+ </footnote>
+ </para>
+
+ <para><sgmltag>itemizedlist</sgmltag> and
+ <sgmltag>orderedlist</sgmltag> are similar to the counterparts in
+ HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one
+ consists of one or more <sgmltag>listentry</sgmltag> elements, and
+ each <sgmltag>listentry</sgmltag> contains one or more block
+ elements. The <sgmltag>listentry</sgmltag> elements are analagous to
+ HTMLs <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>Use:</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>]]></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>
+ </sect3>
+
+ <sect3>
+ <title>Showing file samples</title>
+
+ <para>If you want to show a fragment of a file (or perhaps a complete
+ file) to the user, wrap it 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 closing tag should
+ appear on the same line as the last line of the output, otherwise a
+ spurious blank line will be included.</para>
+
+ <example>
+ <title><sgmltag>programlisting</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA[<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>]]></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 you have finished, your program should look like
+ this;</para>
+
+ <programlisting>
+#include &lt;stdio.h&gt;
+
+int
+main(void)
+{
+ printf("hello, world\n");
+}</programlisting>
+ </example>
+
+ <note>
+ <para>There is a mechanism within DocBook for referring to sections
+ of a previously occuring <sgmltag>programlisting</sgmltag>, called
+ callouts (see <sgmltag>programlistingco</sgmltag> for more
+ information). I don't fully understand (i.e., have never used)
+ this feature, so can't document it here. For the mean time, you
+ can include line numbers within the content, and then refer to
+ them later on in your description. That will change, as soon as I
+ find the time to understand and document callouts.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Tables</title>
+
+ <para>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.</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 you
+ can then have 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>Use:</para>
+
+ <programlisting>
+<![ CDATA [<informaltable>
+ <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>
+ <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>If you don't want a border around the table the
+ <literal>frame</literal> attribute can be added to the
+ <sgmltag>informaltable</sgmltag> element with a value of
+ <literal>none</literal> (i.e., <literal>&lt;informaltable
+ frame="none"&gt;</literal>).</para>
+
+ <example>
+ <title>Tables where <literal>frame="none"</literal></title>
+
+ <para>Appearance:</para>
+
+ <informaltable frame="none">
+ <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>
+ </sect3>
+
+ <sect3>
+ <title>Examples for the user to follow</title>
+
+ <para>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.</para>
+
+ <para>A number of distinct elements and entities come in to play
+ here.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><sgmltag>informalexample</sgmltag></term>
+
+ <listitem>
+ <para>Most of the time these examples will occur
+ &ldquo;mid-flow&rdquo; as it were, and you won't need to put a
+ title on them. So, most of the time, the outermost element
+ will be <sgmltag>informalexample</sgmltag>. For those times
+ when you do need to include a title on the example, use
+ <sgmltag>example</sgmltag>.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>&amp;prompt.root;</literal> and
+ <literal>&amp;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 OS, 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. Every
+ time you want to indicate the user is at a shell prompt, use
+ one of <literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal> as necessary. They do not
+ need to be inside <sgmltag>prompt</sgmltag>.</para>
+
+ <note>
+ <para><literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal> are FreeBSD
+ extensions to DocBook, and are not part of the original
+ DTD.</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 probably be
+ displayed differently to the user.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title><sgmltag>informalexample</sgmltag>,
+ <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
+ <sgmltag>userinput</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<informalexample>
+ <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>
+</informalexample>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <informalexample>
+ <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>
+ </informalexample>
+ </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>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>In-line elements</title>
+
+ <sect3>
+ <title>Emphasising information</title>
+
+ <para>When you want to emphasise 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 your document, no equivalent of HTML's <sgmltag>b</sgmltag>
+ and <sgmltag>i</sgmltag>. If the information you are presenting is
+ important then consider presenting it in
+ <sgmltag>important</sgmltag> rather than
+ <sgmltag>emphasis</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>emphasis</sgmltag></title>
+
+ <para>Use:</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>
+ </sect3>
+
+ <sect3>
+ <title>Applications, commands, options, and cites</title>
+
+ <para>You will frequently want to refer to both applications and
+ commands when writing for the Handbook. 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.</para>
+
+ <para>In addition, you will occasionally need to list one or more of
+ the options that a command might take.</para>
+
+ <para>Finally, you will often want to list a command with it's manual
+ section number, in the &ldquo;command(number)&rdquo; format so
+ common in Unix manuals.</para>
+
+ <para>Mark up application names with
+ <sgmltag>application</sgmltag>.</para>
+
+ <para>When you want to list a command with it's 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="general-entities">general entities</link> have been
+ created to make this easier. Each entity takes the form
+ <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
+
+ <para>The file that contains these entities is in
+ <filename>doc/share/sgml/man-refs.ent</filename>, and can be
+ referred to using this FPI;</para>
+
+ <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
+
+ <para>Therefore, the introduction to your documentation will probably
+ look like this;</para>
+
+ <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
+
+&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
+%man;
+
+&hellip;
+
+]]&gt;</programlisting>
+
+ <para>Use <sgmltag>command</sgmltag> when you want to include a
+ command name &ldquo;in-line&rdquo; but present it as something the
+ user should type in.</para>
+
+ <para>Use <sgmltag>option</sgmltag> to mark up a command's
+ options.</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>Use:</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>, &amp;man.sendmail.8;, and &man.newaliases.8;
+ 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>, <citerefentry>
+ <refentrytitle>mailq</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, and <citerefentry>
+ <refentrytitle>newaliases</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry> 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>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Files, directories, extensions</title>
+
+ <para>Whenever you wish 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>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>The SGML source for the Handbook in English can be
+ found in <filename>/usr/doc/en/handbook/</filename>. The first
+ file is called <filename>handbook.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>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The SGML source for the Handbook in English can be found in
+ <filename>/usr/doc/en/handbook/</filename>. The first file is
+ called <filename>handbook.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>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Devices</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>When referring to devices you have two choices. You can either
+ refer to the device as it appears in <filename>/dev</filename>, or
+ you can use the name of the device as it appears in the kernel. For
+ this latter course, use <sgmltag>devicename</sgmltag>.</para>
+
+ <para>Sometimes you will not have a choice. Some devices, such as
+ networking cards, do not have entries in <filename>/dev</filename>,
+ or the entries are markedly different from those entries.</para>
+
+ <example>
+ <title><sgmltag>devicename</sgmltag></title>
+
+ <para>Use:</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, the networking devices, such as
+ <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.
+
+<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, 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>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Hosts, domains, IP addresses, and so forth</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>You can markup identification information for networked
+ computers (hosts) 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 role attribute, or
+ <literal>role="hostname"</literal></term>
+
+ <listitem>
+ <para>With no role 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>.
+ You can explicitly specify this 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 IP address, probably expressed as a dotted
+ quad.</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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="mac"</literal></term>
+
+ <listitem>
+ <para>The text is an ethernet MAC address, expressed as a series
+ of 2 digit hexadecimal numbers seperated by colons.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title><sgmltag>hostid</sgmltag> and roles</title>
+
+ <para>Use:</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 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
+ in existence. A typical MAC 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 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>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Usernames</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>When you need 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>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>To carry out most system administration functions you
+ will need to be <username>root</username>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>To carry out most system administration functions you will
+ need to be <username>root</username>.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Describing <filename>Makefile</filename>s</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</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>Use:</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>
+ </sect3>
+
+ <sect3>
+ <title>Literal text</title>
+
+ <para>You will often need to include &ldquo;literal&rdquo; text in the
+ Handbook. This is text that is excerpted from another file, or which
+ should be copied from the Handbook into another file
+ verbatim.</para>
+
+ <para>Some of the time, <sgmltag>programlisting</sgmltag> will be
+ sufficient to denote this text. <sgmltag>programlisting</sgmltag> is
+ not always appropriate, particularly when you want to include a
+ portion of a file &ldquo;in-line&rdquo; with the rest of the
+ paragraph.</para>
+
+ <para>On these occasions, use <sgmltag>literal</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>literal</sgmltag></title>
+
+ <para>Use:</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>
+ </sect3>
+
+ <sect3>
+ <title>Showing items that the user <emphasis>must</emphasis> fill
+ in</title>
+
+ <para>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
+ can not simply copy the examples that you provide, but must instead
+ include 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>Use:</para>
+
+ <programlisting>
+<![ CDATA [<informalexample>
+ <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
+</informalexample>]]></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>Use:</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>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Links</title>
+
+ <note>
+ <para>Links are also in-line elements.</para>
+ </note>
+
+ <sect3>
+ <title>Linking to other parts of the same document</title>
+
+ <para>Linking within the same document requires you to 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).</para>
+
+ <para>Each element within DocBook has an attribute called
+ <literal>id</literal>. You can place text in this attribute to
+ uniquely name the element it is attached to.</para>
+
+ <para>This value will be used when you specify the link
+ source.</para>
+
+ <para>Normally, you will only be linking to chapters or sections, so
+ you would add the <literal>id</literal> attribute to these
+ elements.</para>
+
+ <example>
+ <title><literal>id on chapters and sections</literal></title>
+
+ <programlisting>
+<![ CDATA [<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>]]></programlisting>
+ </example>
+
+ <para>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
+ <literal>id</literal> for the subsection is constructed by appending
+ text to the <literal>id</literal> of the chapter. This helps to
+ ensure that they are unique.</para>
+
+ <para>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 <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 won't show up in
+ the document.</para>]]></programlisting>
+ </example>
+
+ <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 <literal>id</literal> attribute, you can use either
+ <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para>
+
+ <para>Both of these elements have a <literal>linkend</literal>
+ attribute. The value of this attribute should be the value that you
+ have used in a <literal>id</literal> attribute (it does not matter
+ if that value has not yet occured in your document, this will work
+ for forward links as well as backward links).</para>
+
+ <para>If you use <sgmltag>xref</sgmltag> then you have no control over
+ the text of the link. It will be generated for you.</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;</para>
+
+ <programlisting>
+<![ CDATA [<para>More information can be found
+ in <xref linkend="chapter1">.</para>
+
+<para>More specific information can be found
+ in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
+
+ <para>The text of the link will be generated automatically, and will
+ look like (<emphasis>emphasised</emphasis> text indicates the text
+ that will be the link);</para>
+
+ <blockquote>
+ <para>More information can be found in <emphasis>Chapter
+ One</emphasis>.</para>
+
+ <para>More specific information can be found in <emphasis>the
+ section called Sub-sect 1</emphasis>.</para>
+ </blockquote>
+ </example>
+
+ <para>Notice how the text from the link is derived from the section
+ title or the chapter number.</para>
+
+ <note>
+ <para>This means that you <emphasis>can not</emphasis> use
+ <sgmltag>xref</sgmltag> to 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> can not generate the text for the
+ link.</para>
+ </note>
+
+ <para>If you want to control the text of the link then use
+ <sgmltag>link</sgmltag>. This element wraps content, and the content
+ will be used for the link.</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
+ <link linkend="chapter1">the first chapter</link>.</para>
+
+<para>More specific information can be found in
+ <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting>
+
+ <para>This will generate the following
+ (<emphasis>emphasised</emphasis> text indicates the text that will
+ be the link);</para>
+
+ <blockquote>
+ <para>More information can be found in <emphasis>the first
+ chapter</emphasis>.</para>
+
+ <para>More specific information can be found in
+ <emphasis>this</emphasis> section.</para>
+ </blockquote>
+ </example>
+
+ <note>
+ <para>That last one is a bad example. Never use words like
+ &ldquo;this&rdquo; or &ldquo;here&rdquo; as the source for the
+ link. The reader will need to hunt around the surrounding context
+ to see where the link is actually taking them.</para>
+ </note>
+
+ <note>
+ <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to
+ include a link to an <literal>id</literal> on an
+ <sgmltag>anchor</sgmltag> element, since the
+ <sgmltag>link</sgmltag> content defines the text that will be used
+ for the link.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Linking to documents on the WWW</title>
+
+ <para>Linking to external documents is much simpler, as long as you
+ know the URL of the document you want to link to. Use
+ <sgmltag>ulink</sgmltag>. The <literal>url</literal> 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>
+
+ <example>
+ <title><sgmltag>ulink</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>Of course, you could stop reading this document and
+ go to the <ulink url="http://www.freebsd.org/">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="http://www.freebsd.org/">FreeBSD home page</ulink>
+ instead.</para>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>* LinuxDoc</title>
+
+ <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the
+ <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
+ Project</ulink>, and subsequently adopted by the FreeBSD Documentation
+ Project.</para>
+
+ <para>The LinuxDoc DTD contains primarily appearance related markup rather
+ than content related markup (i.e., it describes what something looks
+ like rather than what it is).</para>
+
+ <para>Both the FreeBSD Documentation Project and the Linux Documentation
+ Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para>
+
+ <para>The LinuxDoc DTD is available from the ports collection in the
+ <filename>textproc/linuxdoc</filename> category.</para>
+ </sect1>
+</chapter>
+
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-declaration: "../chapter.decl"
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ sgml-parent-document: ("../book.sgml" "part" "chapter")
+ End:
+-->
+