path: root/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     $FreeBSD$
-->

<chapter id="docbook-markup">
  <title>DocBook Markup</title>

  <sect1 id="docbook-markup-introduction">
    <title>Introduction</title>

    <para>This chapter is an introduction to DocBook as it is used for
      &os; documentation.  DocBook is a large and complex markup
      system, but the subset described here covers the parts that are
      most widely used for &os; documentation.  While a moderate
      subset is covered, it is impossible to anticipate every
      situation.  Please post questions that this document does
      not answer to the &a.doc;.</para>

    <para>DocBook was originally developed by HaL Computer Systems and
      O'Reilly &amp; Associates to be a Document Type Definition
      (<acronym>DTD</acronym>) for writing technical documentation
      <footnote><para>A short history
	  can be found under <ulink
	    url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
	    http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>.
      Since 1998 it is maintained by the <ulink
	url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
	DocBook Technical Committee</ulink>.  As such, and unlike
      LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
      oriented towards markup that describes <emphasis>what</emphasis>
      something is, rather than describing <emphasis>how</emphasis> it
      should be presented.</para>

    <para>The DocBook <acronym>DTD</acronym> is available from the
      Ports Collection in the
      <filename role="package">textproc/docbook-xml-450</filename>
      port.  It is automatically installed as part of the
      <filename role="package">textproc/docproj</filename>
      port.</para>

    <note>
      <title>Formal Versus Informal</title>

      <para>Some elements may exist in two forms,
	<emphasis>formal</emphasis> and <emphasis>informal</emphasis>.
	Typically, the formal version of the element will consist of a
	title followed by the informal version of the element.  The
	informal version will not have a title.</para>
    </note>

    <note>
      <title>Inline Versus Block</title>

      <para>In the remainder of this document, when describing
	elements, <emphasis>inline</emphasis> means that the element
	can occur within a block element, and does not cause a line
	break.  A <emphasis>block</emphasis> element, by comparison,
	will cause a line break (and other processing) when it is
	encountered.</para>
    </note>
  </sect1>

  <sect1 id="docbook-markup-freebsd-extensions">
    <title>&os; Extensions</title>

    <para>The &os; Documentation Project has extended the
      DocBook <acronym>DTD</acronym> with additional elements and
      entities.  These additions serve to make some of the markup
      easier or more precise.</para>

    <para>Throughout the rest of this document, the term
      <quote>DocBook</quote> is used to mean the &os;-extended
      DocBook <acronym>DTD</acronym>.</para>

    <note>
      <para>Most of these extensions are not unique to &os;,
	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 contact
	&a.doceng;.</para>
    </note>

    <sect2 id="docbook-markup-freebsd-extensions-elements">
      <title>&os; Elements</title>

      <para>The additional &os; elements are not (currently) in the
	Ports Collection.  They are stored in the &os; Subversion
	tree, as <ulink
	  url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para>

      <para>&os;-specific elements used in the examples below are
	clearly marked.</para>
    </sect2>

    <sect2 id="docbook-markup-freebsd-extensions-entities">
      <title>&os; Entities</title>

      <para>This table shows some of the most useful entities
	available in the <acronym>FDP</acronym>.  For a complete list,
	see the <filename>*.ent</filename> files in
	<filename class="directory">doc/share/xml</filename>.</para>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	  <colspec colname="entity"/>
	  <colspec colname="expandsto"/>
	  <colspec colname="notes"/>

	  <tbody valign="top">
	    <row>
	      <entry namest="entity" nameend="notes">&os; Name Entities</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;os;</literal></entry>
	      <entry><literal>&os;</literal></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;os.stable;</literal></entry>
	      <entry><literal>&os.stable;</literal></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;os.current;</literal></entry>
	      <entry><literal>&os.current;</literal></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry namest="entity" nameend="notes">Manual Page Entities</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;man.ls.1;</literal></entry>
	      <entry>&man.ls.1;</entry>
	      <entry>Usage:  <literal>&amp;man.ls.1; is the manual page for <sgmltag class="starttag">command</sgmltag>ls<sgmltag class="endtag">command</sgmltag>.</literal></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;man.cp.1;</literal></entry>
	      <entry>&man.cp.1;</entry>
	      <entry>Usage:  <literal>The manual page for <sgmltag class="starttag">command</sgmltag>cp<sgmltag class="endtag">command</sgmltag> is &amp;man.cp.1;.</literal></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry>
	      <entry><emphasis>link to
		  <replaceable>command</replaceable> manual page in
		  section
		  <replaceable>sectionnumber</replaceable></emphasis></entry>
	      <entry>Entities are defined for all the <ulink
		  url="&url.base;/cgi/man.cgi">&os; manual
		  pages</ulink>.</entry>
	    </row>

	    <row>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry namest="entity" nameend="notes">&os; Mailing List Entities</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;a.doc;</literal></entry>
	      <entry><literal>&a.doc;</literal></entry>
	      <entry>Usage:  <literal>A link to the &amp;a.doc;.</literal></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;a.questions;</literal></entry>
	      <entry><literal>&a.questions;</literal></entry>
	      <entry>Usage:  <literal>A link to the &amp;a.questions;.</literal></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;a.<replaceable>listname</replaceable>;</literal></entry>
	      <entry><emphasis>link to
		  <replaceable>listname</replaceable></emphasis></entry>
	      <entry>Entities are defined for all the <ulink
		  url="&url.books.handbook;/eresources.html#eresources-mail">&os;
		  mailing lists</ulink>.</entry>
	    </row>

	    <row>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry namest="entity" nameend="notes">&os; Document Link Entities</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;url.books.handbook;</literal></entry>
	      <entry><literal>&url.books.handbook;</literal></entry>
	      <entry>Usage: <literal>A link to the <sgmltag
		  class="starttag">ulink
		  url="&amp;url.books.handbook;/advanced-networking.html"</sgmltag>Advanced
		  Networking<sgmltag class="endtag">ulink</sgmltag>
		  chapter of the Handbook.</literal></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;url.books.<replaceable>bookname</replaceable>;</literal></entry>
	      <entry><emphasis>relative path to
		  <replaceable>bookname</replaceable></emphasis></entry>
	      <entry>Entities are defined for all the <ulink
		  url="&url.doc.langbase;/books/">&os;
		  books</ulink>.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;url.articles.committers-guide;</literal></entry>
	      <entry><literal>&url.articles.committers-guide;</literal></entry>
	      <entry>Usage: <literal>A link to the <sgmltag
		  class="starttag">ulink
		  url="&amp;url.articles.committers-guide;"</sgmltag>Committer's
		Guide<sgmltag class="endtag">ulink</sgmltag>
		article.</literal></entry>
	    </row>

	    <row>
	      <entry><literal>&amp;url.articles.<replaceable>articlename</replaceable>;</literal></entry>
	      <entry><emphasis>relative path to
		  <replaceable>articlename</replaceable></emphasis></entry>
	      <entry>Entities are defined for all the <ulink
		  url="&url.doc.langbase;/articles/">&os;
		  articles</ulink>.</entry>
	    </row>

	    <row>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry namest="entity" nameend="notes">Other Operating System Name Entities</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;linux;</literal></entry>
	      <entry>&linux;</entry>
	      <entry>The &linux; operating system.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;unix;</literal></entry>
	      <entry>&unix;</entry>
	      <entry>The &unix; operating system.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;windows;</literal></entry>
	      <entry>&windows;</entry>
	      <entry>The &windows; operating system.</entry>
	    </row>

	    <row>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>

	    <row>
	      <entry namest="entity" nameend="notes">Miscellaneous Entities</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;prompt.root;</literal></entry>
	      <entry>&prompt.root;</entry>
	      <entry>The <username>root</username> user
		prompt.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;prompt.user;</literal></entry>
	      <entry>&prompt.user;</entry>
	      <entry>A prompt for an unprivileged user.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;postscript;</literal></entry>
	      <entry>&postscript;</entry>
	      <entry>The
		&postscript; programming language.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;tex;</literal></entry>
	      <entry>&tex;</entry>
	      <entry>The
		&tex; typesetting language.</entry>
	    </row>

	    <row>
	      <entry><literal>&amp;xorg;</literal></entry>
	      <entry>&xorg;</entry>
	      <entry>The &xorg; open source X
		Window System.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>
    </sect2>
  </sect1>

  <sect1 id="docbook-markup-fpi">
    <title>Formal Public Identifier (FPI)</title>

    <para>In compliance with the DocBook guidelines for writing
      <acronym>FPI</acronym>s for DocBook customizations, the
      <acronym>FPI</acronym> for the &os; extended DocBook
      <acronym>DTD</acronym> is:</para>

      <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
  </sect1>

  <sect1 id="docbook-markup-document-structure">
    <title>Document Structure</title>

    <para>DocBook allows structuring documentation in several ways.
      The &os; Documentation Project uses two primary types of DocBook
      document: the book and the article.</para>

    <para>Books are organized into <sgmltag>chapter</sgmltag>s.
      This is a mandatory requirement.  There may be
      <sgmltag>part</sgmltag>s between the book and the chapter to
      provide another layer of organization.  For example, the
      Handbook is arranged in this way.</para>

    <para>A chapter may (or may not) contain one or more sections.
      These are indicated with the <sgmltag>sect1</sgmltag> element.
      If a section contains another section then use the
      <sgmltag>sect2</sgmltag> element, and so on, up to
      <sgmltag>sect5</sgmltag>.</para>

    <para>Chapters and sections contain the remainder of the
      content.</para>

    <para>An article is simpler than a book, and does not use
      chapters.  Instead, the content of an article is organized into
      one or more sections, using the same <sgmltag>sect1</sgmltag>
      (and <sgmltag>sect2</sgmltag> and so on) elements that are used
      in books.</para>

    <para>The nature of the document being written should be used to
      determine whether it is best marked up as a book or an article.
      Articles are well suited to information that does not need to be
      broken down into several chapters, and that is, relatively
      speaking, quite short, at up to 20-25 pages of content.  Books
      are best suited to information that can be broken up into
      several chapters, possibly with appendices and similar content
      as well.</para>

    <para>The <ulink url="&url.base;/docs.html">&os; tutorials</ulink>
      are all marked up as articles, while this
      document, the
      <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
      and the <ulink url="&url.books.handbook;/index.html">FreeBSD
	Handbook</ulink> are all marked up as books, for
      example.</para>

    <sect2 id="docbook-markup-starting-a-book">
      <title>Starting a Book</title>

      <para>The content of a book is contained within the
	<sgmltag>book</sgmltag> element.  As well as containing
	structural markup, this element can contain elements that
	include additional information about the book.  This is either
	meta-information, used for reference purposes, or additional
	content used to produce a title page.</para>

      <para>This additional information is contained within
	<sgmltag>bookinfo</sgmltag>.</para>

      <example>
	<title>Boilerplate <sgmltag>book</sgmltag> with
	  <sgmltag>bookinfo</sgmltag></title>

	<!-- Cannot put this in a marked section because of the
	  replaceable elements -->

	<programlisting><sgmltag class="starttag">book</sgmltag>
  <sgmltag class="starttag">bookinfo</sgmltag>
    <sgmltag class="starttag">title</sgmltag><replaceable>Your Title Here</replaceable><sgmltag class="endtag">title</sgmltag>

    <sgmltag class="starttag">author</sgmltag>
      <sgmltag class="starttag">firstname</sgmltag><replaceable>Your first name</replaceable><sgmltag class="endtag">firstname</sgmltag>
      <sgmltag class="starttag">surname</sgmltag><replaceable>Your surname</replaceable><sgmltag class="endtag">surname</sgmltag>
      <sgmltag class="starttag">affiliation</sgmltag>
        <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag><replaceable>Your email address</replaceable><sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag>
      <sgmltag class="endtag">affiliation</sgmltag>
    <sgmltag class="endtag">author</sgmltag>

    <sgmltag class="starttag">copyright</sgmltag>
      <sgmltag class="starttag">year</sgmltag><replaceable>1998</replaceable><sgmltag class="endtag">year</sgmltag>
      <sgmltag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</sgmltag><replaceable>Your name</replaceable><sgmltag class="endtag">holder</sgmltag>
    <sgmltag class="endtag">copyright</sgmltag>

    <sgmltag class="starttag">releaseinfo</sgmltag>&dollar;&os;&dollar;<sgmltag class="endtag">releaseinfo</sgmltag>

    <sgmltag class="starttag">abstract</sgmltag>
      <sgmltag class="starttag">para</sgmltag><replaceable>Include an abstract of the book's contents here.</replaceable><sgmltag class="endtag">para</sgmltag>
    <sgmltag class="endtag">abstract</sgmltag>
  <sgmltag class="endtag">bookinfo</sgmltag>

  &hellip;

