My primer for people new to the Doc. Proj. Incomplete, but should be

enough for most people, and gets it into the repository, making it
easier for others to add to as necessary.

This has not (yet) been turned on in the upper level Makefile or
listed on the web site yet, I want to get some more feedback
from readers first.  It should be "made visible" later this week.

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