doc/en/tutorials/docproj-primer/sgml-markup/chapter.sgml

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

     $Id: chapter.sgml,v 1.3 1999-07-14 19:06:23 nik Exp $
-->

<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.1-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>listitem</sgmltag> elements, and
	  each <sgmltag>listitem</sgmltag> contains one or more block
	  elements.  The <sgmltag>listitem</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.1-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:
-->