<sgmltag class="endtag">book</sgmltag></programlisting>
      </example>
    </sect2>

    <sect2 id="docbook-markup-starting-an-article">
      <title>Starting an Article</title>

      <para>The content of the article is contained within the
	<sgmltag>article</sgmltag> element.  As well as containing
	structural markup, this element can contain elements that
	include additional information about the article.  This is
	either meta-information, used for reference purposes, or
	additional content used to produce a title page.</para>

      <para>This additional information is contained within
	<sgmltag>articleinfo</sgmltag>.</para>

      <example>
	<title>Boilerplate <sgmltag>article</sgmltag> with
	  <sgmltag>articleinfo</sgmltag></title>

	<!-- Cannot put this in a marked section because of the
	  replaceable elements -->

	<programlisting><sgmltag class="starttag">article</sgmltag>
  <sgmltag class="starttag">articleinfo</sgmltag>
    <sgmltag class="starttag">title</sgmltag><replaceable>Your title here</replaceable><sgmltag class="endtag">title</sgmltag>

    <sgmltag class="starttag">author</sgmltag>
      <sgmltag class="starttag">firstname</sgmltag><replaceable>Your first name</replaceable><sgmltag class="endtag">firstname</sgmltag>
      <sgmltag class="starttag">surname</sgmltag><replaceable>Your surname</replaceable><sgmltag class="endtag">surname</sgmltag>
      <sgmltag class="starttag">affiliation</sgmltag>
        <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag><replaceable>Your email address</replaceable><sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag>
      <sgmltag class="endtag">affiliation</sgmltag>
    <sgmltag class="endtag">author</sgmltag>

    <sgmltag class="starttag">copyright</sgmltag>
      <sgmltag class="starttag">year</sgmltag><replaceable>1998</replaceable><sgmltag class="endtag">year</sgmltag>
      <sgmltag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</sgmltag><replaceable>Your name</replaceable><sgmltag class="endtag">holder</sgmltag>
    <sgmltag class="endtag">copyright</sgmltag>

    <sgmltag class="starttag">releaseinfo</sgmltag>&dollar;&os;&dollar;<sgmltag class="endtag">releaseinfo</sgmltag>

    <sgmltag class="starttag">abstract</sgmltag>
      <sgmltag class="starttag">para</sgmltag><replaceable>Include an abstract of the article's contents here.</replaceable><sgmltag class="endtag">para</sgmltag>
    <sgmltag class="endtag">abstract</sgmltag>
  <sgmltag class="endtag">articleinfo</sgmltag>

  &hellip;

<sgmltag class="endtag">article</sgmltag></programlisting>
      </example>
    </sect2>

    <sect2 id="docbook-markup-indicating-chapters">
      <title>Indicating Chapters</title>

      <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters.
	Each chapter has a mandatory <sgmltag>title</sgmltag>.
	Articles do not contain chapters, they are reserved for
	books.</para>

      <example>
	<title>A Simple Chapter</title>

	<programlisting><sgmltag class="starttag">chapter</sgmltag>
  <sgmltag class="starttag">title</sgmltag>The Chapter's Title<sgmltag class="endtag">title</sgmltag>

  ...
<sgmltag class="endtag">chapter</sgmltag></programlisting>
	</example>

	<para>A chapter cannot be empty; it must contain elements in
	  addition to <sgmltag>title</sgmltag>.  If you need to
	  include an empty chapter then just use an empty
	  paragraph.</para>

	<example>
	  <title>Empty Chapters</title>

	  <programlisting><sgmltag class="starttag">chapter</sgmltag>
  <sgmltag class="starttag">title</sgmltag>This is An Empty Chapter<sgmltag class="endtag">title</sgmltag>

  <sgmltag class="starttag">para</sgmltag><sgmltag class="endtag">para</sgmltag>
<sgmltag class="endtag">chapter</sgmltag></programlisting>
      </example>
    </sect2>

    <sect2 id="docbook-markup-sections-below-chapters">
      <title>Sections Below Chapters</title>

      <para>In books, chapters may (but do not need to) be broken up
	into sections, subsections, and so on.  In articles, sections
	are the main structural element, and each article must contain
	at least one section.  Use the
	<sgmltag>sect<replaceable>n</replaceable></sgmltag> element.
	The <replaceable>n</replaceable> indicates the section number,
	which identifies the section level.</para>

      <para>The first
	<sgmltag>sect<replaceable>n</replaceable></sgmltag> is
	<sgmltag>sect1</sgmltag>.  You can have one or more of these
	in a chapter.  They can contain one or more
	<sgmltag>sect2</sgmltag> elements, and so on, down to
	<sgmltag>sect5</sgmltag>.</para>

      <example>
	<title>Sections in Chapters</title>

	<programlisting><sgmltag class="starttag">chapter</sgmltag>
  <sgmltag class="starttag">title</sgmltag>A Sample Chapter<sgmltag class="endtag">title</sgmltag>

  <sgmltag class="starttag">para</sgmltag>Some text in the chapter.<sgmltag class="endtag">para</sgmltag>

  <sgmltag class="starttag">sect1</sgmltag>
    <sgmltag class="starttag">title</sgmltag>First Section<sgmltag class="endtag">title</sgmltag>

    &hellip;
  <sgmltag class="endtag">sect1</sgmltag>

  <sgmltag class="starttag">sect1</sgmltag>
    <sgmltag class="starttag">title</sgmltag>Second Section<sgmltag class="endtag">title</sgmltag>

    <sgmltag class="starttag">sect2</sgmltag>
      <sgmltag class="starttag">title</sgmltag>First Sub-Section<sgmltag class="endtag">title</sgmltag>

      <sgmltag class="starttag">sect3</sgmltag>
	<sgmltag class="starttag">title</sgmltag>First Sub-Sub-Section<sgmltag class="endtag">title</sgmltag>

	&hellip;
      <sgmltag class="endtag">sect3</sgmltag>
    <sgmltag class="endtag">sect2</sgmltag>

    <sgmltag class="starttag">sect2</sgmltag>
      <sgmltag class="starttag">title</sgmltag>Second Sub-Section (1.2.2)<sgmltag class="endtag">title</sgmltag>

      &hellip;
    <sgmltag class="endtag">sect2</sgmltag>
  <sgmltag class="endtag">sect1</sgmltag>
<sgmltag class="endtag">chapter</sgmltag></programlisting>
      </example>

      <note>
	<para>Section numbers are automatically generated and
	  prepended to titles when the document is rendered to an
	  output format.  The generated section numbers and titles
	  from the example above will be:</para>

	<itemizedlist>
	  <listitem>
	    <para>1.1. First Section</para>
	  </listitem>

	  <listitem>
	    <para>1.2. Second Section</para>
	  </listitem>

	  <listitem>
	    <para>1.2.1. First Sub-Section</para>
	  </listitem>

	  <listitem>
	    <para>1.2.1.1. First Sub-Sub-Section</para>
	  </listitem>

	  <listitem>
	    <para>1.2.2. Second Sub-Section</para>
	  </listitem>
	</itemizedlist>
      </note>
    </sect2>

    <sect2 id="docbook-markup-subdividing-part">
      <title>Subdividing Using <sgmltag>part</sgmltag>
	Elements</title>

      <para><sgmltag>part</sgmltag>s introduce another level of
	organization between <sgmltag>book</sgmltag> and
	<sgmltag>chapter</sgmltag> with one or more
	<sgmltag>part</sgmltag>s.  This cannot be done in an
	<sgmltag>article</sgmltag>.</para>

      <programlisting><sgmltag class="starttag">part</sgmltag>
  <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag>

  <sgmltag class="starttag">chapter</sgmltag>
    <sgmltag class="starttag">title</sgmltag>Overview<sgmltag class="endtag">title</sgmltag>

    ...
  <sgmltag class="endtag">chapter</sgmltag>

  <sgmltag class="starttag">chapter</sgmltag>
    <sgmltag class="starttag">title</sgmltag>What is FreeBSD?<sgmltag class="endtag">title</sgmltag>

    ...
  <sgmltag class="endtag">chapter</sgmltag>

  <sgmltag class="starttag">chapter</sgmltag>
    <sgmltag class="starttag">title</sgmltag>History<sgmltag class="endtag">title</sgmltag>

    ...
  <sgmltag class="endtag">chapter</sgmltag>
<sgmltag class="endtag">part</sgmltag></programlisting>
    </sect2>
  </sect1>

  <sect1 id="docbook-markup-block-elements">
    <title>Block Elements</title>

    <sect2 id="docbook-markup-paragraphs">
      <title>Paragraphs</title>

      <para>DocBook supports three types of paragraphs:
	<sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
	<sgmltag>simpara</sgmltag>.</para>

      <para>Almost all paragraphs in &os; documentation use
	<sgmltag>para</sgmltag>.  <sgmltag>formalpara</sgmltag>
	includes a <sgmltag>title</sgmltag> element, and
	<sgmltag>simpara</sgmltag> disallows some elements from
	within <sgmltag>para</sgmltag>.  Stick with
	<sgmltag>para</sgmltag>.</para>

      <example>
	<title><sgmltag>para</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>This is a paragraph.  It can contain just about any
  other element.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

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

    <sect2 id="docbook-markup-block-quotations">
      <title>Block Quotations</title>

      <para>A block quotation is an extended quotation from another
	document that should not appear within the current paragraph.
	These are rarely needed.</para>

      <para>Blockquotes can optionally contain a title and an
	attribution (or they can be left untitled and
	unattributed).</para>

      <example>
	<title><sgmltag>blockquote</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>A small excerpt from the US Constitution:<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">blockquote</sgmltag>
  <sgmltag class="starttag">title</sgmltag>Preamble to the Constitution of the United States<sgmltag class="endtag">title</sgmltag>

  <sgmltag class="starttag">attribution</sgmltag>Copied from a web site somewhere<sgmltag class="endtag">attribution</sgmltag>

  <sgmltag class="starttag">para</sgmltag>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.<sgmltag class="endtag">para</sgmltag>
<sgmltag class="endtag">blockquote</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>A small excerpt from the US Constitution:</para>

	<blockquote>
	  <title>Preamble to the Constitution of the United
	    States</title>

	  <attribution>Copied from a web site
	    somewhere</attribution>

	  <para>We the People of the United States, in Order to form
	    a more perfect Union, establish Justice, insure domestic
	    Tranquility, provide for the common defence, promote the
	    general Welfare, and secure the Blessings of Liberty to
	    ourselves and our Posterity, do ordain and establish
	    this Constitution for the United States of
	    America.</para>
	</blockquote>
      </example>
    </sect2>

    <sect2 id="docbook-markup-tips-notes">
      <title>Tips, Notes, Warnings, Cautions, Important Information
	and Sidebars</title>

      <para>Extra information may need to be separated from
	the main body of the text.  Typically this is
	<quote>meta</quote> information of which the user should be
	aware.</para>

      <para>Depending on the nature of the information, one of
	<sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
	<sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
	<sgmltag>important</sgmltag> should be used.  Alternatively,
	if the information is related to the main text but is not
	one of the above, use <sgmltag>sidebar</sgmltag>.</para>

      <para>The circumstances in which to choose one of these
	elements over another is loosely defined by the DocBook
	documentation, which suggests:</para>

      <itemizedlist>
	<listitem>
	  <para>A Note is for information that should be heeded by
	    all readers.</para>
	</listitem>

	<listitem>
	  <para>An Important element is a variation on Note.</para>
	</listitem>

	<listitem>
	  <para>A Caution is for information regarding possible data
	    loss or software damage.</para>
	</listitem>

	<listitem>
	  <para>A Warning is for information regarding possible
	    hardware damage or injury to life or limb.</para>
	</listitem>
      </itemizedlist>

      <example>
	<title><sgmltag>warning</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">warning</sgmltag>
  <sgmltag class="starttag">para</sgmltag>Installing FreeBSD may make you want to delete Windows from your
    hard disk.<sgmltag class="endtag">para</sgmltag>
<sgmltag class="endtag">warning</sgmltag></programlisting>
      </example>

      <para>Appearance:</para>
      <!-- Need to do this outside of the example -->
      <warning>
	<para>Installing FreeBSD may make you want to delete Windows
	  from your hard disk.</para>
      </warning>
    </sect2>

    <sect2 id="docbook-markup-lists-and-procedures">
      <title>Lists and Procedures</title>

      <para>Information often needs to be presented as lists, or as a
	number of steps that must be carried out in order to
	accomplish a particular goal.</para>

      <para>To do this, use <sgmltag>itemizedlist</sgmltag>,
	<sgmltag>orderedlist</sgmltag>, or
	<sgmltag>procedure</sgmltag><footnote><para>There are other
	    types of list element in DocBook, but we are not
	    concerned with those at the
	    moment.</para></footnote></para>

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

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

      <example>
	<title><sgmltag>itemizedlist</sgmltag>,
	  <sgmltag>orderedlist</sgmltag>, and
	  <sgmltag>procedure</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">itemizedlist</sgmltag>
  <sgmltag class="starttag">listitem</sgmltag>
    <sgmltag class="starttag">para</sgmltag>This is the first itemized item.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">listitem</sgmltag>

  <sgmltag class="starttag">listitem</sgmltag>
    <sgmltag class="starttag">para</sgmltag>This is the second itemized item.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">listitem</sgmltag>
<sgmltag class="endtag">itemizedlist</sgmltag>

<sgmltag class="starttag">orderedlist</sgmltag>
  <sgmltag class="starttag">listitem</sgmltag>
    <sgmltag class="starttag">para</sgmltag>This is the first ordered item.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">listitem</sgmltag>

  <sgmltag class="starttag">listitem</sgmltag>
    <sgmltag class="starttag">para</sgmltag>This is the second ordered item.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">listitem</sgmltag>
<sgmltag class="endtag">orderedlist</sgmltag>

<sgmltag class="starttag">procedure</sgmltag>
  <sgmltag class="starttag">step</sgmltag>
    <sgmltag class="starttag">para</sgmltag>Do this.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">step</sgmltag>

  <sgmltag class="starttag">step</sgmltag>
    <sgmltag class="starttag">para</sgmltag>Then do this.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">step</sgmltag>

  <sgmltag class="starttag">step</sgmltag>
    <sgmltag class="starttag">para</sgmltag>And now do this.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">step</sgmltag>
<sgmltag class="endtag">procedure</sgmltag></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>

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

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

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

    <sect2 id="docbook-markup-showing-file-samples">
      <title>Showing File Samples</title>

      <para>Fragments of a file (or perhaps a complete file) are shown
	by wrapping them in the <sgmltag>programlisting</sgmltag>
	element.</para>

      <para>White space and line breaks within
	<sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
	significant.  In particular, this means that the opening tag
	should appear on the same line as the first line of the
	output, and the closing tag should appear on the same line
	as the last line of the output, otherwise spurious blank
	lines may be included.</para>

      <example>
	<title><sgmltag>programlisting</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>When finished, the program will look like
  this:<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">programlisting</sgmltag>#include &amp;lt;stdio.h&amp;gt;

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

	<para>Notice how the angle brackets in the
	  <literal>#include</literal> line need to be referenced by
	  their entities instead of being included literally.</para>

	<para>Appearance:</para>

	<para>When finished, the program will look like this:</para>

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

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

    <sect2 id="docbook-markup-callouts">
      <title>Callouts</title>

      <para>A callout is a visual marker for referring to a
	piece of text or specific position within an
	example.</para>

      <para>Callouts are marked with the <sgmltag>co</sgmltag>
	element.  Each element must have a unique
	<literal>id</literal> assigned to it.  After the example,
	include a <sgmltag>calloutlist</sgmltag> that describes each
	callout.</para>

      <example>
	<title><sgmltag>co</sgmltag> and
	  <sgmltag>calloutlist</sgmltag></title>

	<programlisting><sgmltag class="starttag">para</sgmltag>When finished, the program will look like
  this:<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">programlisting</sgmltag>#include &amp;lt;stdio.h&amp;gt; <sgmltag class="emptytag">co id="co-ex-include"</sgmltag>

int <sgmltag class="emptytag">co id="co-ex-return"</sgmltag>
main(void)
{
    printf("hello, world\n"); <sgmltag class="emptytag">co id="co-ex-printf"</sgmltag>
}<sgmltag class="endtag">programlisting</sgmltag>

<sgmltag class="starttag">calloutlist</sgmltag>
  <sgmltag class="starttag">callout arearefs="co-ex-include"</sgmltag>
    <sgmltag class="starttag">para</sgmltag>Includes the standard IO header file.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">callout</sgmltag>

  <sgmltag class="starttag">callout arearefs="co-ex-return"</sgmltag>
    <sgmltag class="starttag">para</sgmltag>Specifies that <sgmltag class="starttag">function</sgmltag>main()<sgmltag class="endtag">function</sgmltag> returns an
      int.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">callout</sgmltag>

  <sgmltag class="starttag">callout arearefs="co-ex-printf"</sgmltag>
    <sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">function</sgmltag>printf()<sgmltag class="endtag">function</sgmltag> call that writes
      <sgmltag class="starttag">literal</sgmltag>hello, world<sgmltag class="endtag">literal</sgmltag> to standard output.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">callout</sgmltag>
<sgmltag class="endtag">calloutlist</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>When finished, the program will look like this:</para>

	<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>

int <co id="co-ex-return"/>
main(void)
{
    printf("hello, world\n"); <co id="co-ex-printf"/>
}</programlisting>

	<calloutlist>
	  <callout arearefs="co-ex-include">
	    <para>Includes the standard IO header file.</para>
	  </callout>

	  <callout arearefs="co-ex-return">
	    <para>Specifies that <function>main()</function> returns
	      an int.</para>
	  </callout>

	  <callout arearefs="co-ex-printf">
	    <para>The <function>printf()</function> call that writes
	      <literal>hello, world</literal> to standard
	      output.</para>
	  </callout>
	</calloutlist>
      </example>
    </sect2>

    <sect2 id="docbook-markup-tables">
      <title>Tables</title>

      <para>Unlike <acronym>HTML</acronym>, DocBook does not need
	tables for layout purposes, as the stylesheet handles those
	issues.  Instead, just use tables for marking up tabular
	data.</para>

      <para>In general terms (and see the DocBook documentation for
	more detail) a table (which can be either formal or informal)
	consists of a <sgmltag>table</sgmltag> element.  This contains
	at least one <sgmltag>tgroup</sgmltag> element, which
	specifies (as an attribute) the number of columns in this
	table group.  Within the tablegroup there is one
	<sgmltag>thead</sgmltag> element, which contains elements for
	the table headings (column headings), and one
	<sgmltag>tbody</sgmltag> which contains the body of the
	table.</para>

      <para>Both <sgmltag>tgroup</sgmltag> and
	<sgmltag>thead</sgmltag> contain <sgmltag>row</sgmltag>
	elements, which in turn contain <sgmltag>entry</sgmltag>
	elements.  Each <sgmltag>entry</sgmltag> element specifies
	one cell in the table.</para>

      <example>
	<title><sgmltag>informaltable</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">informaltable pgwide="1"</sgmltag>
  <sgmltag class="starttag">tgroup cols="2"</sgmltag>
    <sgmltag class="starttag">thead</sgmltag>
      <sgmltag class="starttag">row</sgmltag>
        <sgmltag class="starttag">entry</sgmltag>This is Column Head 1<sgmltag class="endtag">entry</sgmltag>
        <sgmltag class="starttag">entry</sgmltag>This is Column Head 2<sgmltag class="endtag">entry</sgmltag>
      <sgmltag class="endtag">row</sgmltag>
    <sgmltag class="endtag">thead</sgmltag>

    <sgmltag class="starttag">tbody</sgmltag>
      <sgmltag class="starttag">row</sgmltag>
	<sgmltag class="starttag">entry</sgmltag>Row 1, column 1<sgmltag class="endtag">entry</sgmltag>
	<sgmltag class="starttag">entry</sgmltag>Row 1, column 2<sgmltag class="endtag">entry</sgmltag>
      <sgmltag class="endtag">row</sgmltag>

      <sgmltag class="starttag">row</sgmltag>
	<sgmltag class="starttag">entry</sgmltag>Row 2, column 1<sgmltag class="endtag">entry</sgmltag>
	<sgmltag class="starttag">entry</sgmltag>Row 2, column 2<sgmltag class="endtag">entry</sgmltag>
      <sgmltag class="endtag">row</sgmltag>
    <sgmltag class="endtag">tbody</sgmltag>
  <sgmltag class="endtag">tgroup</sgmltag>
<sgmltag class="endtag">informaltable</sgmltag></programlisting>

	<para>Appearance:</para>

	<informaltable pgwide="1">
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>This is Column Head 1</entry>
		<entry>This is Column Head 2</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry>Row 1, column 1</entry>
		<entry>Row 1, column 2</entry>
	      </row>

	      <row>
		<entry>Row 2, column 1</entry>
		<entry>Row 2, column 2</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </example>

      <para>Always use the <literal>pgwide</literal> attribute with
	a value of <literal>1</literal> with the
	<sgmltag>informaltable</sgmltag> element.  A bug in Internet
	Explorer can cause the table to render incorrectly if this
	is omitted.</para>

      <para>Table borders can be suppressed by setting the
	<literal>frame</literal> attribute to <literal>none</literal>
	in the <sgmltag>informaltable</sgmltag> element.  For example,
	<literal><sgmltag class="starttag">informaltable
	    frame="none"</sgmltag></literal>.</para>

      <example>
	<title>Tables Where <literal>frame="none"</literal></title>

	<para>Appearance:</para>

	<informaltable frame="none" pgwide="1">
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>This is Column Head 1</entry>
		<entry>This is Column Head 2</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry>Row 1, column 1</entry>
		<entry>Row 1, column 2</entry>
	      </row>

	      <row>
		<entry>Row 2, column 1</entry>
		<entry>Row 2, column 2</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </example>
    </sect2>

    <sect2 id="docbook-markup-examples">
      <title>Examples for the User to Follow</title>

      <para>Examples for the user to follow are often necessary.
	Typically, these will consist of dialogs with the computer;
	the user types in a command, the user gets a response back,
	the user types another command, and so on.</para>

      <para>A number of distinct elements and entities come into
	play here.</para>

      <variablelist>
	<varlistentry>
	  <term><sgmltag>screen</sgmltag></term>

	  <listitem>
	    <para>Everything the user sees in this example will be
	      on the computer screen, so the next element is
	      <sgmltag>screen</sgmltag>.</para>

	    <para>Within <sgmltag>screen</sgmltag>, white space is
	      significant.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><sgmltag>prompt</sgmltag>,
	    <literal>&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
	      operating system, command shell, or application).  These
	      should be marked up using
	      <sgmltag>prompt</sgmltag>.</para>

	    <para>As a special case, the two shell prompts for the
	      normal user and the root user have been provided as
	      entities.  To indicate the user is at a shell prompt,
	      use one of <literal>&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 &os;
		extensions to DocBook, and are not part of the
		original <acronym>DTD</acronym>.</para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><sgmltag>userinput</sgmltag></term>

	  <listitem>
	    <para>When displaying text that the user should type in,
	      wrap it in <sgmltag>userinput</sgmltag> tags.  It will
	      be displayed differently than system output text.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <example>
	<title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>,
	  and <sgmltag>userinput</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">screen</sgmltag>&amp;prompt.user; <sgmltag class="starttag">userinput</sgmltag>ls -1<sgmltag class="endtag">userinput</sgmltag>
foo1
foo2
foo3
&amp;prompt.user; <sgmltag class="starttag">userinput</sgmltag>ls -1 | grep foo2<sgmltag class="endtag">userinput</sgmltag>
foo2
&amp;prompt.user; <sgmltag class="starttag">userinput</sgmltag>su<sgmltag class="endtag">userinput</sgmltag>
<sgmltag class="starttag">prompt</sgmltag>Password: <sgmltag class="endtag">prompt</sgmltag>
&amp;prompt.root; <sgmltag class="starttag">userinput</sgmltag>cat foo2<sgmltag class="endtag">userinput</sgmltag>
This is the file called 'foo2'<sgmltag class="endtag">screen</sgmltag></programlisting>

	<para>Appearance:</para>

	<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>
      </example>

      <note>
	<para>Even though we are displaying the contents of the file
	  <filename>foo2</filename>, it is <emphasis>not</emphasis>
	  marked up as <sgmltag>programlisting</sgmltag>.  Reserve
	  <sgmltag>programlisting</sgmltag> for showing fragments of
	  files outside the context of user actions.</para>
      </note>
    </sect2>
  </sect1>

  <sect1 id="docbook-markup-inline-elements">
    <title>In-line Elements</title>

    <sect2 id="docbook-markup-inline-emphasizing">
      <title>Emphasizing Information</title>

      <para>To emphasize a particular word or phrase, use
	<sgmltag>emphasis</sgmltag>.  This may be presented as
	italic, or bold, or might be spoken differently with a
	text-to-speech system.</para>

      <para>There is no way to change the presentation of the
	emphasis within the document, no equivalent of
	<acronym>HTML</acronym>'s <sgmltag>b</sgmltag> and
	<sgmltag>i</sgmltag>.  If the information being presented is
	important, then consider presenting it in
	<sgmltag>important</sgmltag> rather than
	<sgmltag>emphasis</sgmltag>.</para>

      <example>
	<title><sgmltag>emphasis</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>FreeBSD is without doubt <sgmltag class="starttag">emphasis</sgmltag>the<sgmltag class="endtag">emphasis</sgmltag>
  premiere &amp;unix;-like operating system for the Intel
  architecture.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>FreeBSD is without doubt <emphasis>the</emphasis>
	  premiere &unix;-like operating system for the Intel
	  architecture.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-acronyms">
      <title>Acronyms</title>

      <para>Many computer terms are <emphasis>acronyms</emphasis>,
	words formed from the first letter of each word in a
	phrase.  Acronyms are marked up into
	<sgmltag>acronym</sgmltag> elements.  It is helpful to the
	reader when an acronym is defined on the first use, as shown
	in the example below.</para>

      <example>
	<title>Acronyms</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>Request For Comments (<sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag>) 1149
  defined the use of avian carriers for transmission of
  Internet Protocol (<sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag>) data.  The
  quantity of <sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag> data currently
  transmitted in that manner is unknown.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>Request For Comments (<acronym>RFC</acronym>) 1149
	  defined the use of avian carriers for transmission of
	  Internet Protocol (<acronym>IP</acronym>) data.  The
	  quantity of <acronym>IP</acronym> data currently
	  transmitted in that manner is unknown.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-quotations">
      <title>Quotations</title>

      <para>To quote text from another document or source, or to
	denote a phrase that is used figuratively, use
	<sgmltag>quote</sgmltag>.  Most of the markup tags available
	for normal text are also available from within a
	<sgmltag>quote</sgmltag>.</para>

      <example>
	<title>Quotations</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>However, make sure that the search does not go beyond the
  <sgmltag class="starttag">quote</sgmltag>boundary between local and public administration<sgmltag class="endtag">quote</sgmltag>,
  as <sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag> 1535 calls it.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

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

    <sect2 id="docbook-markup-keys">
      <title>Keys, Mouse Buttons, and Combinations</title>

      <para>To refer to a specific key on the keyboard, use
	<sgmltag>keycap</sgmltag>.  To refer to a mouse button, use
	<sgmltag>mousebutton</sgmltag>.  And to refer to
	combinations of key presses or mouse clicks, wrap them all
	in <sgmltag>keycombo</sgmltag>.</para>

      <para><sgmltag>keycombo</sgmltag> has an attribute called
	<literal>action</literal>, which may be one of
	<literal>click</literal>, <literal>double-click</literal>,
	<literal>other</literal>, <literal>press</literal>,
	<literal>seq</literal>, or <literal>simul</literal>.  The
	last two values denote whether the keys or buttons should be
	pressed in sequence, or simultaneously.</para>

      <para>The stylesheets automatically add any connecting
	symbols, such as <literal>+</literal>, between the key
	names, when wrapped in <sgmltag>keycombo</sgmltag>.</para>

      <example>
	<title>Keys, Mouse Buttons, and Combinations</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>To switch to the second virtual terminal, press
  <sgmltag class="starttag">keycombo action="simul"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Alt<sgmltag class="endtag">keycap</sgmltag>
    <sgmltag class="starttag">keycap</sgmltag>F1<sgmltag class="endtag">keycap</sgmltag><sgmltag class="endtag">keycombo</sgmltag>.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>To exit <sgmltag class="starttag">command</sgmltag>vi<sgmltag class="endtag">command</sgmltag> without saving changes, type
  <sgmltag class="starttag">keycombo action="seq"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Esc<sgmltag class="endtag">keycap</sgmltag><sgmltag class="starttag">keycap</sgmltag>:<sgmltag class="endtag">keycap</sgmltag>
    <sgmltag class="starttag">keycap</sgmltag>q<sgmltag class="endtag">keycap</sgmltag><sgmltag class="starttag">keycap</sgmltag>!<sgmltag class="endtag">keycap</sgmltag><sgmltag class="endtag">keycombo</sgmltag>.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>My window manager is configured so that
  <sgmltag class="starttag">keycombo action="simul"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Alt<sgmltag class="endtag">keycap</sgmltag>
    <sgmltag class="starttag">mousebutton</sgmltag>right<sgmltag class="endtag">mousebutton</sgmltag>
  <sgmltag class="endtag">keycombo</sgmltag> mouse button is used to move windows.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>To switch to the second virtual terminal, press
	  <keycombo action="simul"><keycap>Alt</keycap>
	    <keycap>F1</keycap></keycombo>.</para>

	<para>To exit <command>vi</command> without saving changes,
	  type <keycombo action="seq">
	    <keycap>Esc</keycap>
	    <keycap>:</keycap>
	    <keycap>q</keycap>
	    <keycap>!</keycap></keycombo>.</para>

	<para>My window manager is configured so that
	  <keycombo action="simul">
	    <keycap>Alt</keycap>
	    <mousebutton>right</mousebutton></keycombo> mouse button
	  is used to move windows.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-applications">
      <title>Applications, Commands, Options, and Cites</title>

      <para>Both applications and commands are frequently referred to
	when writing documentation.  The distinction between them is
	that an application is the name of a program or suite of
	programs that fulfill a particular task.  A command is the
	filename of a program that the user can type and run at a
	command line.</para>

      <para>It is often necessary to show some of the options that a
	command might take.</para>

      <para>Finally, it is often useful to list a command with its
	manual section number, in the <quote>command(number)</quote>
	format so common in Unix manuals.</para>

      <para>Mark up application names with
	<sgmltag>application</sgmltag>.</para>

      <para>To list a command with its manual section
	number (which should be most of the time) the DocBook
	element is <sgmltag>citerefentry</sgmltag>.  This will
	contain a further two elements,
	<sgmltag>refentrytitle</sgmltag> and
	<sgmltag>manvolnum</sgmltag>.  The content of
	<sgmltag>refentrytitle</sgmltag> is the name of the command,
	and the content of <sgmltag>manvolnum</sgmltag> is the
	manual page section.</para>

      <para>This can be cumbersome to write, and so a series of
	<link linkend="xml-primer-general-entities">general
	  entities</link> have been created to make this easier.
	Each entity takes the form
	<literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>

      <para>The file that contains these entities is in
	<filename>doc/share/xml/man-refs.ent</filename>, and can be
	referred to using this <acronym>FPI</acronym>:</para>

      <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>

      <para>Therefore, the introduction to &os; documentation will
	usually include this:</para>

      <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.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 to include a command
	name <quote>in-line</quote> but present it as something the
	user should type in.</para>

      <para>Use <sgmltag>option</sgmltag> to mark up the options
	which will be passed to a command.</para>

      <para>When referring to the same command multiple times in
	close proximity, it is preferred to use the
	<literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
	notation to markup the first reference and use
	<sgmltag>command</sgmltag> to markup subsequent references.
	This makes the generated output, especially
	<acronym>HTML</acronym>, appear visually better.</para>

      <example>
	<title>Applications, Commands, and Options</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">application</sgmltag>Sendmail<sgmltag class="endtag">application</sgmltag> is the most
  widely used Unix mail application.<sgmltag class="starttag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">application</sgmltag>Sendmail<sgmltag class="endtag">application</sgmltag> includes the
  <sgmltag class="starttag">citerefentry</sgmltag>
    <sgmltag class="starttag">refentrytitle</sgmltag>sendmail<sgmltag class="endtag">refentrytitle</sgmltag>
    <sgmltag class="starttag">manvolnum</sgmltag>8<sgmltag class="endtag">manvolnum</sgmltag>
  <sgmltag class="endtag">citerefentry</sgmltag>, &amp;man.mailq.1;, and &amp;man.newaliases.1;
  programs.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>One of the command line parameters to <sgmltag class="starttag">citerefentry</sgmltag>
    <sgmltag class="starttag">refentrytitle</sgmltag>sendmail<sgmltag class="endtag">refentrytitle</sgmltag>
    <sgmltag class="starttag">manvolnum</sgmltag>8<sgmltag class="endtag">manvolnum</sgmltag>
  <sgmltag class="endtag">citerefentry</sgmltag>, <sgmltag class="starttag">option</sgmltag>-bp<sgmltag class="endtag">option</sgmltag>, will display the current
  status of messages in the mail queue.  Check this on the command
  line by running <sgmltag class="starttag">command</sgmltag>sendmail -bp<sgmltag class="endtag">command</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para><application>Sendmail</application> is the most widely
	  used Unix mail application.</para>

	<para><application>Sendmail</application> includes the
	  <citerefentry>
	    <refentrytitle>sendmail</refentrytitle>
	    <manvolnum>8</manvolnum>
	  </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
	  programs.</para>

	<para>One of the command line parameters to
	  <citerefentry>
	    <refentrytitle>sendmail</refentrytitle>
	    <manvolnum>8</manvolnum>
	  </citerefentry>, <option>-bp</option>, will display the
	  current status of messages in the mail queue.  Check this
	  on the command line by running
	  <command>sendmail -bp</command>.</para>
      </example>

      <note>
	<para>Notice how the
	  <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
	  notation is easier to follow.</para>
      </note>
    </sect2>

    <sect2 id="docbook-markup-files">
      <title>Files, Directories, Extensions</title>

      <para>To refer to the name of a file, a directory, or a file
	extension, use <sgmltag>filename</sgmltag>.</para>

      <example>
	<title><sgmltag>filename</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>The XML source for the Handbook in English is
  found in <sgmltag class="starttag">filename class="directory"</sgmltag>/usr/doc/en_US.ISO8859-1/books/handbook/<sgmltag class="endtag">filename</sgmltag>.  The first
  file is called <sgmltag class="starttag">filename</sgmltag>book.xml<sgmltag class="endtag">filename</sgmltag> in that
  directory.  There is also a <sgmltag class="starttag">filename</sgmltag>Makefile<sgmltag class="endtag">filename</sgmltag>
  and a number of files with a <sgmltag class="starttag">filename</sgmltag>.ent<sgmltag class="endtag">filename</sgmltag>
  extension.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>The XML source for the Handbook in English can be
	  found in <filename>/usr/doc/en/handbook/</filename>.  The
	  first file is called <filename>handbook.xml</filename> in
	  that directory.  There is also a
	  <filename>Makefile</filename> and a number of files with a
	  <filename>.ent</filename> extension.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-name-of-ports">
      <title>The Name of Ports</title>

      <note>
	<title>&os; Extension</title>

	<para>These elements are part of the &os; extension to
	  DocBook, and do not exist in the original DocBook
	  <acronym>DTD</acronym>.</para>
      </note>

      <para>To include the name of a program from the &os;
	Ports Collection in the document, use the
	<sgmltag>filename</sgmltag> tag with the
	<literal>role</literal> attribute set to
	<literal>package</literal>.  Since ports can be installed in
	any number of locations, only include the category and the
	port name; do not include
	<filename>/usr/ports</filename>.</para>

      <example>
	<title><sgmltag>filename</sgmltag> Tag with
	  <literal>package</literal> Role</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>Install the <sgmltag class="starttag">filename role="package"</sgmltag>net/wireshark<sgmltag class="endtag">filename</sgmltag> port to view network traffic.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

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

    <sect2 id="docbook-markup-devices">
      <title>Devices</title>

      <note>
	<title>&os; Extension</title>

	<para>These elements are part of the &os; extension to
	  DocBook, and do not exist in the original DocBook
	  <acronym>DTD</acronym>.</para>
      </note>

      <para>There are two names for devices: the device name as it
	appears in <filename>/dev</filename>, or the name of the
	device as it appears in the kernel.  For this latter course,
	use <sgmltag>devicename</sgmltag>.</para>

      <para>Sometimes there is no choice.  Some devices, such as
	network cards, do not have entries in
	<filename>/dev</filename>, or the entries are markedly
	different from their kernel device names.</para>

      <example>
	<title><sgmltag>devicename</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">devicename</sgmltag>sio<sgmltag class="endtag">devicename</sgmltag> is used for serial
  communication in FreeBSD.  <sgmltag class="starttag">devicename</sgmltag>sio<sgmltag class="endtag">devicename</sgmltag> manifests
  through a number of entries in <sgmltag class="starttag">filename</sgmltag>/dev<sgmltag class="endtag">filename</sgmltag>, including
  <sgmltag class="starttag">filename</sgmltag>/dev/ttyd0<sgmltag class="endtag">filename</sgmltag> and <sgmltag class="starttag">filename</sgmltag>/dev/cuaa0<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>By contrast, network devices such as
  <sgmltag class="starttag">devicename</sgmltag>ed0<sgmltag class="endtag">devicename</sgmltag> do not appear in <sgmltag class="starttag">filename</sgmltag>/dev<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>In MS-DOS, the first floppy drive is referred to as
  <sgmltag class="starttag">devicename</sgmltag>a:<sgmltag class="endtag">devicename</sgmltag>.  In FreeBSD it is
  <sgmltag class="starttag">filename</sgmltag>/dev/fd0<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

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

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

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

    <sect2 id="docbook-markup-hosts">
      <title>Hosts, Domains, IP Addresses, and So Forth</title>

      <note>
	<title>&os; Extension</title>

	<para>These elements are part of the &os; extension to
	  DocBook, and do not exist in the original DocBook
	  <acronym>DTD</acronym>.</para>
      </note>

      <para>Identification information for networked computers (hosts)
	can be marked up in several ways, depending on the nature of
	the information.  All of them use <sgmltag>hostid</sgmltag> as
	the element, with the <literal>role</literal> attribute
	selecting the type of the marked up information.</para>

      <variablelist>
	<varlistentry>
	  <term>No <literal>role</literal> attribute, or
	    <literal>role="hostname"</literal></term>

	  <listitem>
	    <para>With no <literal>role</literal> attribute (i.e.,
	      <sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>)
	      the marked up information is the simple hostname, such
	      as <literal>freefall</literal> or
	      <literal>wcarchive</literal>.  The hostname can be
	      explicitly specified with
	      <literal>role="hostname"</literal>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>role="domainname"</literal></term>

	  <listitem>
	    <para>The text is a domain name, such as
	      <literal>FreeBSD.org</literal> or
	      <literal>ngo.org.uk</literal>.  There is no hostname
	      component.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>role="fqdn"</literal></term>

	  <listitem>
	    <para>The text is a Fully Qualified Domain Name, with
	      both hostname and domain name parts.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>role="ipaddr"</literal></term>

	  <listitem>
	    <para>The text is an <acronym>IP</acronym> address,
	      probably expressed as a dotted quad.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>role="ip6addr"</literal></term>

	  <listitem>
	    <para>The text is an <acronym>IPv6</acronym>
	      address.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>role="netmask"</literal></term>

	  <listitem>
	    <para>The text is a network mask, which might be
	      expressed as a dotted quad, a hexadecimal string, or as
	      a <literal>/</literal> followed by a number
	      (<acronym>CIDR</acronym> notation).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>role="mac"</literal></term>

	  <listitem>
	    <para>The text is an Ethernet <acronym>MAC</acronym>
	      address, expressed as a series of 2 digit hexadecimal
	      numbers separated by colons.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <example>
	<title><sgmltag>hostid</sgmltag> and Roles</title>

	<para>Usage:</para>

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

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

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

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

	<para>Appearance:</para>

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

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

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

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

    <sect2 id="docbook-markup-usernames">
      <title>Usernames</title>

      <note>
	<title>&os; Extension</title>

	<para>These elements are part of the &os; extension to
	  DocBook, and do not exist in the original DocBook
	  <acronym>DTD</acronym>.</para>
      </note>

      <para>To refer to a specific username, such as
	<literal>root</literal> or <literal>bin</literal>, use
	<sgmltag>username</sgmltag>.</para>

      <example>
	<title><sgmltag>username</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>To carry out most system administration functions
  requires logging in as <sgmltag class="starttag">username</sgmltag>root<sgmltag class="endtag">username</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>To carry out most system administration functions
	  requires logging in as <username>root</username>.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-email-addresses">
      <title>Email Addresses</title>

      <para>Email addresses are marked up as <sgmltag>email</sgmltag>
	elements.  In the <acronym>HTML</acronym> output format, the
	wrapped text becomes a hyperlink to the email address.  Other
	output formats that support hyperlinks may also make the email
	address into a link.</para>

      <example>
	<title><sgmltag>email</sgmltag> with a Hyperlink</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>An email address that does not actually exist, like
  <sgmltag class="starttag">email</sgmltag>notreal@example.com<sgmltag class="endtag">email</sgmltag>, can be used as an
  example.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>An email address that does not actually exist, like
	  <email>notreal@example.com</email>, can be used as an
	  example.</para>
      </example>

      <para>A &os;-specific extension allows setting the
	<literal>role</literal> attribute to <literal>nolink</literal>
	to prevent the creation of the hyperlink to the email
	address.</para>

      <example>
	<title><sgmltag>email</sgmltag> Without a Hyperlink</title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>Sometimes a link to an email address like
  <sgmltag class="starttag">email role="nolink"</sgmltag>notreal@example.com<sgmltag class="endtag">email</sgmltag> is not
  desired.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>Sometimes a link to an email address like
	  <email role="nolink">notreal@example.com</email> is not
	  desired.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-describing-makefiles">
      <title>Describing <filename>Makefile</filename>s</title>

      <note>
	<title>&os; Extension</title>

	<para>These elements are part of the &os; extension to
	  DocBook, and do not exist in the original DocBook
	  <acronym>DTD</acronym>.</para>
      </note>

      <para>Two elements exist to describe parts of
	<filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag>
	and <sgmltag>makevar</sgmltag>.</para>

      <para><sgmltag>maketarget</sgmltag> identifies a build target
	exported by a <filename>Makefile</filename> that can be
	given as a parameter to <command>make</command>.
	<sgmltag>makevar</sgmltag> identifies a variable that can be
	set (in the environment, on the command line with
	<command>make</command>, or within the
	<filename>Makefile</filename>) to influence the
	process.</para>

      <example>
	<title><sgmltag>maketarget</sgmltag> and
	  <sgmltag>makevar</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>Two common targets in a <sgmltag class="starttag">filename</sgmltag>Makefile<sgmltag class="endtag">filename</sgmltag>
  are <sgmltag class="starttag">maketarget</sgmltag>all<sgmltag class="endtag">maketarget</sgmltag> and
  <sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag>.<sgmltag class="endtag">para</sgmltag>

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

<sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag> may be controlled by a
  number of variables, including <sgmltag class="starttag">makevar</sgmltag>CLOBBER<sgmltag class="endtag">makevar</sgmltag>
  and <sgmltag class="starttag">makevar</sgmltag>RECURSE<sgmltag class="endtag">makevar</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

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

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

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

    <sect2 id="docbook-markup-literal-text">
      <title>Literal Text</title>

      <para>Literal text, or text which should be entered verbatim, is
	often needed in documentation.  This is text that is excerpted
	from another file, or which should be copied exactly as shown
	from the documentation into another file.</para>

      <para>Some of the time, <sgmltag>programlisting</sgmltag> will
	be sufficient to denote this text.  But
	<sgmltag>programlisting</sgmltag> is not always appropriate,
	particularly when you want to include a portion of a file
	<quote>in-line</quote> with the rest of the
	paragraph.</para>

      <para>On these occasions, use
	<sgmltag>literal</sgmltag>.</para>

      <example>
	<title><sgmltag>literal</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">literal</sgmltag>maxusers 10<sgmltag class="endtag">literal</sgmltag> 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.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>The <literal>maxusers 10</literal> line in the kernel
	  configuration file determines the size of many system
	  tables, and is a rough guide to how many simultaneous
	  logins the system will support.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-replaceable">
      <title>Showing Items That the User <emphasis>Must</emphasis>
	Fill In</title>

      <para>There will often be times when the user is shown
	what to do, or referred to a file or command line, but
	cannot simply copy the example provided.  Instead, they
	must supply some information themselves.</para>

      <para><sgmltag>replaceable</sgmltag> is designed for this
	eventuality.  Use it <emphasis>inside</emphasis> other
	elements to indicate parts of that element's content that
	the user must replace.</para>

      <example>
	<title><sgmltag>replaceable</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">screen</sgmltag>&amp;prompt.user; <sgmltag class="starttag">userinput</sgmltag>man <sgmltag class="starttag">replaceable</sgmltag>command<sgmltag class="endtag">replaceable</sgmltag><sgmltag class="endtag">userinput</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting>

	<para>Appearance:</para>

	<informalexample>
	  <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
	</informalexample>

	<para><sgmltag>replaceable</sgmltag> can be used in many
	  different elements, including <sgmltag>literal</sgmltag>.
	  This example also shows that <sgmltag>replaceable</sgmltag>
	  should only be wrapped around the content that the user
	  <emphasis>is</emphasis> meant to provide.  The other content
	  should be left alone.</para>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">literal</sgmltag>maxusers <sgmltag class="starttag">replaceable</sgmltag>n<sgmltag class="endtag">replaceable</sgmltag><sgmltag class="endtag">literal</sgmltag>
  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.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>For a desktop workstation, <sgmltag class="starttag">literal</sgmltag>32<sgmltag class="endtag">literal</sgmltag> is a good value
  for <sgmltag class="starttag">replaceable</sgmltag>n<sgmltag class="endtag">replaceable</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>The
	  <literal>maxusers <replaceable>n</replaceable></literal>
	  line in the kernel configuration file determines the size
	  of many system tables, and is a rough guide to how many
	  simultaneous logins the system will support.</para>

	<para>For a desktop workstation, <literal>32</literal> is a
	  good value for <replaceable>n</replaceable>.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-gui-buttons">
      <title>Showing <acronym>GUI</acronym> Buttons</title>

      <para>Buttons presented by a graphical user interface are marked
	with <sgmltag>guibutton</sgmltag>.  To make the text look more
	like a graphical button, brackets and non-breaking spaces are
	added surrounding the text.</para>

      <example>
	<title><sgmltag>guibutton</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>Edit the file, then click
  <sgmltag class="starttag">guibutton</sgmltag>[&amp;nbsp;Save&amp;nbsp;]<sgmltag class="endtag">guibutton</sgmltag> to save the
  changes.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>Appearance:</para>

	<para>Edit the file, then click
	  <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
	  changes.</para>
      </example>
    </sect2>

    <sect2 id="docbook-markup-system-errors">
      <title>Quoting System Errors</title>

      <para>System errors generated by &os; are marked with
	<sgmltag>errorname</sgmltag>.  This indicates the exact error
	that appears.</para>

      <example>
	<title><sgmltag>errorname</sgmltag></title>

	<para>Usage:</para>

	<programlisting><sgmltag class="starttag">screen</sgmltag><sgmltag class="starttag">errorname</sgmltag>Panic: cannot mount root<sgmltag class="endtag">errorname</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting>

	<para>Appearance:</para>

	<informalexample>
	  <screen><errorname>Panic: cannot mount root</errorname></screen>
	</informalexample>
      </example>
    </sect2>
  </sect1>

  <sect1 id="docbook-markup-images">
    <title>Images</title>

    <important>
      <para>Image support in the documentation is somewhat
	experimental.  The mechanisms described here are unlikely to
	change, but that is not guaranteed.</para>

      <para>To provide conversion between different image formats, the
	<filename role="package">graphics/ImageMagick</filename>
	port must be installed.  This port is not included in the
	<filename role="package">textproc/docproj</filename> meta
	port, and must be installed separately.</para>

      <para>A good example of the use of images is the
	<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
	document.  Examine the files in that directory to see how
	these elements are used together.  Build different output
	formats to see how the format determines what images are shown
	in the rendered document.</para>
    </important>

    <sect2 id="docbook-markup-image-formats">
      <title>Image Formats</title>

      <para>Two image formats are currently supported.  The type of
	image determines which format to use.</para>

      <para>Images that are primarily vector based, such as network
	diagrams, time lines, and similar, should be in
	<acronym>EPS</acronym> (Encapsulated Postscript) format.
	These images have a <filename>.eps</filename>
	extension.</para>

      <para>For bitmaps, such as screen captures, use the
	<acronym>PNG</acronym> (Portable Network Graphic) format.
	These images have the <filename>.png</filename>
	extension.</para>

      <para>These are the <emphasis>only</emphasis> formats in which
	images should be committed to the documentation
	repository.</para>

      <para>Use the appropriate format for each image.  Documentation
	will often have a mix of <acronym>EPS</acronym> and
	<acronym>PNG</acronym> images.  The
	<filename>Makefile</filename>s ensure that the correct format
	image is chosen depending on the output format used.
	<emphasis>Do not commit the same image to the repository in
	  two different formats</emphasis>.</para>

      <important>
	<para>The Documentation Project may eventually switch to using
	  the <acronym>SVG</acronym> (Scalable Vector Graphic) format
	  for vector images.  However, the current state of
	  <acronym>SVG</acronym> capable editing tools makes this
	  impractical.</para>
      </important>
    </sect2>

    <sect2 id="docbook-markup-image-file-locations">
      <title>Image File Locations</title>

      <para>Image files can be stored in one of several locations,
	depending on the document and image:</para>

      <itemizedlist>
	<listitem>
	  <para>In the same directory as the document itself, usually
	    done for articles and small books that keep all their
	    files in a single directory.</para>
	</listitem>

	<listitem>
	  <para>In a subdirectory of the main document.  Typically
	    done when a large book uses separate subdirectories to
	    organize individual chapters.</para>

	  <para>When images are stored in a subdirectory of the
	    main document directory, the subdirectory name must be
	    included in their paths in the
	    <filename>Makefile</filename> and the
	    <sgmltag>imagedata</sgmltag> element.</para>
	</listitem>

	<listitem>
	  <para>In a subdirectory of
	    <filename class="directory">doc/share/images</filename>
	    named after the document.  For example, images for the
	    Handbook are stored in <filename
	      class="directory">doc/share/images/books/handbook</filename>.
	    Images that work for multiple translations are stored in
	    this upper level of the documentation file tree.
	    Generally, these are images that can be used unchanged in
	    non-English translations of the document.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="docbook-markup-image-markup">
      <title>Image Markup</title>

      <para>Images are included as part of a
	<sgmltag>mediaobject</sgmltag>.  The
	<sgmltag>mediaobject</sgmltag> can contain other, more
	specific objects.  We are concerned with two, the
	<sgmltag>imageobject</sgmltag> and the
	<sgmltag>textobject</sgmltag>.</para>

      <para>Include one <sgmltag>imageobject</sgmltag>, and two
	<sgmltag>textobject</sgmltag> elements.  The
	<sgmltag>imageobject</sgmltag> will point to the name of the
	image file without the extension.  The
	<sgmltag>textobject</sgmltag> elements contain information
	that will be presented to the user as well as, or instead of,
	the image itself.</para>

      <para>Text elements are shown to the reader in several
	situations.  When the document is viewed in
	<acronym>HTML</acronym>, text elements are shown while the
	image is loading, or if the mouse pointer is hovered over the
	image, or if a text-only browser is being used.  In formats
	like plain text where graphics are not possible, the text
	elements are shown instead of the graphical ones.</para>

      <para>This example shows how to include an image called
	<filename>fig1.png</filename> in a document.  The image is a
	rectangle with an A inside it:</para>

      <programlisting><sgmltag class="starttag">mediaobject</sgmltag>
  <sgmltag class="starttag">imageobject</sgmltag>
    <sgmltag class="starttag">imagedata fileref="fig1"</sgmltag> <co id="co-image-ext"/>
  <sgmltag class="endtag">imageobject</sgmltag>

  <sgmltag class="starttag">textobject</sgmltag>
    <sgmltag class="starttag">literallayout class="monospaced"</sgmltag>+---------------+ <co id="co-image-literal"/>
|       A       |
+---------------+<sgmltag class="endtag">literallayout</sgmltag>
  <sgmltag class="endtag">textobject</sgmltag>

  <sgmltag class="starttag">textobject</sgmltag>
    <sgmltag class="starttag">phrase</sgmltag>A picture<sgmltag class="endtag">phrase</sgmltag> <co id="co-image-phrase"/>
  <sgmltag class="endtag">textobject</sgmltag>
<sgmltag class="endtag">mediaobject</sgmltag></programlisting>

      <calloutlist>
	<callout arearefs="co-image-ext">
	  <para>Include an <sgmltag>imagedata</sgmltag> element
	    inside the <sgmltag>imageobject</sgmltag> element.  The
	    <literal>fileref</literal> attribute should contain the
	    filename of the image to include, without the extension.
	    The stylesheets will work out which extension should be
	    added to the filename automatically.</para>
	</callout>

	<callout arearefs="co-image-literal">

	  <para>The first <sgmltag>textobject</sgmltag> contains a
	    <sgmltag>literallayout</sgmltag> element, where the
	    <literal>class</literal> attribute is set to
	    <literal>monospaced</literal>.  This is an opportunity to
	    demonstrate <acronym>ASCII</acronym> art skills.  This
	    content will be used if the document is converted to plain
	    text.</para>

	  <para>Notice how the first and last lines of the content
	    of the <sgmltag>literallayout</sgmltag> element butt up
	    next to the element's tags.  This ensures no extraneous
	    white space is included.</para>
	</callout>

	<callout arearefs="co-image-phrase">
	  <para>The second <sgmltag>textobject</sgmltag> contains a
	    single <sgmltag>phrase</sgmltag> element.  The contents of
	    this phrase will become the <literal>alt</literal>
	    attribute for the image when this document is converted to
	    <acronym>HTML</acronym>.</para>
	</callout>
      </calloutlist>
    </sect2>

    <sect2 id="docbook-markup-image-makefile-entries">
      <title>Image <filename>Makefile</filename> Entries</title>

      <para>Images must be listed in the <filename>Makefile</filename>
	in the <makevar>IMAGES</makevar> variable.  This variable must
	contain the names of all the <emphasis>source</emphasis>
	images.  For example, if there are three figures,
	<filename>fig1.eps</filename>, <filename>fig2.png</filename>,
	<filename>fig3.png</filename>, then the
	<filename>Makefile</filename> should have lines like this in
	it.</para>

      <programlisting>&hellip;
IMAGES= fig1.eps fig2.png fig3.png
&hellip;</programlisting>

	<para>or</para>

	<programlisting>&hellip;
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
&hellip;</programlisting>

      <para>Again, the <filename>Makefile</filename> will work out the
	complete list of images it needs to build the source document,
	you only need to list the image files <emphasis>you</emphasis>
	provided.</para>
    </sect2>

    <sect2 id="docbook-markup-images-in-subdirectories">
      <title>Images and Chapters in Subdirectories</title>

      <para>Be careful when separating documentation into smaller
	files in different directories (see <xref
	  linkend="xml-primer-include-using-gen-entities"/>).</para>

      <para>Suppose there is a book with three chapters, and the
	chapters are stored in their own directories, called
	<filename>chapter1/chapter.xml</filename>,
	<filename>chapter2/chapter.xml</filename>, and
	<filename>chapter3/chapter.xml</filename>.  If each chapter
	has images associated with it, place
	those images in each chapter's subdirectory
	(<filename>chapter1/</filename>,
	<filename>chapter2/</filename>, and
	<filename>chapter3/</filename>).</para>

      <para>However, doing this requires including the directory
	names in the <makevar>IMAGES</makevar> variable in the
	<filename>Makefile</filename>, <emphasis>and</emphasis>
	including the directory name in the
	<sgmltag>imagedata</sgmltag> element in the document
	document.</para>

      <para>For example, if the book has
	<filename>chapter1/fig1.png</filename>, then
	<filename>chapter1/chapter.xml</filename> should
	contain:</para>

      <programlisting><sgmltag class="starttag">mediaobject</sgmltag>
  <sgmltag class="starttag">imageobject</sgmltag>
    <sgmltag class="emptytag">imagedata fileref="chapter1/fig1"</sgmltag> <co id="co-image-dir"/>
  <sgmltag class="endtag">imageobject</sgmltag>

  &hellip;

<sgmltag class="endtag">mediaobject</sgmltag></programlisting>

      <calloutlist>
	<callout arearefs="co-image-dir">
	  <para>The directory name must be included in the
	    <literal>fileref</literal> attribute.</para>
	</callout>
      </calloutlist>

      <para>The <filename>Makefile</filename> must contain:</para>

      <programlisting>&hellip;
IMAGES=  chapter1/fig1.png
&hellip;</programlisting>
    </sect2>
  </sect1>

  <sect1 id="docbook-markup-links">
    <title>Links</title>

    <note>
      <para>Links are also in-line elements.</para>
    </note>

    <sect2 id="docbook-markup-links-ids">
      <title><literal>id</literal> Attributes</title>

      <para>Most DocBook elements accept an <literal>id</literal>
	attribute to give that part of the document a unique name.
	The <literal>id</literal> can be used as a target for a
	crossreference or link.</para>

      <para>Any portion of the document that will be a link target
	must have an <literal>id</literal> attribute.  Assigning an
	<literal>id</literal> to all chapters and sections, even if
	there are no current plans to link to them, is a good idea.
	These <literal>id</literal>s can be used as unique anchor
	reference points by anyone referring to the
	<acronym>HTML</acronym> version of the document.</para>

      <example>
	<title><literal>id</literal> on Chapters and
	  Sections</title>

	<programlisting><sgmltag class="starttag">chapter id="introduction"</sgmltag>
  <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag>

  <sgmltag class="starttag">para</sgmltag>This is the introduction.  It contains a subsection,
    which is identified as well.<sgmltag class="endtag">para</sgmltag>

  <sgmltag class="starttag">sect1 id="introduction-moredetails"</sgmltag>
    <sgmltag class="starttag">title</sgmltag>More Details<sgmltag class="endtag">title</sgmltag>

    <sgmltag class="starttag">para</sgmltag>This is a subsection.<sgmltag class="endtag">para</sgmltag>
  <sgmltag class="endtag">sect1</sgmltag>
<sgmltag class="endtag">chapter</sgmltag></programlisting>
      </example>

      <para>Use descriptive values for <literal>id</literal> names.
	The values must be unique within the entire document, not just
	in a single file.  In the example, the subsection
	<literal>id</literal> is constructed by appending text to the
	chapter <literal>id</literal>.  This ensures that the
	<literal>id</literal>s are unique.  It also helps both reader
	and anyone editing the document to see where the link is
	located within the document, similar to a directory
	path to a file.</para>

      <para>To allow the user to jump into a specific portion of the
	document, even in the middle of a paragraph or an example, use
	<sgmltag>anchor</sgmltag>.  This element has no content, but
	takes an <literal>id</literal> attribute.</para>

      <example>
	<title><sgmltag>anchor</sgmltag></title>

	<programlisting><sgmltag class="starttag">para</sgmltag>This paragraph has an embedded
  <sgmltag class="emptytag">anchor id="para1"</sgmltag>link target in it.  It will not
  show up in the document.<sgmltag class="endtag">para</sgmltag></programlisting>
      </example>
    </sect2>

    <sect2 id="docbook-markup-links-crossreferences">
      <title>Crossreferences with <literal>xref</literal></title>

      <para><sgmltag>xref</sgmltag> provides the reader with a link to
	jump to another section of the document.  The target
	<literal>id</literal> is specified in the
	<literal>linkend</literal> attribute, and
	<sgmltag>xref</sgmltag> generates the link text
	automatically.</para>

      <example>
	<title>Using <sgmltag>xref</sgmltag></title>

	<para>Assume that this fragment appears somewhere in a
	  document that includes the <literal>id</literal>
	  example shown above:</para>

	<programlisting><sgmltag class="starttag">para</sgmltag>More information can be found
  in <sgmltag class="emptytag">xref linkend="introduction"</sgmltag>.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>More specific information can be found
  in <sgmltag class="emptytag">xref linkend="introduction-moredetails"</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	<para>The link text will be generated automatically, looking
	  like (<emphasis>emphasized</emphasis> text indicates the
	  link text):</para>

	<blockquote>
	  <para>More information can be found in <emphasis>Chapter
	      1, Introduction</emphasis>.</para>

	  <para>More specific information can be found in
	    <emphasis>Section 1.1,
	      <quote>More Details</quote></emphasis>.</para>
	</blockquote>
      </example>

      <para>The link text is generated automatically from the chapter
	and section number and <literal>title</literal>
	elements.</para>

      <note>
	<para><sgmltag>xref</sgmltag> cannot link to an
	  <literal>id</literal> attribute on an
	  <sgmltag>anchor</sgmltag> element.  The
	  <sgmltag>anchor</sgmltag> has no content, so the
	  <sgmltag>xref</sgmltag> cannot generate the link
	  text.</para>
      </note>
    </sect2>

    <sect2 id="docbook-markup-links-to-same-or-web-documents">
      <title>Linking to the Same Document or Other Documents on the
	Web</title>

      <para>The link elements described here allow the writer to
	define the link text.  It is very important to use descriptive
	link text to give the reader an idea of where the link will
	take them.  Remember that DocBook can be rendered to multiple
	types of media.  The reader may be looking at a printed book
	or other form of media where there are no links.  If the link
	text is not descriptive enough, the reader may not be able to
	locate the linked section.</para>

      <sect3 id="docbook-markup-links-to-same-document">
	<title>Links to the Same Document</title>

	<para><sgmltag>link</sgmltag> is used to create a link
	  within the same document.  The target <literal>id</literal>
	  is specified in the <literal>linkend</literal> attribute.
	  This element wraps content, which is used for the link
	  text.</para>

	<example>
	  <title>Using <sgmltag>link</sgmltag></title>

	  <para>Assume that this fragment appears somewhere in a
	    document that includes the <literal>id</literal>
	    example.</para>

	  <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found in the
  <sgmltag class="starttag">link linkend="introduction"</sgmltag>sample introduction<sgmltag class="endtag">link</sgmltag>.<sgmltag class="endtag">para</sgmltag>

<sgmltag class="starttag">para</sgmltag>More specific information can be found in the
  <sgmltag class="starttag">link linkend="introduction-moredetails"</sgmltag>sample introduction with more
    details<sgmltag class="endtag">link</sgmltag> section.<sgmltag class="endtag">para</sgmltag></programlisting>

	  <para>This output will be generated
	    (<emphasis>emphasized</emphasis> text is used to show the
	    link text):</para>

	  <blockquote>
	    <para>More information can be found in the
	      <emphasis>sample introduction</emphasis>.</para>

	    <para>More specific information can be found in the
	      <emphasis>sample introduction with more
		details</emphasis> section.</para>
	  </blockquote>
	</example>

	<note>
	  <para><sgmltag>link</sgmltag> can be used to include links
	    to the <literal>id</literal> of an
	    <sgmltag>anchor</sgmltag> element, since the
	    <sgmltag>link</sgmltag> content defines the link
	    text.</para>
	</note>
      </sect3>

      <sect3 id="docbook-markup-links-to-web-documents">
	<title>Linking to Other Documents on the Web</title>

	<para>The <sgmltag>ulink</sgmltag> is used to link to
	  external documents on the web.  The <literal>url</literal>
	  attribute is the <acronym>URL</acronym> of the page that the
	  link points to, and the content of the element is the text
	  that will be displayed for the user to activate.</para>

	<example>
	  <title><sgmltag>ulink</sgmltag> to a &os; Documentation Web
	    Page</title>

	  <para>Link to the book or article <acronym>URL</acronym>
	    entity.  To link to a specific chapter in a book, add a
	    slash and the chapter file name, followed by an optional
	    anchor within the chapter.  For articles, link to the
	    article <acronym>URL</acronym> entity, followed by an
	    optional anchor within the article.
	    <acronym>URL</acronym> entities can be found in
	    <filename>doc/share/xml/urls.ent</filename>.</para>

	  <para>Usage for book links:</para>

	  <programlisting><sgmltag class="starttag">para</sgmltag>Read the <sgmltag class="starttag">ulink
    url="&amp;url.books.handbook;/svn.html#svn-intro"</sgmltag>SVN
    introduction<sgmltag class="endtag">ulink</sgmltag>, then pick the nearest mirror from
  the list of <sgmltag class="starttag">ulink
    url="&amp;url.books.handbook;/svn-mirrors.html"</sgmltag>Subversion
    mirror sites<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	  <para>Appearance:</para>

	  <para>Read the <ulink
	      url="&url.books.handbook;/svn.html#svn-intro">SVN
	      introduction</ulink>, then pick the nearest mirror from
	    the list of <ulink
	      url="&url.books.handbook;/svn-mirrors.html">Subversion
	      mirror sites</ulink>.</para>

	  <para>Usage for article links:</para>

	  <programlisting><sgmltag class="starttag">para</sgmltag>Read this
  <sgmltag class="starttag">ulink url="&amp;url.articles.bsdl-gpl;"</sgmltag>article
    about the BSD license<sgmltag class="endtag">ulink</sgmltag>, or just the
  <sgmltag class="starttag">ulink url="&amp;url.articles.bsdl-gpl;#intro"</sgmltag>introduction<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	  <para>Appearance:</para>

	  <para>Read this <ulink url="&url.articles.bsdl-gpl;">article
	      about the BSD license</ulink>, or just the <ulink
	      url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>
	</example>

	<example>
	  <title><sgmltag>ulink</sgmltag> to a &os; Web Page</title>

	  <para>Usage:</para>

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

	  <para>Appearance:</para>

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

	<example>
	  <title><sgmltag>ulink</sgmltag> to an External Web
	    Page</title>

	  <para>Usage:</para>

	  <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on
  <sgmltag class="starttag">ulink
    url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag>GUID
    Partition Tables<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	  <para>Appearance:</para>

	  <para>Wikipedia has an excellent reference on
	    <ulink
	      url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
	      Partition Tables</ulink>.</para>

	  <para>The link text can be omitted to show the actual
	    URL:</para>

	  <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on
  GUID Partition Tables: <sgmltag class="starttag">ulink
    url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag><sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>

	  <para>Appearance:</para>

	  <para>Wikipedia has an excellent reference on
	    GUID Partition Tables: <ulink
	      url="http://en.wikipedia.org/wiki/GUID_Partition_Table"></ulink>.</para>
	</example>
      </sect3>
    </sect2>
  </sect1>
</chapter>