diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
index 20dc438fec..f112fbcc69 100644
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
@@ -1,498 +1,498 @@
 <!-- Copyright (c) 1999 Neil Blakey-Milner, 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 THE AUTHOR "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: doc/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml,v 1.5 2001/07/05 08:47:55 dd Exp $
+     $FreeBSD$
 -->
 
 <chapter id="doc-build">
   <title>The Documentation Build Process</title>
 
   <para>This chapter's main purpose is to clearly explain <emphasis>how
     the documentation build process is organised</emphasis>, and
     <emphasis>how to affect modifications to this process</emphasis>.
     </para>
 
   <para>After you have finished reading this chapter you should:</para>
 
   <itemizedlist>
     <listitem>
       <para>Know what you need to build the FDP documentation, in
 	addition to those mentioned in the <link
 	linkend="tools">SGML tools chapter</link>.</para>
     </listitem>
 
     <listitem>
       <para>Be able to read and understand the
 	<application>make</application> instructions that are present in
 	each document's <filename>Makefile</filename>s, as well as an
 	overview of the <filename>doc.project.mk</filename> includes.</para>
     </listitem>
  
     <listitem>
       <para>Be able to customize the build process by using
 	<application>make</application> variables and
 	<application>make</application> targets.</para>
     </listitem>
   </itemizedlist>
 
   <sect1>
     <title>The FreeBSD Documentation Build Toolset</title>
 
     <para>Here are your tools.  Use them every way you can.</para>
 
     <itemizedlist>
       <listitem>
 	<para>The primary build tool you will need is
 	  <application>make</application>, but specifically
 	  <application>Berkeley Make</application>.</para>
       </listitem>
 
       <listitem>
 	<para>Package building is handled by FreeBSD's
 	  <application>pkg_create</application>.  If you are not using
 	  FreeBSD, you will either have to live without packages, or
 	  compile the source yourself.</para>
       </listitem>
 
       <listitem>
 	<para><application>gzip</application> is needed to create
 	  compressed versions of the document.
 	  <application>bzip2</application> compression and
 	  <application>zip</application> archives are also supported.
 	  <application>tar</application> is supported, but package
 	  building demands it.</para>
       </listitem>
 
       <listitem>
 	<para><application>install</application> is the default method
 	  to install the documentation.  There are alternatives,
 	  however.</para>
       </listitem>
     </itemizedlist>
 
     <note>
       <para>It is unlikely you will not be able to find these last two, they
 	are mentioned for completeness.</para>
     </note>
   </sect1>
 
   <sect1>
     <title>Understanding Makefiles in the Documentation tree</title>
 
     <para>There are three main types of <filename>Makefile</filename>s 
       in the FreeBSD Documentation Project tree.</para>
 
     <itemizedlist>
       <listitem>
 	<para><link linkend="sub-make">Subdirectory
 	  <filename>Makefile</filename>s</link> simply pass
 	  commands to those directories below them.</para>
       </listitem>
 
       <listitem>
 	<para><link linkend="doc-make">Documentation
 	  <filename>Makefile</filename>s</link> describe the
 	  document(s) that should be produced from this directory.</para>
       </listitem>
 
       <listitem>
 	<para><link linkend="make-includes"><application>Make</application>
 	  includes</link> are the glue that perform the document production,
 	  and are usually of the form
 	  <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="sub-make">
       <title>Subdirectory Makefiles</title>
 
       <para>These directories usually take the form of:</para>
 
       <programlisting>SUBDIR =articles
 SUBDIR+=books
 
 COMPAT_SYMLINK = en
 
 DOC_PREFIX?= ${.CURDIR}/..
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
 
       <para>In quick summary, the first four non-empty lines define the
 	<application>make</application> variables,
 	<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
 	and <makevar>DOC_PREFIX</makevar>.</para>
 
       <para>The first <makevar>SUBDIR</makevar> statement, as well as
 	the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to
 	assign a value to a variable, overriding any previous
 	value.</para>
 
       <para>The second <makevar>SUBDIR</makevar> statement shows how a
 	value is appended to the current value of a variable.  The
 	<makevar>SUBDIR</makevar> variable is now <literal>articles
 	books</literal>.</para>
 
       <para>The <makevar>DOC_PREFIX</makevar> assignment shows how a
 	value is assigned to the variable, but only if it is not already
 	defined.  This is useful if <makevar>DOC_PREFIX</makevar> is not
 	where this <filename>Makefile</filename> thinks it is - the user
 	can override this and provide the correct value.</para>
 
       <para>Now what does it all mean?  <makevar>SUBDIR</makevar>
 	mentions which subdirectories below this one the build process
 	should pass any work on to.</para>
 
       <para><makevar>COMPAT_SYMLINK</makevar> is specific to
 	compatibility symlinks (amazingly enough) for languages to their
 	official encoding (<filename>doc/en</filename> would point to
 	<filename>en_US.ISO-8859-1</filename>).</para>
 
       <para><makevar>DOC_PREFIX</makevar> is the path to the root of the
 	FreeBSD Document Project tree.  This is not always that easy to
-	find, and is also easily overridable, to allow for flexibility.
+	find, and is also easily overridden, to allow for flexibility.
 	<makevar>.CURDIR</makevar> is a <application>make</application>
 	builtin variable with the path to the current directory.</para>
 
       <para>The final line includes the FreeBSD Documentation Project's
 	project-wide <application>make</application> system file
 	<filename>doc.project.mk</filename> which is the glue which
 	converts these variables into build instructions.</para>
 
     </sect2>
     <sect2 id="doc-make">
       <title>Documentation Makefiles</title>
 
       <para>These <filename>Makefile</filename>s set a bunch of
 	<application>make</application> variables that describe how to
 	build the documentation contained in that directory.</para>
 
       <para>Here is an example:</para>
 
       <programlisting>MAINTAINER=nik@FreeBSD.org
 
 DOC?= book
 
 FORMATS?= html-split html
 
 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=
 
 # SGML content
 SRCS=  book.sgml
 
 DOC_PREFIX?= ${.CURDIR}/../../..
 
 .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
 
       <para>The <makevar>MAINTAINER</makevar> variable is a very 
 	important one.  This variable provides the ability to claim
 	ownership over a document in the FreeBSD Documentation
 	Project, whereby you gain the responsibility for maintaining 
 	it.</para>
 
       <para><makevar>DOC</makevar> is the name (sans the
 	<filename>.sgml</filename> extension) of the main document
 	created by this directory.  <makevar>SRCS</makevar> lists all
 	the individual files that make up the document.  This should
 	also include important files in which a change should result
 	in a rebuild.</para>
 
       <para><makevar>FORMATS</makevar> indicates the default formats
 	that should be built for this document.
 	<makevar>INSTALL_COMPRESSED</makevar> is the default list of
 	compression techniques that should be used in the document
 	build.  <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by
 	default, should be non-empty if only compressed documents are
 	desired in the build.</para>
 
       <note>
 	<para>We covered optional variable assignments in the 
 	  <link linkend="sub-make">previous section</link>.</para>
       </note>
 
       <para>The <makevar>DOC_PREFIX</makevar> and include statements
 	should be familiar already.</para>
     </sect2>
   </sect1>
 
   <sect1 id="make-includes">
     <title>FreeBSD Documentation Project make includes</title>
 
     <para>This is best explained by inspection of the code.  Here are
       the system include files:</para>
 
     <itemizedlist>
       <listitem>
 	<para><filename>doc.project.mk</filename> is the main project
 	  include file, which includes all the following include files, as
 	  necessary.</para>
       </listitem>
 
       <listitem>
 	<para><filename>doc.subdir.mk</filename> handles traversing of
 	  the document tree during the build and install processes.</para>
       </listitem>
 
       <listitem>
 	<para><filename>doc.install.mk</filename> provides variables
 	  that affect ownership and installation of documents.</para>
       </listitem>
 
       <listitem>
 	<para><filename>doc.docbook.mk</filename> is included if
 	  <makevar>DOCFORMAT</makevar> is <literal>docbook</literal>
 	  and <makevar>DOC</makevar> is set.</para>
       </listitem>
     </itemizedlist>
 
     <sect2>
       <title>doc.project.mk</title>
 
       <para>By inspection:</para>
 
       <programlisting>DOCFORMAT?=	docbook
 MAINTAINER?=	doc@FreeBSD.org
 
 PREFIX?=	/usr/local
 PRI_LANG?=	en_US.ISO8859-1
 
 .if defined(DOC)
 .if ${DOCFORMAT} == "docbook"
 .include "doc.docbook.mk"
 .endif
 .endif
 
 .include "doc.subdir.mk"
 .include "doc.install.mk"</programlisting>
 
       <sect3>
 
 	<title>Variables</title>
 
 	<para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar>
 	  are assigned default values, if these are not set by the
 	  document make file.</para>
 
 	<para><makevar>PREFIX</makevar> is the prefix under which the
 	  <link linkend="tools">documentation building tools</link> are
 	  installed.  For normal package and port installation, this is
 	  <filename>/usr/local</filename>.</para>
 
 	<para><makevar>PRI_LANG</makevar> should be set to whatever
 	  language and encoding is natural amongst users these documents are
 	  being built for.  US English is the default.</para>
 
 	<note>
 	  <para><makevar>PRI_LANG</makevar> in no way affects what documents
 	    can, or even will, be built.  It's main use is creating links to
 	    commonly referenced documents into the FreeBSD documentation
 	    install root.</para>
 	</note>
       </sect3>
 
       <sect3>
 	<title>Conditionals</title>
        
 	<para>The <literal>.if defined(DOC)</literal> line is an example of
 	  a <application>make</application> conditional which, like in
 	  other programs, defines behaviour if some condition is true or
 	  if it is false.  <literal>defined</literal> is a function which
 	  returns whether the variable given is defined or not.</para>
 
 	<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
 	  tests whether the <makevar>DOCFORMAT</makevar> variable is
 	  <literal>"docbook"</literal>, and in this case, includes
 	  <filename>doc.docbook.mk</filename>.</para>
 
 	<para>The two <literal>.endif</literal>s close the two above
 	  conditionals, marking the end of their application.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>doc.subdir.mk</title>
 
       <para>This is too long to explain by inspection, you should be
 	able to work it out with the knowledge gained from the previous
 	chapters, and a little help given here.</para>
 
       <sect3>
 	<title>Variables</title>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><makevar>SUBDIR</makevar> is a list of subdirectories 
 	      that the build process should go further down
 	      into.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><makevar>ROOT_SYMLINKS</makevar> is the name of
 	      directories that should be linked to the document
 	      install root from their actual locations, if the current
 	      language is the primary language (specified by
 	      <makevar>PRI_LANG</makevar>).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><makevar>COMPAT_SYMLINK</makevar> is described in the
 	      <link linkend="sub-make">Subdirectory Makefile</link>
 	      section.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Targets and macros</title>
 
 	<para>Dependencies are described by 
 	  <literal><replaceable>target</replaceable>:
 	  <replaceable>dependency1 dependency2 ...</replaceable></literal>
 	  tuples, where to build <literal>target</literal>, you need to build
 	  the given dependencies first.</para>
 
 	<para>After that descriptive tuple, instructions on how to build
 	  the target may be given, if the conversion process between the
 	  target and it's dependencies are not previously defined, or if
 	  this particular conversion is not the same as the default
 	  conversion method.</para>
 
 	<para>A special dependency <literal>.USE</literal> defines
 	  the equivalent of a macro.</para>
 
 <programlisting>_SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
 	@${ECHO} "===> ${DIRPRFX}${entry}"
 	@(cd ${.CURDIR}/${entry} && \
 	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor</programlisting>
 
 	<para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now a
 	  macro which will execute the given commands when it is listed
 	  as a dependency.</para>
 
 	<para>What sets this macro apart from other targets?  Basically,
 	  it is executed <emphasis>after</emphasis> the instructions
 	  given in the build procedure it is listed as a dependency to,
 	  and it doesn't adjust <makevar>.TARGET</makevar>, which is the
 	  variable which contains the name of the target currently
 	  being built.</para>
 
 <programlisting>clean: _SUBDIRUSE
 	rm -f ${CLEANFILES}</programlisting>
 
 	<para>In the above, <maketarget>clean</maketarget> will use the
 	  <maketarget>_SUBDIRUSE</maketarget> macro after it has
 	  executed the instruction 
 	  <command>rm -f ${CLEANFILES}</command>.  In effect, this causes
 	  <maketarget>clean</maketarget> to go further and further down
 	  the directory tree, deleting built files as it goes
 	  <emphasis>down</emphasis>, not on the way back up.</para>
 
 	<sect4>
 	  <title>Provided targets</title>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><maketarget>install</maketarget> and
 		<maketarget>package</maketarget> both go down the
 		directory tree calling the real versions of themselves
 		in the subdirectories.
 		(<maketarget>realinstall</maketarget> and
 		<maketarget>realpackage</maketarget>
 		 respectively)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para><maketarget>clean</maketarget> removes files created
 		by the build process (and goes down the directory tree
 		too).  <maketarget>cleandir</maketarget> does the same,
 		and also removes the object directory, if any.</para>
 	    </listitem>
 	  </itemizedlist>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>More on conditionals</title>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><literal>exists</literal> is another condition
 	      function which returns true if the given file exists.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><literal>empty</literal> returns true if the given
 	      variable is empty.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><literal>target</literal> returns true if the given
 	      target does not already exist.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Looping constructs in make (.for)</title>
 
 	<para><literal>.for</literal> provides a way to repeat a set of
 	  instructions for each space-separated element in a variable.
 	  It does this by assigning a variable to contain the current
 	  element in the list being examined.</para>
 
 <programlisting>_SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
 	@${ECHO} "===> ${DIRPRFX}${entry}"
 	@(cd ${.CURDIR}/${entry} && \
 	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor</programlisting>
 
 	<para>In the above, if <makevar>SUBDIR</makevar> is empty, no
 	  action is taken; if it has one or more elements, the
 	  instructions between <literal>.for</literal> and
 	  <literal>.endfor</literal> would repeat for every element,
 	  with <makevar>entry</makevar> being replaced with the value of
 	  the current element.</para>
       </sect3>
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 7d90a804ad..359e4bf337 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -1,2600 +1,2601 @@
 <!-- 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="sgml-markup">
   <title>SGML Markup</title>
 
   <para>This chapter describes the two markup languages you will encounter
     when you contribute to the FreeBSD documentation project.  Each section
     describes the markup language, and details the markup that you are likely
     to want to use, or that is already in use.</para>
 
   <para>These markup languages contain a large number of elements, and it can
     be confusing sometimes to know which element to use for a particular
     situation.  This section goes through the elements you are most likely to
     need, and gives examples of how you would use them.</para>
   
   <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
     that would just reiterate the documentation for each language.  The aim of
     this section is to list those elements more likely to be useful to you.
     If you have a question about how best to markup a particular piece of
     content, please post it to the FreeBSD Documentation Project mailing list
     <email>freebsd-doc@FreeBSD.org</email>.</para>
 
   <note>
     <title>Inline vs. block</title>
     
     <para>In the remainder of this document, when describing elements,
       <emphasis>inline</emphasis> means that the element can occur within a
       block element, and does not cause a line break.  A
       <emphasis>block</emphasis> element, by comparison, will cause a line
       break (and other processing) when it is encountered.</para>
   </note>
   
   <sect1>
     <title>HTML</title>
     
     <para>HTML, the HyperText Markup Language, is the markup language of
       choice on the World Wide Web.  More information can be found at
       &lt;URL:<ulink
 	url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</para>
 
     <para>HTML is used to markup pages on the FreeBSD web site.  It should not
-      (generally) be used to mark up other documention, since DocBook offers a
+      (generally) be used to mark up other documentation, 
+      since DocBook offers a
       far richer set of elements to choose from.  Consequently, you will
       normally only encounter HTML pages if you are writing for the web
       site.</para>
 
     <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
       latest, 4.0 (available in both <emphasis>strict</emphasis> and
       <emphasis>loose</emphasis> variants).</para>
 	  
     <para>The HTML DTDs are available from the ports collection in the
       <filename>textproc/html</filename> port.  They are automatically
       installed as part of the <filename>textproc/docproj</filename>
       port.</para>
 
     <sect2>
       <title>Formal Public Identifier (FPI)</title>
 
       <para>There are a number of HTML FPIs, depending upon the version (also
 	known as the level) of HTML that you want to declare your document to
 	be compliant with.</para>
 
       <para>The majority of HTML documents on the FreeBSD web site comply with
 	the loose version of HTML 4.0.</para>
 
       <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
     </sect2>
 
     <sect2>
       <title>Sectional elements</title>
 
       <para>An HTML document is normally split in to two sections.  The first
 	section, called the <emphasis>head</emphasis>, contains
 	meta-information about the document, such as its title, the name of
 	the author, the parent document, and so on.  The second section, the
 	<emphasis>body</emphasis>, contains the content that will be displayed
 	to the user.</para>
 
       <para>These sections are indicated with <sgmltag>head</sgmltag> and
 	<sgmltag>body</sgmltag> elements respectively.  These elements are
 	contained within the top-level <sgmltag>html</sgmltag> element.</para>
 
       <example>
 	<title>Normal HTML document structure</title>
 
 	<programlisting>&lt;html>
   &lt;head>
 	  &lt;title><replaceable>The document's title</replaceable>&lt;/title>
   &lt;/head>
 
   &lt;body>
 
     &hellip;
 
   &lt;/body>
 &lt;/html></programlisting>
       </example>
     </sect2>
     
     <sect2>
       <title>Block elements</title>
 
       <sect3>
 	<title>Headings</title>
 
 	<para>HTML allows you to denote headings in your document, at up to
 	  six different levels.</para>
 
 	<para>The largest and most prominent heading is <sgmltag>h1</sgmltag>,
 	  then <sgmltag>h2</sgmltag>, continuing down to
 	  <sgmltag>h6</sgmltag>.</para>
 
 	<para>The element's content is the text of the heading.</para>
 
 	<example>
 	  <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<h1>First section</h1>
 
 <!-- Document introduction goes here -->
 
 <h2>This is the heading for the first section</h2>
 
 <!-- Content for the first section goes here -->
 
 <h3>This is the heading for the first sub-section</h3>
 
 <!-- Content for the first sub-section goes here -->
 
 <h2>This is the heading for the second section</h2>
 
 <!-- Content for the second section goes here -->]]></programlisting>	    
 	</example>
 	
 	<para>Generally, an HTML page should have one first level heading
 	  (<sgmltag>h1</sgmltag>).  This can contain many second level
 	  headings (<sgmltag>h2</sgmltag>), which can in turn contain many
 	  third level headings.  Each
 	  <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
-	  the same element, but one further up the hierarchy, preceeding it.
+	  the same element, but one further up the hierarchy, preceding it.
 	  Leaving gaps in the numbering is to be avoided.</para>
 
 	<example>
 	  <title>Bad ordering of
 	    <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<h1>First section</h1>
 
 <!-- Document introduction -->
 
 <h3>Sub-section</h3>
 
 <!-- This is bad, <h2> has been left out -->]]></programlisting>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Paragraphs</title>
 
 	<para>HTML supports a single paragraph element,
 	  <sgmltag>p</sgmltag>.</para>
 
 	<example>
 	  <title><sgmltag>p</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>This is a paragraph.  It can contain just about any
   other element.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Block quotations</title>
 
 	<para>A block quotation is an extended quotation from another document
 	  that should not appear within the current paragraph.</para>
 
 	<example>
 	  <title><sgmltag>blockquote</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>A small excerpt from the US Constitution:</p>
 
 <blockquote>We the People of the United States, in Order to form
   a more perfect Union, establish Justice, insure domestic
   Tranquility, provide for the common defence, promote the general
   Welfare, and secure the Blessings of Liberty to ourselves and our
   Posterity, do ordain and establish this Constitution for the
   United States of America.</blockquote>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Lists</title>
 
 	<para>You can present the user with three types of lists, ordered,
 	  unordered, and definition.</para>
 
 	<para>Typically, each entry in an ordered list will be numbered, while
 	  each entry in an unordered list will be preceded by a bullet point.
 	  Definition lists are composed of two sections for each entry.  The
 	  first section is the term being defined, and the second section is
 	  the definition of the term.</para>
 
 	<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
 	  element, unordered lists by the <sgmltag>ul</sgmltag> element, and
 	  definition lists by the <sgmltag>dl</sgmltag> element.</para>
 
 	<para>Ordered and unordered lists contain listitems, indicated by the
 	  <sgmltag>li</sgmltag> element.  A listitem can contain textual
 	  content, or it may be further wrapped in one or more
 	  <sgmltag>p</sgmltag> elements.</para>
 
 	<para>Definition lists contain definition terms
 	  (<sgmltag>dt</sgmltag>) and definition descriptions
 	  (<sgmltag>dd</sgmltag>).  A definition term can only contain inline
 	  elements.  A definition description can contain other block
 	  elements.</para>
 
 	<example>
 	  <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>An unordered list.  Listitems will probably be
-  preceeded by bullets.</p>
+  preceded by bullets.</p>
 
 <ul>
   <li>First item</li>
 
   <li>Second item</li>
 
   <li>Third item</li>
 </ul>
 
 <p>An ordered list, with list items consisting of multiple
   paragraphs.  Each item (note: not each paragraph) will be
   numbered.</p>
 
 <ol>
   <li><p>This is the first item.  It only has one paragraph.</p></li>
 
   <li><p>This is the first paragraph of the second item.</p>
 
     <p>This is the second paragraph of the second item.</p></li>
 
   <li><p>This is the first and only paragraph of the third
     item.</p></li>
 </ol>]]></programlisting>
 	</example>
 
 	<example>
 	  <title>Definition lists with <sgmltag>dl</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<dl>
   <dt>Term 1</dt>
 
   <dd><p>Paragraph 1 of definition 1.</p></dd>
 
     <p>Paragraph 2 of definition 1.</p></dd>
 
   <dt>Term 2</dt>
 
   <dd><p>Paragraph 1 of definition 2.</p></dd>
 
   <dt>Term 3</dt>
 
   <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
     element is not required in the single paragraph case.</dd>
 </dl>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Pre-formatted text</title>
 
 	<para>You can indicate that text should be shown to the user exactly
 	  as it is in the file.  Typically, this means that the text is shown
 	  in a fixed font, multiple spaces are not merged in to one, and line
 	  breaks in the text are significant.</para>
 
 	<para>In order to do this, wrap the content in the
 	  <sgmltag>pre</sgmltag> element.</para>
 
 	<example>
 	  <title><sgmltag>pre</sgmltag></title>
 
 	  <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
 	    message;</para>
 
 	  <programlisting><![ CDATA [<pre>  From: nik@FreeBSD.org
   To: freebsd-doc@FreeBSD.org
   Subject: New documentation available
 
   There's a new copy of my primer for contributers to the FreeBSD
   Documentation Project available at
 
     <URL:http://people.FreeBSD.org/~nik/primer/index.html>
 
   Comments appreciated.
 
   N</pre>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Tables</title>
 
 	<note>
 	  <para>Most text-mode browsers (such as Lynx) do not render tables
 	    particularly effectively.  If you are relying on the tabular
 	    display of your content, you should consider using alternative
 	    markup to prevent confusion.</para>
 	</note>
 
 	<para>Mark up tabular information using the <sgmltag>table</sgmltag>
 	  element.  A table consists of one or more table rows
 	  (<sgmltag>tr</sgmltag>), each containing one or more cells of table
 	  data (<sgmltag>td</sgmltag>).  Each cell can contain other block
 	  elements, such as paragraphs or lists.  It can also contain another
 	  table (this nesting can repeat indefinitely).  If the cell only
 	  contains one paragraph then you do not need to include the
 	  <sgmltag>p</sgmltag> element.</para>
 
 	<example>
 	  <title>Simple use of <sgmltag>table</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p>
 
 <table>
   <tr>
     <td>Top left cell</td>
 
     <td>Top right cell</td>
   </tr>
 
   <tr>
     <td>Bottom left cell</td>
 
     <td>Bottom right cell</td>
   </tr>
 </table>]]></programlisting></example>
 
 	<para>A cell can span multiple rows and columns.  To indicate this,
 	  add the <literal>rowspan</literal> and/or <literal>colspan</literal>
 	  attributes, with values indicating the number of rows of columns
 	  that should be spanned.</para>
 
 	<example>
 	  <title>Using <literal>rowspan</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to
   it on the right.</p>
 
 <table>
   <tr>
     <td rowspan="2">Long and thin</td>
   </tr>
 
   <tr>
     <td>Top cell</td>
 
     <td>Bottom cell</td>
   </tr>
 </table>]]></programlisting>
 	</example>
 
 	<example>
 	  <title>Using <literal>colspan</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p>
 
 <table>
   <tr>
     <td colspan="2">Top cell</td>
   </tr>
 
   <tr>
     <td>Bottom left cell</td>
 
     <td>Bottom right cell</td>
   </tr>
 </table>]]></programlisting>
 	</example>
 
 	<example>
 	  <title>Using <literal>rowspan</literal> and
 	    <literal>colspan</literal> together</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
   cells merged in to one.  The other cells are normal.</p>
 
 <table>
   <tr>
     <td colspan="2" rowspan="2">Top left large cell</td>
 
     <td>Top right cell</td>
   </tr>
 
   <tr>
     <!-- Because the large cell on the left merges in to
          this row, the first <td> will occur on its
          right -->
 	    
     <td>Middle right cell</td>
   </tr>
 
   <tr>
     <td>Bottom left cell</td>
 
     <td>Bottom middle cell</td>
 
     <td>Bottom right cell</td>
   </tr>
 </table>]]></programlisting>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>In-line elements</title>
 
       <sect3>
 	<title>Emphasising information</title>
 
 	<para>You have two levels of emphasis available in HTML,
 	  <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
 	  <sgmltag>em</sgmltag> is for a normal level of emphasis and
 	  <sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
 
 	<para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
 	  <sgmltag>strong</sgmltag> is rendered in bold.  This is not always
 	  the case, however, and you should not rely on it.</para>
 
 	<example>
 	  <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while
   <strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Bold and italics</title>
 
 	<para>Because HTML includes presentational markup, you can also
 	  indicate that particular content should be rendered in bold or
 	  italic.  The elements are <sgmltag>b</sgmltag> and
 	  <sgmltag>i</sgmltag> respectively.</para>
 
 	<example>
 	  <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
 
 	  <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
   in italics.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Indicating fixed pitch text</title>
 
 	<para>If you have content that should be rendered in a fixed pitch
 	  (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
 	  <quote>teletype</quote>).</para>
 
 	<example>
 	  <title><sgmltag>tt</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>This document was originally written by
   Nik Clayton, who can be reached by e-mail as
   <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Content size</title>
 
 	<para>You can indicate that content should be shown in a larger or
 	  smaller font.  There are three ways of doing this.</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag>
 	      around the content you wish to change size.  These tags can be
 	      nested, so <literal>&lt;big&gt;&lt;big&gt;This is much
 		bigger&lt;/big&gt;&lt;/big&gt;</literal> is possible.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
 	      attribute set to <literal>+1</literal> or <literal>-1</literal>
 	      respectively.  This has the same effect as using
 	      <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>.  However,
 	      the use of this approach is deprecated.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
 	      attribute set to a number between 1 and 7.  The default font size
 	      is <literal>3</literal>.  This approach is deprecated.</para>
 	  </listitem>
 	</orderedlist>
 
 	<example>
 	  <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
 	    <sgmltag>font</sgmltag></title>
 
 	  <para>The following fragments all do the same thing.</para>
 
 	  <programlisting><![ CDATA [<p>This text is <small>slightly smaller</small>.  But
   this text is <big>slightly bigger</big>.</p>
 
 <p>This text is <font size="-1">slightly smaller</font>.  But
   this text is <font size="+1">slightly bigger</font.</p>
 
 <p>This text is <font size="2">slightly smaller</font>.  But
   this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Links</title>
 
       <note>
 	<para>Links are also in-line elements.</para>
       </note>
 
       <sect3>
 	<title>Linking to other documents on the WWW</title>
 
 	<para>In order to include a link to another document on the WWW you
 	  must know the URL of the document you want to link to.</para>
 
 	<para>The link is indicated with <sgmltag>a</sgmltag>, and the
 	  <literal>href</literal> attribute contains the URL of the target
 	  document.  The content of the element becomes the link, and is
 	  normally indicated to the user in some way (underlining, change of
 	  colour, different mouse cursor when over the link, and so
 	  on).</para>
 
 	<example>
 	  <title>Using <literal>&lt;a href="..."&gt;</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>More information is available at the
   <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
 	</example>
 
 	<para>These links will take the user to the top of the chosen
 	  document.</para>
       </sect3>
       
       <sect3>
 	<title>Linking to other parts of documents</title>
 
 	<para>Linking to a point within another document (or within the same
 	  document) requires that the document author include anchors that you
 	  can link to.</para>
 
 	<para>Anchors are indicated with <sgmltag>a</sgmltag> and the
 	  <literal>name</literal> attribute instead of
 	  <literal>href</literal>.</para>
 
 	<example>
 	  <title>Using <literal>&lt;a name="..."&gt;</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
   in other links with the name <tt>para1</tt>.</p>]]></programlisting>
 	</example>
 
 	<para>To link to a named part of a document, write a normal link to
 	  that document, but include the name of the anchor after a
 	  <literal>#</literal> symbol.</para>
 
 	<example>
 	  <title>Linking to a named part of another document</title>
 
 	  <para>Assume that the <literal>para1</literal> example resides in a
 	    document called <filename>foo.html</filename>.</para>
 
 	  <programlisting><![ CDATA [<p>More information can be found in the
   <a href="foo.html#para1">first paragraph</a> of
   <tt>foo.html</tt>.</p>]]></programlisting>
 	</example>
 
 	<para>If you are linking to a named anchor within the same document
 	  then you can omit the document's URL, and just include the name of
-	  the anchor (with the preceeding <literal>#</literal>).</para>
+	  the anchor (with the preceding <literal>#</literal>).</para>
 
 	<example>
 	  <title>Linking to a named part of the same document</title>
 
 	  <para>Assume that the <literal>para1</literal> example resides in
 	    this document</para>
 
 	  <programlisting><![ CDATA [<p>More information can be found in the
   <a href="#para1">first paragraph</a> of this
   document.</p>]]></programlisting>
 	</example>
       </sect3>
     </sect2>
   </sect1>
   
   <sect1>
     <title>DocBook</title>
 
     <para>DocBook was designed by the <ulink
 	url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be
       a DTD for writing technical documentation.  As such, and unlike LinuxDoc
       and HTML, DocBook is very heavily oriented towards markup that
       describes <emphasis>what</emphasis> something is, rather than describing
       <emphasis>how</emphasis> it should be presented.</para>
 
     <note>
       <title><literal>formal</literal> vs. <literal>informal</literal></title>
 
       <para>Some elements may exist in two forms, <emphasis>formal</emphasis>
 	and <emphasis>informal</emphasis>.  Typically, the formal version of
 	the element will consist of a title followed by the information
 	version of the element.  The informal version will not have a
 	title.</para>
     </note>
     
     <para>The DocBook DTD is available from the ports collection in the
       <filename>textproc/docbook</filename> port.  It is automatically
       installed as part of the <filename>textproc/docproj</filename>
       port.</para>
     
     <sect2>
       <title>FreeBSD extensions</title>
 
       <para>The FreeBSD Documentation Project has extended the DocBook DTD by
 	adding some new elements.  These elements serve to make some of the
 	markup more precise.</para>
 
       <para>Where a FreeBSD specific element is listed below it is clearly
 	marked.</para>
 
       <para>Throughout the rest of this document, the term
 	<quote>DocBook</quote> is used to mean the FreeBSD extended DocBook
 	DTD.</para>
       
       <note>
 	<para>There is nothing about these extensions that is FreeBSD
 	  specific, it was just felt that they were useful enhancements for
 	  this particular project.  Should anyone from any of the other *nix
 	  camps (NetBSD, OpenBSD, Linux, &hellip;) be interested in
 	  collaborating on a standard DocBook extension set, please get in
 	  touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para>
       </note>
 
       <para>The FreeBSD extensions are not (currently) in the ports
 	collection.  They are stored in the FreeBSD CVS tree, as <ulink
 	url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Formal Public Identifier (FPI)</title>
 
       <para>In compliance with the DocBook guidelines for writing FPIs for
 	  DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
 	  is;</para>
 
 	<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
     </sect2>
 
     <sect2>
       <title>Document structure</title>
 
       <para>DocBook allows you to structure your documentation in several
 	ways.  In the FreeBSD Documentation Project we are using two primary
 	types of DocBook document: the book and the article.</para>
 
       <para>A book is organised into <sgmltag>chapter</sgmltag>s.  This is a
 	mandatory requirement.  There may be <sgmltag>part</sgmltag>s between
 	the book and the chapter to provide another layer of organisation.
 	The Handbook is arranged in this way.</para>
 
       <para>A chapter may (or may not) contain one or more sections.  These
 	are indicated with the <sgmltag>sect1</sgmltag> element.  If a section
 	contains another section then use the <sgmltag>sect2</sgmltag>
 	element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
 
       <para>Chapters and sections contain the remainder of the content.</para>
 
       <para>An article is simpler than a book, and does not use chapters.
 	Instead, the content of an article is organised 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>Obviously, you should consider the nature of the documentation you 
 	are writing in order to decide 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="../../../../docs.html">FreeBSD
 	  tutorials</ulink> are all marked up as articles, while this
 	document, the <ulink url="../faq/index.html">FreeBSD
 	  FAQ</ulink>, and the <ulink
 	  url="../handbook/index.html">FreeBSD Handbook</ulink> are
 	all marked up as books.</para>
 
       <sect3>
 	<title>Starting a book</title>
 
 	<para>The content of the book is contained within the
 	  <sgmltag>book</sgmltag> element.  As well as containing structural
 	  markup, this element can contain elements that include additional
 	  information about the book.  This is either meta-information, used
 	  for reference purposes, or additional content used to produce a
 	  title page.</para>
 
 	<para>This additional information should be contained within
 	  <sgmltag>bookinfo</sgmltag>.</para>
 
 	<example>
 	  <title>Boilerplate <sgmltag>book</sgmltag> with
 	    <sgmltag>bookinfo</sgmltag></title>
 
 	  <!-- Can't put this in a marked section because of the
                replaceable elements -->
 	  <programlisting>&lt;book>
   &lt;bookinfo>
     &lt;title><replaceable>Your title here</replaceable>&lt;/title>
     
     &lt;author>
       &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
       &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
       &lt;affiliation>
         &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
       &lt;/affiliation>
     &lt;/author>
 
     &lt;copyright>
       &lt;year><replaceable>1998</replaceable>&lt;/year>
       &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
     &lt;/copyright>
 
     &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
 
     &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
 
     &lt;abstract>
       &lt;para><replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para>
     &lt;/abstract>
   &lt;/bookinfo>
 
   &hellip;
 
 &lt;/book></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>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 should be contained within
 	  <sgmltag>articleinfo</sgmltag>.</para>
 
 	<example>
 	  <title>Boilerplate <sgmltag>article</sgmltag> with
 	    <sgmltag>articleinfo</sgmltag></title>
 
 	  <!-- Can't put this in a marked section because of the
                replaceable elements -->
 	  <programlisting>&lt;article>
   &lt;articleinfo>
     &lt;title><replaceable>Your title here</replaceable>&lt;/title>
     
     &lt;author>
       &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
       &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
       &lt;affiliation>
         &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
       &lt;/affiliation>
     &lt;/author>
 
     &lt;copyright>
       &lt;year><replaceable>1998</replaceable>&lt;/year>
       &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
     &lt;/copyright>
 
     &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
 
     &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
 
     &lt;abstract>
       &lt;para><replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para>
     &lt;/abstract>
   &lt;/articleinfo>
 
   &hellip;
 
 &lt;/article></programlisting>
 	</example>	
       </sect3>
       <sect3>
 	<title>Indicating chapters</title>
 
 	<para>Use <sgmltag>chapter</sgmltag> to mark up your chapters.  Each
 	  chapter has a mandatory <sgmltag>title</sgmltag>.  Articles do not
 	  contain chapters, they are reserved for books.</para>
 
 	<example>
 	  <title>A simple chapter</title>
 
 	  <programlisting><![ CDATA [<chapter>
   <title>The chapter's title</title>
 
   ...
 </chapter>]]></programlisting>
 	</example>
 
 	<para>A chapter cannot be empty; it must contain elements in addition
 	  to <sgmltag>title</sgmltag>.  If you need to include an empty
 	  chapter then just use an empty paragraph.</para>
 
 	<example>
 	  <title>Empty chapters</title>
 
 	  <programlisting><![ CDATA [<chapter>
   <title>This is an empty chapter</title>
 
   <para></para>
 </chapter>]]></programlisting>	    
 	</example>
       </sect3>
 
       <sect3>
 	<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><![ RCDATA [<chapter>
   <title>A sample chapter</title>
 
   <para>Some text in the chapter.</para>
 
   <sect1>
     <title>First section (1.1)</title>
 
     &hellip;
   </sect1>
 
   <sect1>
     <title>Second section (1.2)</title>
 
     <sect2>
       <title>First sub-section (1.2.1)</title>
 
       <sect3>
         <title>First sub-sub-section (1.2.1.1)</title>
 
         &hellip;
       </sect3>
     </sect2>
 
     <sect2>
       <title>Second sub-section (1.2.2)</title>
 
       &hellip;
     </sect2>
   </sect1>
 </chapter>]]></programlisting>
 	</example>
 	
 	<note>
 	  <para>This example includes section numbers in the section titles.
 	    You should not do this in your documents.  Adding the section
 	    numbers is carried out by the stylesheets (of which more
 	    later), and you do not need to manage them yourself.</para>
 	</note>
       </sect3>
       
       <sect3>
 	<title>Subdividing using <sgmltag>part</sgmltag>s</title>
 
 	<para>You can introduce another layer of organisation between
 	  <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
 	  more <sgmltag>part</sgmltag>s.  This cannot be done in an
 	  <sgmltag>article</sgmltag>.</para>
 
 	<programlisting><![ CDATA [<part>
   <title>Introduction</title>
 
   <chapter>
     <title>Overview</title>
 
     ...
   </chapter>
 
   <chapter>
     <title>What is FreeBSD?</title>
 
     ...
   </chapter>
 
   <chapter>
     <title>History</title>
 
     ...
   </chapter>
 </part>]]></programlisting>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Block elements</title>
       
       <sect3>
 	<title>Paragraphs</title>
 	
 	<para>DocBook supports three types of paragraphs:
 	  <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
 	  <sgmltag>simpara</sgmltag>.</para>
 	
 	<para>Most of the time you will only need to use
 	  <sgmltag>para</sgmltag>.  <sgmltag>formalpara</sgmltag> includes a
 	  <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag>
 	  disallows some elements from within <sgmltag>para</sgmltag>.  Stick
 	  with <sgmltag>para</sgmltag>.</para>
 	  
 	<example>
 	  <title><sgmltag>para</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>This is a paragraph.  It can contain just about any
   other element.</para> ]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>This is a paragraph.  It can contain just about any other
 	    element.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Block quotations</title>
 	
 	<para>A block quotation is an extended quotation from another document
 	  that should not appear within the current paragraph.  You will
 	  probably only need it infrequently.</para>
 	
 	<para>Blockquotes can optionally contain a title and an attribution
 	  (or they can be left untitled and unattributed).</para>
 
 	<example>
 	  <title><sgmltag>blockquote</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para>
 	      
 <blockquote>
   <title>Preamble to the Constitution of the United States</title>
 
   <attribution>Copied from a web site somewhere</attribution>
 	    
   <para>We the People of the United States, in Order to form a more perfect
     Union, establish Justice, insure domestic Tranquility, provide for the
     common defence, promote the general Welfare, and secure the Blessings
     of Liberty to ourselves and our Posterity, do ordain and establish this
     Constitution for the United States of America.</para>
 </blockquote>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <blockquote>
 	    <title>Preamble to the Constitution of the United States</title>
 	    
 	    <attribution>Copied from a web site somewhere</attribution>
 	    
 	    <para>We the People of the United States, in Order to form a more
 	      perfect Union, establish Justice, insure domestic Tranquility,
 	      provide for the common defence, promote the general Welfare, and
 	      secure the Blessings of Liberty to ourselves and our Posterity,
 	      do ordain and establish this Constitution for the United States
 	      of America.</para>
 	  </blockquote>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Tips, notes, warnings, cautions, important information and
 	  sidebars.</title>
 	  
 	<para>You may need to include extra information separate from the
 	  main body of the text.  Typically this is <quote>meta</quote>
 	  information that the user should be aware of.</para>
 	
 	<para>Depending on the nature of the information, one of
 	  <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
 	  <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
 	  <sgmltag>important</sgmltag> should be used.  Alternatively, if the
 	  information is related to the main text but is not one of the above,
 	  use <sgmltag>sidebar</sgmltag>.</para>
 
 	<para>The circumstances in which to choose one of these elements over
 	  another is unclear.  The DocBook documentation suggests;</para>
 	
 	<itemizedlist>
 	  <listitem>
 	    <para>A Note is for information that should be heeded by all
 	      readers.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>An Important element is a variation on Note.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>A Caution is for information regarding possible data loss
 	      or software damage.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>A Warning is for information regarding possible hardware
 	      damage or injury to life or limb.</para>
 	  </listitem>
 	</itemizedlist>
 	
 	<example>
 	  <title><sgmltag>warning</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<warning>
   <para>Installing FreeBSD may make you want to delete Windows from your
-    harddisk.</para>
+    hard disk.</para>
 </warning>]]></programlisting>
 	  </example>
 	  
 	<!-- Need to do this outside of the example -->
 	<warning>
 	  <para>Installing FreeBSD may make you want to delete Windows from
-	    your harddisk.</para>
+	    your hard disk.</para>
 	</warning>	  
       </sect3>
       
       <sect3>
 	<title>Lists and procedures</title>
 	
 	<para>You will often need to list pieces of information to the user,
 	  or present them with a number of steps that must be carried out in
 	  order to accomplish a particular goal.</para>
 	
 	<para>In order to do this, use <sgmltag>itemizedlist</sgmltag>,
 	  <sgmltag>orderedlist</sgmltag>, or
 	  <sgmltag>procedure</sgmltag><footnote><para>There are other types of
 	      list element in DocBook, but we're not concerned with those at
 	      the moment.</para>
 	  </footnote>
 	</para>
 	  
 	<para><sgmltag>itemizedlist</sgmltag> and
 	  <sgmltag>orderedlist</sgmltag> are similar to their counterparts in
 	  HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>.  Each one
 	  consists of one or more <sgmltag>listitem</sgmltag> elements, and
 	  each <sgmltag>listitem</sgmltag> contains one or more block
-	  elements.  The <sgmltag>listitem</sgmltag> elements are analagous to
+	  elements.  The <sgmltag>listitem</sgmltag> elements are analogous to
 	  HTML'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>Use:</para>
 	    
 	  <programlisting><![ CDATA [<itemizedlist>
   <listitem>
     <para>This is the first itemized item.</para>
   </listitem>
 
   <listitem>
     <para>This is the second itemized item.</para>
   </listitem>
 </itemizedlist>
 
 <orderedlist>
   <listitem>
     <para>This is the first ordered item.</para>
   </listitem>
 
   <listitem>
     <para>This is the second ordered item.</para>
   </listitem>
 </orderedlist>
 
 <procedure>
   <step>
     <para>Do this.</para>
   </step>
 
   <step>
     <para>Then do this.</para>
   </step>
 
   <step>
     <para>And now do this.</para>
   </step>
 </procedure>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	  
 	  <itemizedlist>
 	    <listitem>
 	      <para>This is the first itemized item.</para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para>This is the second itemized item.</para>
 	    </listitem>
 	  </itemizedlist>
 	  
 	  <orderedlist>
 	    <listitem>
 	      <para>This is the first ordered item.</para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para>This is the second ordered item.</para>
 	    </listitem>
 	  </orderedlist>
 	</example>
 
 	<!-- Can't have <procedure> inside <example>, so this is a cheat -->
 	
 	<procedure>
 	  <step>
 	    <para>Do this.</para>
 	  </step>
 	  
 	  <step>
 	    <para>Then do this.</para>
 	  </step>
 	  
 	  <step>
 	    <para>And now do this.</para>
 	  </step>
 	</procedure>	  
       </sect3>
       
       <sect3>
 	<title>Showing file samples</title>
 	
 	<para>If you want to show a fragment of a file (or perhaps a complete
 	  file) to the user, wrap it in the <sgmltag>programlisting</sgmltag>
 	  element.</para>
 	  
 	<para>White space and line breaks within
 	  <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
 	  significant.  In particular, this means that the 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>Use:</para>
 	    
 	  <programlisting><![ CDATA[<para>When you have finished, your program should look like
   this;</para>
 
 <programlisting>#include &lt;stdio.h&gt;
 
 int
 main(void)
 {
     printf("hello, world\n");
 }</programlisting>]]></programlisting>
 
 	  <para>Notice how the angle brackets in the
 	    <literal>#include</literal> line need to be referenced by their
 	    entities instead of being included literally.</para>
 	    
 	  <para>Appearance:</para>
 	    
 	  <para>When you have finished, your program should look like
 	    this;</para>
 	    
 	  <programlisting>#include &lt;stdio.h&gt;
 
 int
 main(void)
 {
     printf("hello, world\n");
 }</programlisting>	    
 	</example>
       </sect3>
 
       <sect3>
 	<title>Callouts</title>
 
 	<para>A callout is a mechanism for referring back to an earlier piece
 	  of text or specific position within an earlier example without
 	  linking to it within the text.</para>
 
 	<para>To do this, mark areas of interest in your example
 	  (<sgmltag>programlisting</sgmltag>,
 	  <sgmltag>literallayout</sgmltag>, or whatever) with the
 	  <sgmltag>co</sgmltag> element.  Each element must have a unique
 	  <literal>id</literal> assigned to it.  After the example include a
 	  <sgmltag>calloutlist</sgmltag> that refers back to the example and
 	  provides additional commentary.</para>
 	
 	<example>
 	  <title><sgmltag>co</sgmltag> and
 	    <sgmltag>calloutlist</sgmltag></title>
 
 	  <programlisting><![ CDATA[<para>When you have finished, your program should 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>]]></programlisting>
 
 	  <para>Appearance:</para>
 
 	  <para>When you have finished, your program should 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>
       </sect3>
       
       <sect3>
 	<title>Tables</title>
 	
 	<para>Unlike HTML, you do not need to use tables for layout purposes,
 	  as the stylesheet handles those issues for you.  Instead, just use
 	  tables for marking up tabular data.</para>
 
 	<para>In general terms (and see the DocBook documentation for more
 	  detail) a table (which can be either formal or informal) consists of
 	  a <sgmltag>table</sgmltag> element.  This contains at least one
 	  <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
 	  the number of columns in this table group.  Within the tablegroup
 	  you can then have one <sgmltag>thead</sgmltag> element, which
 	  contains elements for the table headings (column headings), and one
 	  <sgmltag>tbody</sgmltag> which contains the body of the
 	  table.</para>
 
 	<para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag>
 	  contain <sgmltag>row</sgmltag> elements, which in turn contain
 	  <sgmltag>entry</sgmltag> elements.  Each <sgmltag>entry</sgmltag>
 	  element specifies one cell in the table.</para>
 	  
 	<example>
 	  <title><sgmltag>informaltable</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<informaltable>
   <tgroup cols="2">
     <thead>
       <row>
         <entry>This is column head 1</entry>
         <entry>This is column head 2</entry>
       </row>
     </thead>
 
     <tbody>
       <row>
         <entry>Row 1, column 1</entry>
         <entry>Row 1, column 2</entry>
       </row>
 
       <row>
         <entry>Row 2, column 1</entry>
         <entry>Row 2, column 2</entry>
       </row>
     </tbody>
   </tgroup>
 </informaltable>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	  
 	  <informaltable>
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>This is column head 1</entry>
 		  <entry>This is column head 2</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>Row 1, column 1</entry>
 		  <entry>Row 1, column 2</entry>
 		</row>
 		
 		<row>
 		  <entry>Row 2, column 1</entry>
 		  <entry>Row 2, column 2</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 	</example>
 	
 	<para>If you don't want a border around the table the
 	  <literal>frame</literal> attribute can be added to the
 	  <sgmltag>informaltable</sgmltag> element with a value of
 	  <literal>none</literal> (i.e., <literal>&lt;informaltable
 	    frame="none"&gt;</literal>).</para>
 
 	<example>
 	  <title>Tables where <literal>frame="none"</literal></title>
 	  
 	  <para>Appearance:</para>
 	
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>This is column head 1</entry>
 		  <entry>This is column head 2</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>Row 1, column 1</entry>
 		  <entry>Row 1, column 2</entry>
 		</row>
 		
 		<row>
 		  <entry>Row 2, column 1</entry>
 		  <entry>Row 2, column 2</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Examples for the user to follow</title>
 	
 	<para>A lot of the time you need to show examples for the user to
 	  follow.  Typically, these will consist of dialogs with the computer;
 	  the user types in a command, the user gets a response back, they
 	  type in another command, and so on.</para>
 	  
 	<para>A number of distinct elements and entities come in to play
 	  here.</para>
 	
 	<variablelist>
 	  <varlistentry>
 	    <term><sgmltag>screen</sgmltag></term>
 	    
 	    <listitem>
 	      <para>Everything the user sees in this example will be on the
 		computer screen, so the next element is
 		<sgmltag>screen</sgmltag>.</para>
 		
 	      <para>Within <sgmltag>screen</sgmltag>, white space is
 		significant.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><sgmltag>prompt</sgmltag>,
 	      <literal>&amp;prompt.root;</literal> and
 	      <literal>&amp;prompt.user;</literal></term>
 	    
 	    <listitem>
 	      <para>Some of the things the user will be seeing on the screen
 		are prompts from the computer (either from the OS, command
 		shell, or application.  These should be marked up using
 		<sgmltag>prompt</sgmltag>.</para>
 
 	      <para>As a special case, the two shell prompts for the normal
 		user and the root user have been provided as entities.  Every
 		time you want to indicate the user is at a shell prompt, use
 		one of <literal>&amp;prompt.root;</literal> and
 		<literal>&amp;prompt.user;</literal> as necessary.  They do
 		not need to be inside <sgmltag>prompt</sgmltag>.</para>
 
 	      <note>
 		<para><literal>&amp;prompt.root;</literal> and
 		  <literal>&amp;prompt.user;</literal> are FreeBSD
 		  extensions to DocBook, and are not part of the original
 		  DTD.</para>
 	      </note>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><sgmltag>userinput</sgmltag></term>
 	    
 	    <listitem>
 	      <para>When displaying text that the user should type in, wrap it
 		in <sgmltag>userinput</sgmltag> tags.  It will probably be
 		displayed differently to the user.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 	  
 	<example>
 	  <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
 	    <sgmltag>userinput</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput>
 foo1
 foo2
 foo3
 &prompt.user; <userinput>ls -1 | grep foo2</userinput>
 foo2
 &prompt.user; <userinput>su</userinput>
 <prompt>Password: </prompt>
 &prompt.root; <userinput>cat foo2</userinput>
 This is the file called 'foo2'</screen>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	
 	  <screen>&prompt.user; <userinput>ls -1</userinput>
 foo1
 foo2
 foo3
 &prompt.user; <userinput>ls -1 | grep foo2</userinput>
 foo2
 &prompt.user; <userinput>su</userinput>
 <prompt>Password: </prompt>
 &prompt.root; <userinput>cat foo2</userinput>
 This is the file called 'foo2'</screen>
 	</example>
 	
 	<note>
 	  <para>Even though we are displaying the contents of the file
 	    <filename>foo2</filename>, it is <emphasis>not</emphasis> marked
 	    up as <sgmltag>programlisting</sgmltag>.  Reserve
 	    <sgmltag>programlisting</sgmltag> for showing fragments of files
 	    outside the context of user actions.</para>
 	</note>
       </sect3>
     </sect2>
     
     <sect2>
       <title>In-line elements</title>
       
       <sect3>
 	<title>Emphasising information</title>
 	
 	<para>When you want to emphasise a particular word or phrase, use
 	  <sgmltag>emphasis</sgmltag>.  This may be presented as italic, or
 	  bold, or might be spoken differently with a text-to-speech
 	  system.</para>
 	
 	<para>There is no way to change the presentation of the emphasis
 	  within your document, no equivalent of HTML's <sgmltag>b</sgmltag>
 	  and <sgmltag>i</sgmltag>.  If the information you are presenting is
 	  important then consider presenting it in
 	  <sgmltag>important</sgmltag> rather than
 	  <sgmltag>emphasis</sgmltag>.</para>
 	  
 	<example>
 	  <title><sgmltag>emphasis</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
   premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	
 	  <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix
 	    like operating system for the Intel architecture.</para>
 	</example>
       </sect3>
 
       <sect3>
 	<title>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>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>To switch to the second virtual terminal, press 
   <keycombo action="simul"><keycap>Alt</keycap>
     <keycap>F1</keycap></keycombo>.</para>
 
 <para>To exit <command>vi</command> without saving your work, type
   <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
     <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
 
 <para>My window manager is configured so that
   <keycombo action="simul"><keycap>Alt</keycap>
     <mousebutton>right</mousebutton>
   </keycombo> mouse button is used to move windows.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>To switch to the second virtual terminal, press 
 	    <keycombo action="simul"><keycap>Alt</keycap>
 	      <keycap>F1</keycap></keycombo>.</para>
 
 	  <para>To exit <command>vi</command> without saving your work, 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>
       </sect3>
       
       <sect3>
 	<title>Applications, commands, options, and cites</title>
 	
 	<para>You will frequently want to refer to both applications and
 	  commands when writing for the Handbook.  The distinction between
 	  them is simple: an application is the name for a suite (or possibly
 	  just 1) of programs that fulfil a particular task.  A command is the
 	  name of a program that the user can run.</para>
 
 	<para>In addition, you will occasionally need to list one or more of
 	  the options that a command might take.</para>
 	
 	<para>Finally, you will often want to list a command with 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>When you want 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="sgml-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/sgml/man-refs.ent</filename>, and can be
 	  referred to using this FPI:</para>
 
 	<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
 
 	<para>Therefore, the introduction to your documentation will probably
 	  look like this:</para>
 
 	<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook 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 you want 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 a command's
 	  options.</para>
 
 	<para>This can be confusing, and sometimes the choice is not always
 	  clear.  Hopefully this example makes it clearer.</para>
 
 	<example>
 	  <title>Applications, commands, and options.</title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para><application>Sendmail</application> is the most
   widely used Unix mail application.</para>
 
 <para><application>Sendmail</application> includes the
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, &man.mailq.8;, and &man.newaliases.8;
   programs.</para>
 
 <para>One of the command line parameters to <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, <option>-bp</option>, will display the current
   status of messages in the mail queue.  Check this on the command
   line by running <command>sendmail -bp</command>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para><application>Sendmail</application> is the most widely used
 	    Unix mail application.</para>
 	  
 	  <para><application>Sendmail</application> includes the
 	    <citerefentry>
 	      <refentrytitle>sendmail</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry>, <citerefentry>
 	      <refentrytitle>mailq</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry>, and <citerefentry>
 	      <refentrytitle>newaliases</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry> programs.</para>
 	  
 	  <para>One of the command line parameters to <citerefentry>
 	      <refentrytitle>sendmail</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry>, <option>-bp</option>, will display the current
 	    status of messages in the mail queue.  Check this on the command
 	    line by running <command>sendmail -bp</command>.</para>
 	</example>
 
 	<note>
 	  <para>Notice how the
 	    <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para>
 	</note>
       </sect3>
       
       <sect3>
 	<title>Files, directories, extensions</title>
 	
 	<para>Whenever you wish to refer to the name of a file, a directory,
 	  or a file extension, use <sgmltag>filename</sgmltag>.</para>
 	  
 	<example>
 	  <title><sgmltag>filename</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
   found in <filename>/usr/doc/en/handbook/</filename>.  The first
   file is called <filename>handbook.sgml</filename> in that
   directory.  You should also see a <filename>Makefile</filename>
   and a number of files with a <filename>.ent</filename>
   extension.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The SGML source for the Handbook in English can be found in
 	    <filename>/usr/doc/en/handbook/</filename>.  The first file is
 	    called <filename>handbook.sgml</filename> in that directory.  You
 	    should also see a <filename>Makefile</filename> and a number of
 	    files with a <filename>.ent</filename> extension.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Devices</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>When referring to devices you have two choices.  You can either
 	  refer to the device as it appears in <filename>/dev</filename>, or
 	  you can use the name of the device as it appears in the kernel.  For
 	  this latter course, use <sgmltag>devicename</sgmltag>.</para>
 	  
 	<para>Sometimes you will not have a choice.  Some devices, such as
 	  networking cards, do not have entries in <filename>/dev</filename>,
 	  or the entries are markedly different from those entries.</para>
 	  
 	<example>
 	  <title><sgmltag>devicename</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial
   communication in FreeBSD.  <devicename>sio</devicename> manifests
   through a number of entries in <filename>/dev</filename>, including
   <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
 
 <para>By contrast, the networking devices, such as
   <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.
 
 <para>In MS-DOS, the first floppy drive is referred to as
   <devicename>a:</devicename>.  In FreeBSD it is
   <filename>/dev/fd0</filename>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	    
 	  <para><devicename>sio</devicename> is used for serial communication
 	    in FreeBSD.  <devicename>sio</devicename> manifests through a
 	    number of entries in <filename>/dev</filename>, including
 	    <filename>/dev/ttyd0</filename> and
 	    <filename>/dev/cuaa0</filename>.</para>
 	  
 	  <para>By contrast, the networking devices, such as
 	    <devicename>ed0</devicename> do not appear in
 	    <filename>/dev</filename>.</para>
 	    
 	  <para>In MS-DOS, the first floppy drive is referred to as
 	    <devicename>a:</devicename>.  In FreeBSD it is
 	    <filename>/dev/fd0</filename>.</para>	  
 	</example>
       </sect3>
 	
       <sect3>
 	<title>Hosts, domains, IP addresses, and so forth</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>You can markup identification information for networked
 	  computers (hosts) in several ways, depending on the nature of the
 	  information.  All of them use <sgmltag>hostid</sgmltag> as the
 	  element, with the <literal>role</literal> attribute selecting the
 	  type of the marked up information.</para>
 	  
 	<variablelist>
 	  <varlistentry>
 	    <term>No role attribute, or
 	      <literal>role="hostname"</literal></term>
 	    
 	    <listitem>
 	      <para>With no role attribute (i.e.,
 		<sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the
 		marked up information is the simple hostname, such as
 		<literal>freefall</literal> or <literal>wcarchive</literal>.
 		You can explicitly specify this with
 		<literal>role="hostname"</literal>.</para>
 	    </listitem>
 	  </varlistentry>
 	    
 	  <varlistentry>
 	    <term><literal>role="domainname"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is a domain name, such as
 		<literal>FreeBSD.org</literal> or
 		<literal>ngo.org.uk</literal>.  There is no hostname
 		component.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><literal>role="fqdn"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is a Fully Qualified Domain Name, with both
 		hostname and domain name parts.</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>role="ipaddr"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is an IP address, probably expressed as a dotted
 		quad.</para>
 	    </listitem>
 	  </varlistentry>
 
           <varlistentry>
             <term><literal>role="ip6addr"</literal></term>
 
             <listitem>
               <para>The text is an IPv6 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.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><literal>role="mac"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is an Ethernet MAC address, expressed as a series
 		of 2 digit hexadecimal numbers separated by colons.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 	  
 	<example>
 	  <title><sgmltag>hostid</sgmltag> and roles</title>
 	    
 	  <para>Use:</para>
 	    
 	  <programlisting><![ CDATA [<para>The local machine can always be referred to by the
   name <hostid>localhost</hostid>, which will have the IP address
   <hostid role="ipaddr">127.0.0.1</hostid>.</para>
 
 <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
   contains a number of different hosts, including
   <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
   <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
 
 <para>When adding an IP alias to an interface (using
   <command>ifconfig</command>) <emphasis>always</emphasis> use a
   netmask of <hostid role="netmask">255.255.255.255</hostid>
   (which can also be expressed as <hostid
     role="netmask">0xffffffff</hostid>.</para>
 
 <para>The MAC address uniquely identifies every network card
   in existence.  A typical MAC address looks like <hostid
     role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The local machine can always be referred to by the name
 	    <hostid>localhost</hostid>, which will have the IP address <hostid
 	      role="ipaddr">127.0.0.1</hostid>.</para>
 
 	  <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
 	    contains a number of different hosts, including <hostid
 	      role="fqdn">freefall.FreeBSD.org</hostid> and <hostid
 	      role="fqdn">bento.FreeBSD.org</hostid>.</para>
 
 	  <para>When adding an IP alias to an interface (using
 	    <command>ifconfig</command>) <emphasis>always</emphasis> use a
 	    netmask of <hostid role="netmask">255.255.255.255</hostid> (which
 	    can also be expressed as <hostid
 	      role="netmask">0xffffffff</hostid>.</para>
 
 	  <para>The MAC address uniquely identifies every network card in
 	    existence.  A typical MAC address looks like <hostid
 	      role="mac">08:00:20:87:ef:d0</hostid>.</para>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Usernames</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>When you need to refer to a specific username, such as
 	  <literal>root</literal> or <literal>bin</literal>, use
 	  <sgmltag>username</sgmltag>.</para>
 	
 	<example>
 	  <title><sgmltag>username</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>To carry out most system administration functions you
   will need to be <username>root</username>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>To carry out most system administration functions you will
 	    need to be <username>root</username>.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Describing <filename>Makefile</filename>s</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>Two elements exist to describe parts of
 	  <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and
 	  <sgmltag>makevar</sgmltag>.</para>
 	  
 	<para><sgmltag>maketarget</sgmltag> identifies a build target exported
 	  by a <filename>Makefile</filename> that can be given as a parameter
 	  to <command>make</command>.  <sgmltag>makevar</sgmltag> identifies a
 	  variable that can be set (in the environment, on the
 	  <command>make</command> command line, or within the
 	  <filename>Makefile</filename>) to influence the process.</para>
 
 	<example>
 	  <title><sgmltag>maketarget</sgmltag> and
 	    <sgmltag>makevar</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename>
   are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
 
 <para>Typically, invoking <maketarget>all</maketarget> will rebuild the
   application, and invoking <maketarget>clean</maketarget> will remove
   the temporary files (<filename>.o</filename> for example) created by
   the build process.</para>
 
 <para><maketarget>clean</maketarget> may be controlled by a number of
   variables, including <makevar>CLOBBER</makevar> and
   <makevar>RECURSE</makevar>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>Two common targets in a <filename>Makefile</filename> are
 	    <maketarget>all</maketarget> and
 	    <maketarget>clean</maketarget>.</para>
 	    
 	  <para>Typically, invoking <maketarget>all</maketarget> will rebuild
 	    the application, and invoking <maketarget>clean</maketarget> will
 	    remove the temporary files (<filename>.o</filename> for example)
 	    created by the build process.</para>
 	    
 	  <para><maketarget>clean</maketarget> may be controlled by a number
 	    of variables, including <makevar>CLOBBER</makevar> and
 	    <makevar>RECURSE</makevar>.</para>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Literal text</title>
 	
 	<para>You will often need to include <quote>literal</quote> text in the
 	  Handbook.  This is text that is excerpted from another file, or
 	  which should be copied from the Handbook into another file
 	  verbatim.</para>
 
 	<para>Some of the time, <sgmltag>programlisting</sgmltag> will be
 	  sufficient to denote this text.  <sgmltag>programlisting</sgmltag>
 	  is not always appropriate, particularly when you want to include a
 	  portion of a file <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>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel
   configuration file determines the size of many system tables, and is
   a rough guide to how many simultaneous logins the system will
   support.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The <literal>maxusers 10</literal> line in the kernel
 	    configuration file determines the size of many system tables, and
 	    is a rough guide to how many simultaneous logins the system will
 	    support.</para>
 	</example>
       </sect3>
 	
       <sect3>
 	<title>Showing items that the user <emphasis>must</emphasis> fill
 	  in</title>
 	
 	<para>There will often be times when you want to show the user what to
 	  do, or refer to a file, or command line, or similar, where the user
 	  cannot simply copy the examples that you provide, but must instead
 	  include some information themselves.</para>
 	
 	<para><sgmltag>replaceable</sgmltag> is designed for this eventuality.
 	  Use it <emphasis>inside</emphasis> other elements to indicate parts
 	  of that element's content that the user must replace.</para>
 	
 	<example>
 	  <title><sgmltag>replaceable</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<informalexample>
   <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 </informalexample>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 	  </informalexample>
 	  
 	  <para><sgmltag>replaceable</sgmltag> can be used in many different
 	    elements, including <sgmltag>literal</sgmltag>.  This example also
 	    shows that <sgmltag>replaceable</sgmltag> should only be wrapped
 	    around the content that the user <emphasis>is</emphasis> meant to
 	    provide.  The other content should be left alone.</para>
 	    
 	  <para>Use:</para>
 	    
 	  <programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal>
   line in the kernel configuration file determines the size of many system
   tables, and is a rough guide to how many simultaneous logins the system will
   support.</para>
 
 <para>For a desktop workstation, <literal>32</literal> is a good value
   for <replaceable>n</replaceable>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The <literal>maxusers <replaceable>n</replaceable></literal>
 	    line in the kernel configuration file determines the size of many
 	    system tables, and is a rough guide to how many simultaneous
 	    logins the system will support.</para>
 
 	  <para>For a desktop workstation, <literal>32</literal> is a good
 	    value for <replaceable>n</replaceable>.</para>	  
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Images</title>
 
       <important>
 	<para>Image support in the documentation is currently extremely
 	  experimental.  I think the mechanisms described here are unlikely to
 	  change, but that's not guaranteed.</para>
 
 	<para>You will also need to install the
 	  <filename>graphics/ImageMagick</filename> port, which is used to
 	  convert between the different image formats.  This is a big port,
 	  and most of it is not required.  However, while we're working on the
 	  <filename>Makefile</filename>s and other infrastructure it makes
 	  things easier.  This port is <emphasis>not</emphasis> in the
 	  <filename>textproc/docproj</filename> meta port, you must install it
 	  by hand.</para>
 
 	<para>The best example of what follows in practice is the
 	  <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document.
 	  If you're unsure of the description that follows, take a look at the
-	  files in that directory to see how everything hangs togther.
+	  files in that directory to see how everything hangs together.
 	  Experiment with creating different formatted versions of the
 	  document to see how the image markup appears in the formatted
 	  output.</para>
       </important>
 
       <sect3>
 	<title>Image formats</title>
 
 	<para>We currently support two formats for images.  The format you
 	  should use will depend on the nature of your image.</para>
 
 	<para>For images that are primarily vector based, such as network
-	  diagrams, timelines, and similar, use Encapsulated Postscript, and
+	  diagrams, time lines, and similar, use Encapsulated Postscript, and
 	  make sure that your images have the <filename>.eps</filename>
 	  extension.</para>
 
 	<para>For bitmaps, such as screen captures, use the Portable Network
 	  Graphic format, and make sure that your images have the
 	  <filename>.png</filename> extension.</para>
 
 	<para>These are the <emphasis>only</emphasis> formats in which images
 	  should be committed to the CVS repository.</para>
 
 	<para>Use the right format for the right image.  It is to be expected
 	  that your documentation will have a mix of EPS and PNG images.  The
 	  <filename>Makefile</filename>s ensure that the correct format image
 	  is chosen depending on the output format that you use for your
 	  documentation.  <emphasis>Do not commit the same image to the
 	    repository in two different formats</emphasis>.</para>
 
 	<important>
 	  <para>It is anticipated that the Documentation Project will switch to
 	    using the Scalable Vector Graphic (SVG) format for vector images.
 	    However, the current state of SVG capable editing tools makes this
 	    impractical.</para>
 	</important>
       </sect3>
 
       <sect3>
 	<title>Markup</title>
 
 	<para>The markup for an image is relatively simple.  First, markup a
 	  <sgmltag>mediaobject</sgmltag>.  The <sgmltag>mediaobject</sgmltag>
 	  can contain other, more specific objects.  We are concerned with
 	  two, the <sgmltag>imageobject</sgmltag> and the
 	  <sgmltag>textobject</sgmltag>.</para>
 
 	<para>You should include one <sgmltag>imageobject</sgmltag>, and two
 	  <sgmltag>textobject</sgmltag> elements.  The
 	  <sgmltag>imageobject</sgmltag> will point to the name of the image
 	  file that will be used (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.</para>
 
 	<para>There are two circumstances where this can happen.</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>When the reader is viewing the documentation in HTML.  In
 	      this case, each image will need to have associated alternate
 	      text to show the user, typically whilst the image is loading, or
 	      if they hover the mouse pointer over the image.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>When the reader is viewing the documentation in plain text.
 	      In this case, each image should have an ASCII art equivalent to
 	      show the user.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>An example will probably make things easier to understand.
 	  Suppose you have an image, called <filename>fig1</filename>, that
 	  you want to include in the document.  This image is of a rectangle
 	  with an A inside it.  The markup for this would be as
 	  follows.</para>
 
 	<programlisting>&lt;mediaobject>
   &lt;imageobject>
     &lt;imagedata fileref="fig1"> <co id="co-image-ext">
   &lt;/imageobject>
 
   &lt;textobject>
     &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal">
 |       A       |
 +---------------+&lt;/literallayout>
   &lt;/textobject>
 
   &lt;textobject>
     &lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase">
   &lt;/textobject>
 &lt;/mediaobject></programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-image-ext">
 	    <para>Include an <sgmltag>imagedata</sgmltag> element inside the
 	      <sgmltag>imageobject</sgmltag> element.  The
 	      <literal>fileref</literal> attribute should contain the filename
 	      of the image to include, without the extension.  The stylesheets
 	      will work out which extension should be added to the filename
 	      automatically.</para>
 	  </callout>
 
 	  <callout arearefs="co-image-literal">
 	    <para>The first <sgmltag>textobject</sgmltag> should contain a
 	      <sgmltag>literallayout</sgmltag> element, where the
 	      <literal>class</literal> attribute is set to
 	      <literal>monospaced</literal>.  This is your opportunity to
 	      demonstrate your ASCII 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> should contain a
 	      single <sgmltag>phrase</sgmltag> element.  The contents of this
 	      will become the <literal>alt</literal> attribute for the image
 	      when this document is converted to HTML.</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3>
 	<title><filename>Makefile</filename> entries</title>
 
 	<para>Your images must be listed in the
 	  <filename>Makefile</filename> in the <makevar>IMAGES</makevar>
 	  variable.  This variable should contain the name of all your
 	  <emphasis>source</emphasis> images.  For example, if you have
 	  created three figures, <filename>fig1.eps</filename>,
 	  <filename>fig2.png</filename>, <filename>fig3.png</filename>, then
 	  your <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 your source document, you
 	  only need to list the image files <emphasis>you</emphasis>
 	  provided.</para>
       </sect3>
 
       <sect3>
 	<title>Images and chapters in subdirectories</title>
 
 	<para>You must be careful when you separate your documentation in to
 	  smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in
 	  different directories.</para>
 	  
 	<para>Suppose you have a book with three chapters, and the chapters
 	  are stored in their own directories, called
 	  <filename>chapter1/chapter.sgml</filename>,
 	  <filename>chapter2/chapter.sgml</filename>, and
 	  <filename>chapter3/chapter.sgml</filename>.  If each chapter has
 	  images associated with it, I suggest you place those images in each
 	  chapter's subdirectory (<filename>chapter1/</filename>,
 	  <filename>chapter2/</filename>, and
 	  <filename>chapter3/</filename>).</para>
 
 	<para>However, if you do this you must include the directory names in
 	  the <makevar>IMAGES</makevar> variable in the
 	  <filename>Makefile</filename>, <emphasis>and</emphasis> you must
 	  include the directory name in the <sgmltag>imagedata</sgmltag>
 	  element in your document.</para>
 
 	<para>For example, if you have <filename>chapter1/fig1.png</filename>,
 	  then <filename>chapter1/chapter.sgml</filename> should
 	  contain</para>
 
 	<programlisting>&lt;mediaobject>
   &lt;imageobject>
     &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir">
   &lt;/imageobject>
 
   &hellip;
 
 &lt;/mediaobject></programlisting>
 	
 	<calloutlist>
 	  <callout arearefs="co-image-dir">
 	    <para>The directory name must be included in the
 	      <literal>fileref</literal> attribute</para>
 	  </callout>
 	</calloutlist>
 
 	<para>The <filename>Makefile</filename> must contain</para>
 
 	<programlisting>&hellip;
 IMAGES=  chapter1/fig1.png
 &hellip;</programlisting>
 
 	<para>Then everything should just work.</para>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Links</title>
 
       <note>
 	<para>Links are also in-line elements.</para>
       </note>
 
       <sect3>
 	<title>Linking to other parts of the same document</title>
 
 	<para>Linking within the same document requires you to specify
 	  where you are linking from (i.e., the text the user will click, or
 	  otherwise indicate, as the source of the link) and where you are
 	  linking to (the link's destination).</para>
 
 	<para>Each element within DocBook has an attribute called
 	  <literal>id</literal>.  You can place text in this attribute to
 	  uniquely name the element it is attached to.</para>
 
 	  <para>This value will be used when you specify the link
 	  source.</para>
 
 	<para>Normally, you will only be linking to chapters or sections, so
 	  you would add the <literal>id</literal> attribute to these
 	  elements.</para>
 
 	<example>
 	  <title><literal>id on chapters and sections</literal></title>
 
 	  <programlisting><![ CDATA [<chapter id="chapter1">
   <title>Introduction</title>
 
   <para>This is the introduction.  It contains a subsection,
     which is identified as well.</para>
 
   <sect1 id="chapter1-sect1">
     <title>Sub-sect 1</title>
 
     <para>This is the subsection.</para>
   </sect1>
 </chapter>]]></programlisting>
 	</example>
 	
 	<para>Obviously, you should use more descriptive values.  The values
 	  must be unique within the document (i.e., not just the file, but the
 	  document the file might be included in as well).  Notice how the
 	  <literal>id</literal> for the subsection is constructed by appending
 	  text to the <literal>id</literal> of the chapter.  This helps to
 	  ensure that they are unique.</para>
 
 	<para>If you want to allow the user to jump into a specific portion of
 	  the document (possibly in the middle of a paragraph or an example),
 	  use <sgmltag>anchor</sgmltag>.  This element has no content, but
 	  takes an <literal>id</literal> attribute.</para>
 
 	<example>
 	  <title><sgmltag>anchor</sgmltag></title>
 
 	  <programlisting><![ CDATA [<para>This paragraph has an embedded
   <anchor id="para1">link target in it.  It won't show up in
   the document.</para>]]></programlisting>
 	</example>
 	
 	<para>When you want to provide the user with a link they can activate
 	  (probably by clicking) to go to a section of the document that has
 	  an <literal>id</literal> attribute, you can use either
 	  <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para>
 
 	<para>Both of these elements have a <literal>linkend</literal>
 	  attribute.  The value of this attribute should be the value that you
 	  have used in a <literal>id</literal> attribute (it does not matter
 	  if that value has not yet occurred in your document; this will work
 	  for forward links as well as backward links).</para>
 	
 	<para>If you use <sgmltag>xref</sgmltag> then you have no control over
 	  the text of the link.  It will be generated for you.</para>
 	
 	<example>
 	  <title>Using <sgmltag>xref</sgmltag></title>
 
 	  <para>Assume that this fragment appears somewhere in a document that
 	    includes the <literal>id</literal> example;</para>
 	  
 	  <programlisting><![ CDATA [<para>More information can be found
   in <xref linkend="chapter1">.</para>
 
 <para>More specific information can be found
   in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
 
 	  <para>The text of the link will be generated automatically, and will
 	    look like (<emphasis>emphasised</emphasis> text indicates the text
 	    that will be the link);</para>
 
 	  <blockquote>
 	    <para>More information can be found in <emphasis>Chapter
 		One</emphasis>.</para>
 
 	    <para>More specific information can be found in <emphasis>the
 		section called Sub-sect 1</emphasis>.</para>
 	  </blockquote>
 	</example>
 	
 	<para>Notice how the text from the link is derived from the section
 	  title or the chapter number.</para>
 
 	<note>
 	  <para>This means that you <emphasis>cannot</emphasis> use
 	    <sgmltag>xref</sgmltag> to link to an <literal>id</literal>
 	    attribute on an <sgmltag>anchor</sgmltag> element.  The
 	    <sgmltag>anchor</sgmltag> has no content, so the
 	    <sgmltag>xref</sgmltag> cannot generate the text for the
 	    link.</para>
 	</note>
 	
 	<para>If you want to control the text of the link then use
 	  <sgmltag>link</sgmltag>.  This element wraps content, and the
 	  content will be used for the link.</para>
 
 	<example>
 	  <title>Using <sgmltag>link</sgmltag></title>
 
 	  <para>Assume that this fragment appears somewhere in a document that
 	    includes the <literal>id</literal> example.</para>
 
 	  <programlisting><![ CDATA [<para>More information can be found in
   <link linkend="chapter1">the first chapter</link>.</para>
 
 <para>More specific information can be found in
   <link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting>
 	  
 	  <para>This will generate the following
 	    (<emphasis>emphasised</emphasis> text indicates the text that will
 	    be the link);</para>
 	  
 	  <blockquote>
 	    <para>More information can be found in <emphasis>the first
 		chapter</emphasis>.</para>
 	    
 	    <para>More specific information can be found in
 	      <emphasis>this</emphasis> section.</para>
 	  </blockquote>
 	</example>
 	
 	<note>
 	  <para>That last one is a bad example.  Never use words like
 	    <quote>this</quote> or <quote>here</quote> as the source for the
 	    link.  The reader will need to hunt around the surrounding context
 	    to see where the link is actually taking them.</para>
 	</note>
 
 	<note>
 	  <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to
 	    include a link to an <literal>id</literal> on an
 	    <sgmltag>anchor</sgmltag> element, since the
 	    <sgmltag>link</sgmltag> content defines the text that will be used
 	    for the link.</para>
 	</note>
       </sect3>
 
       <sect3>
 	<title>Linking to documents on the WWW</title>
 
 	<para>Linking to external documents is much simpler, as long as you
 	  know the URL of the document you want to link to.  Use
 	  <sgmltag>ulink</sgmltag>.  The <literal>url</literal> attribute is
 	  the URL of the page that the link points to, and the content of the
 	  element is the text that will be displayed for the user to
 	  activate.</para>
 
 	<example>
 	  <title><sgmltag>ulink</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<para>Of course, you could stop reading this document and
   go to the <ulink url="../../../../index.html">FreeBSD
   home page</ulink> instead.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 
 	  <para>Of course, you could stop reading this document and go to the
 	    <ulink url="../../../../index.html">FreeBSD home page</ulink>
 	    instead.</para>
 	</example>
       </sect3>
     </sect2>
   </sect1>
 </chapter>
 
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
index cdac8cd636..18add92569 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
@@ -1,1556 +1,1556 @@
 <!-- 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: doc/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml,v 1.20 2001/10/02 05:28:56 murray Exp $
+     $FreeBSD$
 -->
 
 <chapter id="sgml-primer">
   <title>SGML Primer</title>
 
   <para>The majority of FDP documentation is written in applications of
     SGML.  This chapter explains exactly what that means, how to read
     and understand the source to the documentation, and the sort of SGML
     tricks you will see used in the documentation.</para>
 
   <para>Portions of this section were inspired by Mark Galassi's <ulink
       url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para>
   
   <sect1>
     <title>Overview</title>
 
     <para>Way back when, electronic text was simple to deal with.  Admittedly, 
       you had to know which character set your document was written in (ASCII, 
       EBCDIC, or one of a number of others) but that was about it.  Text was
       text, and what you saw really was what you got.  No frills, no
       formatting, no intelligence.</para>
 
     <para>Inevitably, this was not enough.  Once you have text in a
       machine-usable format, you expect machines to be able to use it and
       manipulate it intelligently.  You would like to indicate that certain
       phrases should be emphasised, or added to a glossary, or be hyperlinks.
       You might want filenames to be shown in a <quote>typewriter</quote> style 
       font for viewing on screen, but as <quote>italics</quote> when printed,
       or any of a myriad of other options for presentation.</para>
 
     <para>It was once hoped that Artificial Intelligence (AI) would make this
       easy.  Your computer would read in the document and automatically
       identify key phrases, filenames, text that the reader should type in,
       examples, and more.  Unfortunately, real life has not happened quite
       like that, and our computers require some assistance before they can
       meaningfully process our text.</para>
 
     <para>More precisely, they need help identifying what is what.  You or I
       can look at
 
       <blockquote>
 	<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 	<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
       </blockquote>
 
       and easily see which parts are filenames, which are commands to be typed
       in, which parts are references to manual pages, and so on.  But the
       computer processing the document cannot.  For this we need
       markup.</para>
     
     <para><quote>Markup</quote> is commonly used to describe <quote>adding
       value</quote> or <quote>increasing cost</quote>.  The term takes on both
       these meanings when applied to text.  Markup is additional text included 
       in the document, distinguished from the document's content in some way,
       so that programs that process the document can read the markup and use
       it when making decisions about the document.  Editors can hide the
       markup from the user, so the user is not distracted by it.</para>
 
     <para>The extra information stored in the markup <emphasis>adds
       value</emphasis> to the document.  Adding the markup to the document
       must typically be done by a person&mdash;after all, if computers could
       recognise the text sufficiently well to add the markup then there would
       be no need to add it in the first place.  This <emphasis>increases the
       cost</emphasis> (i.e., the effort required) to create the
       document.</para>
 
     <para>The previous example is actually represented in this document like
       this;</para>
 
     <programlisting><![ CDATA [
 <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>
 
     <para>As you can see, the markup is clearly separate from the
       content.</para>
 
     <para>Obviously, if you are going to use markup you need to define what
       your markup means, and how it should be interpreted.  You will need a
       markup language that you can follow when marking up your
       documents.</para>
     
    <para>Of course, one markup language might not be enough.  A markup
       language for technical documentation has very different requirements
       than a markup language that was to be used for cookery recipes.  This,
       in turn, would be very different from a markup language used to describe
       poetry.  What you really need is a first language that you use to write
       these other markup languages.  A <emphasis>meta markup
       language</emphasis>.</para>
     
     <para>This is exactly what the Standard Generalised Markup Language (SGML)
       is.  Many markup languages have been written in SGML, including the two
       most used by the FDP, HTML and DocBook.</para>
     
     <para>Each language definition is more properly called a Document Type
       Definition (DTD).  The DTD specifies the name of the elements that can
       be used, what order they appear in (and whether some markup can be used
       inside other markup) and related information.  A DTD is sometimes
       referred to as an <emphasis>application</emphasis> of SGML.</para>
 
     <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis>
       specification of all the elements that are allowed to appear, the order
       in which they should appear, which elements are mandatory, which are
       optional, and so forth. This makes it possible to write an SGML
       <emphasis>parser</emphasis> which reads in both the DTD and a document
       which claims to conform to the DTD.  The parser can then confirm whether
       or not all the elements required by the DTD are in the document in the
       right order, and whether there are any errors in the markup.  This is
       normally referred to as <quote>validating  the document</quote>.</para>
 
     <note>
       <para>This processing simply confirms that the choice of elements, their 
 	ordering, and so on, conforms to that listed in the DTD.  It does
 	<emphasis>not</emphasis> check that you have used
 	<emphasis>appropriate</emphasis> markup for the content.  If you were
 	to try and mark up all the filenames in your document as function
 	names, the parser would not flag this as an error (assuming, of
 	course, that your DTD defines elements for filenames and functions,
 	and that they are allowed to appear in the same place).</para>
     </note>
     
     <para>It is likely that most of your contributions to the Documentation
       Project will consist of content marked up in either HTML or DocBook,
       rather than alterations to the DTDs.  For this reason this book will
       not touch on how to write a DTD.</para>
   </sect1>
   
   <sect1 id="sgml-primer-elements">
     <title>Elements, tags, and attributes</title>
 
     <para>All the DTDs written in SGML share certain characteristics.  This is
       hardly surprising, as the philosophy behind SGML will inevitably show
-      through. One of the most obvious manifestations of this philisophy is
+      through. One of the most obvious manifestations of this philosophy is
       that of <emphasis>content</emphasis> and
       <emphasis>elements</emphasis>.</para>
 
     <para>Your documentation (whether it is a single web page, or a lengthy
       book) is considered to consist of content.  This content is then divided
       (and further subdivided) into elements.  The purpose of adding markup is
       to name and identify the boundaries of these elements for further
       processing.</para>
 
     <para>For example, consider a typical book.  At the very top level, the
       book is itself an element.  This <quote>book</quote> element obviously
       contains chapters, which can be considered to be elements in their own
       right.  Each chapter will contain more elements, such as paragraphs,
       quotations, and footnotes.  Each paragraph might contain further
       elements, identifying content that was direct speech, or the name of a
       character in the story.</para>
 
     <para>You might like to think of this as <quote>chunking</quote> content.
       At the very top level you have one chunk, the book.  Look a little
       deeper, and you have more chunks, the individual chapters.  These are
       chunked further into paragraphs, footnotes, character names, and so
       on.</para>
 
-    <para>Notice how you can make this differentation between different
+    <para>Notice how you can make this differentiation between different
       elements of the content without resorting to any SGML terms.  It really
       is surprisingly straightforward.  You could do this with a highlighter
       pen and a printout of the book, using different colours to indicate
       different chunks of content.</para>
 
     <para>Of course, we do not have an electronic highlighter pen, so we need
       some other way of indicating which element each piece of content belongs
       to.  In languages written in SGML (HTML, DocBook, et al) this is done by
       means of <emphasis>tags</emphasis>.</para>
 
     <para>A tag is used to identify where a particular element starts, and
       where the element ends.  <emphasis>The tag is not part of the element
       itself</emphasis>. Because each DTD was normally written to mark up
       specific types of information, each one will recognise different
       elements, and will therefore have different names for the tags.</para>
 
     <para>For an element called <replaceable>element-name</replaceable> the
       start tag will normally look like
       <literal>&lt;<replaceable>element-name</replaceable>&gt;</literal>.  The
       corresponding closing tag for this element is
       <literal>&lt;/<replaceable>element-name</replaceable>&gt;</literal>.</para>
 
     <example>
       <title>Using an element (start and end tags)</title>
 
       <para>HTML has an element for indicating that the content enclosed by
 	the element is a paragraph, called <literal>p</literal>.  This
 	element has both start and end tags.</para>
       
       <programlisting><![ CDATA [<p>This is a paragraph.  It starts with the start tag for
   the 'p' element, and it will end with the end tag for the 'p'
   element.</p>
 
 <p>This is another paragraph.  But this one is much shorter.</p>]]></programlisting>	  
     </example>
 
     <para>Not all elements require an end tag.  Some elements have no content.
       For example, in HTML you can indicate that you want a horizontal line to
       appear in the document.  Obviously, this line has no content, so just
       the start tag is required for this element.</para>
 
     <example>
       <title>Using an element (start tag only)</title>
 
       <para>HTML has an element for indicating a horizontal rule, called
 	<literal>hr</literal>.  This element does not wrap content, so only
 	has a start tag.</para>
 
       <programlisting><![ CDATA [<p>This is a paragraph.</p>
 
 <hr>
 
 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>]]></programlisting>
     </example>
     
     <para>If it is not obvious by now, elements can contain other elements.
       In the book example earlier, the book element contained all the chapter
       elements, which in turn contained all the paragraph elements, and so
       on.</para>
 
     <example>
       <title>Elements within elements; <sgmltag>em</sgmltag></title>
       
       <programlisting><![ CDATA [<p>This is a simple <em>paragraph</em> where some
   of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting>
     </example>
     
     <para>The DTD will specify the rules detailing which elements can contain
       other elements, and exactly what they can contain.</para>
 
     <important>
       <para>People often confuse the terms tags and elements, and use the
 	terms as if they were interchangeable.  They are not.</para>
 
       <para>An element is a conceptual part of your document.  An element has
 	a defined start and end.  The tags mark where the element starts and
 	end.</para>
 
-      <para>When this document (or anyone else knowledgable about SGML) refers
+      <para>When this document (or anyone else knowledgeable about SGML) refers
 	to <quote>the &lt;p&gt; tag</quote> they mean the literal text
 	consisting of the three characters <literal>&lt;</literal>,
 	<literal>p</literal>, and <literal>&gt;</literal>.  But the phrase
 	<quote>the &lt;p&gt; element</quote> refers to the whole
 	element.</para>
 
       <para>This distinction <emphasis>is</emphasis> very subtle.  But keep it 
 	in mind.</para>
     </important>
       
     <para>Elements can have attributes.  An attribute has a name and a value,
       and is used for adding extra information to the element.  This might be
       information that indicates how the content should be rendered, or might
-      be something that uniquely identifies that occurence of the element, or
+      be something that uniquely identifies that occurrence of the element, or
       it might be something else.</para>
 
     <para>An element's attributes are written <emphasis>inside</emphasis> the
       start tag for that element, and take the form
       <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
 
     <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag>
       element has an attribute called <literal>align</literal>, which suggests
       an alignment (justification) for the paragraph to the program displaying
       the HTML.</para>
 
     <para>The <literal>align</literal> attribute can take one of four defined
       values, <literal>left</literal>, <literal>center</literal>,
       <literal>right</literal> and <literal>justify</literal>.  If the
       attribute is not specified then the default is
       <literal>left</literal>.</para>
 
     <example>
       <title>Using an element with an attribute</title>
       
       <programlisting><![ CDATA [<p align="left">The inclusion of the align attribute
   on this paragraph was superfluous, since the default is left.</p>
 
 <p align="center">This may appear in the center.</p>]]></programlisting>
     </example>
     
     <para>Some attributes will only take specific values, such as
       <literal>left</literal> or <literal>justify</literal>.  Others will
       allow you to enter anything you want.  If you need to include quotes
       (<literal>"</literal>) within an attribute then use single quotes around
       the attribute value.</para>
 
     <example>
       <title>Single quotes around attributes</title>
       
       <programlisting><![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting>
     </example>
 
     <para>Sometimes you do not need to use quotes around attribute values at
       all.  However, the rules for doing this are subtle, and it is far
       simpler just to <emphasis>always</emphasis> quote your attribute
       values.</para>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <para>In order to run the examples in this document you will need to
         install some software on your system and ensure that an environment
         variable is set correctly.</para>
     
       <procedure>
 	<step>
 	  <para>Download and install <filename>textproc/docproj</filename>
 	    from the FreeBSD ports system.  This is a
             <emphasis>meta-port</emphasis> that should download and install
             all of the programs and supporting files that are used by the
             Documentation Project.</para>
 	</step>
 	
         <step>
           <para>Add lines to your shell startup files to set
             <envar>SGML_CATALOG_FILES</envar>.</para>
     
 	  <example id="sgml-primer-envars">
 	    <title><filename>.profile</filename>, for &man.sh.1; and
 	      &man.bash.1; users</title>
 	    
 	    <programlisting>SGML_ROOT=/usr/local/share/sgml	    
 SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
 SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 export SGML_CATALOG_FILES</programlisting>
 	  </example>
 
 	  <example>
 	    <title><filename>.login</filename>, for &man.csh.1; and
 	      &man.tcsh.1; users</title>
 	    
 	    <programlisting>setenv SGML_ROOT /usr/local/share/sgml
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES</programlisting>
           </example>
     
           <para>Then either log out, and log back in again, or run those
             commands from the command line to set the variable values.</para>
 	</step>
       </procedure>
     
       <procedure>
 	<step>
 	  <para>Create <filename>example.sgml</filename>, and enter the
             following text;</para>
 
 	  <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
 <html>
   <head>	     
     <title>An example HTML file</title>
   </head>
 
   <body>	    
     <p>This is a paragraph containing some text.</p>
 
     <p>This paragraph contains some more text.</p>
 
     <p align="right">This paragraph might be right-justified.</p>
   </body>	    
 </html>]]></programlisting>
 	</step>
 
 	<step>
 	  <para>Try and validate this file using an SGML parser.</para>
 
 	  <para>Part of <filename>textproc/docproj</filename> is the
 	    &man.nsgmls.1; <link linkend="sgml-primer-validating">validating
 	    parser</link>.  Normally, &man.nsgmls.1; reads in a document
 	    marked up according to an SGML DTD and returns a copy of the
 	    document's Element Structure Information Set (ESIS, but that is
 	    not important right now).</para>
 
 	  <para>However, when &man.nsgmls.1; is given the <option>-s</option>
 	    parameter, &man.nsgmls.1; will suppress its normal output, and
 	    just print error messages.  This makes it a useful way to check to
 	    see if your document is valid or not.</para>
 
 	  <para>Use &man.nsgmls.1; to check that your document is
 	    valid;</para>
 
           <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen>
 
 	  <para>As you will see, &man.nsgmls.1; returns without displaying any
 	    output.  This means that your document validated
 	    successfully.</para>
 	</step>
 
 	<step>
 	  <para>See what happens when required elements are omitted.  Try
 	    removing the <sgmltag>title</sgmltag> and
 	    <sgmltag>/title</sgmltag> tags, and re-run the validation.</para>
 
           <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
 nsgmls:example.sgml:5:4:E: character data is not allowed here
 nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 
 	  <para>The error output from &man.nsgmls.1; is organised into
 	    colon-separated groups, or columns.</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>Column</entry>
 		  <entry>Meaning</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>1</entry>
 		  <entry>The name of the program generating the error.  This
 		    will always be <literal>nsgmls</literal>.</entry>
 		</row>
 
 		<row>
 		  <entry>2</entry>
 		  <entry>The name of the file that contains the error.</entry>
 		</row>
 
 		<row>
 		  <entry>3</entry>
 		  <entry>Line number where the error appears.</entry>
 		</row>
 
 		<row>
 		  <entry>4</entry>
 		  <entry>Column number where the error appears.</entry>
 		</row>
 
 		<row>
 		  <entry>5</entry>
 		  <entry>A one letter code indicating the nature of the
 		    message.  <literal>I</literal> indicates an informational
 		    message, <literal>W</literal> is for warnings, and
 		    <literal>E</literal> is for errors<footnote>
 		      <para>It is not always the fifth column either.
 			<command>nsgmls -sv</command> displays
 			<literal>nsgmls:I: SP version "1.3"</literal>
 			(depending on the installed version).  As you can see,
 			this is an informational message.</para>
 		    </footnote>, and <literal>X</literal> is for
 		    cross-references.  As you can see, these messages are
 		    errors.</entry>
 		</row>
 
 		<row>
 		  <entry>6</entry>
 		  <entry>The text of the error message.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 
 	  <para>Simply omitting the <sgmltag>title</sgmltag> tags has
 	    generated 2 different errors.</para>
 
 	  <para>The first error indicates that content (in this case,
-	    characters, rather than the start tag for an element) has occured
+	    characters, rather than the start tag for an element) has occurred
 	    where the SGML parser was expecting something else.  In this case,
 	    the parser was expecting to see one of the start tags for elements
 	    that are valid inside <sgmltag>head</sgmltag> (such as
 	    <sgmltag>title</sgmltag>).</para>
 
 	  <para>The second error is because <sgmltag>head</sgmltag> elements
 	    <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag>
 	    element.  Because it does not &man.nsgmls.1; considers that the
 	    element has not been properly finished.  However, the closing tag
 	    indicates that the element has been closed before it has been
 	    finished.</para>
 	</step>
 
 	<step>
 	  <para>Put the <literal>title</literal> element back in.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
 
   <sect1 id="sgml-primer-doctype-declaration">
     <title>The DOCTYPE declaration</title>
 
     <para>The beginning of each document that you write must specify the name
       of the DTD that the document conforms to.  This is so that SGML parsers
       can determine the DTD and ensure that the document does conform to 
       it.</para>
 
     <para>This information is generally expressed on one line, in the DOCTYPE
       declaration.</para>
 
     <para>A typical declaration for a document written to conform with version
       4.0 of the HTML DTD looks like this;</para>
 
     <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>
 
     <para>That line contains a number of different components.</para>
 
     <variablelist>
       <varlistentry>
 	<term><literal>&lt;!</literal></term>
 	
 	<listitem>
 	  <para>Is the <emphasis>indicator</emphasis> that indicates that this
 	    is an SGML declaration.  This line is declaring the document type.
 	  </para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>DOCTYPE</literal></term>
 	
 	<listitem>
 	  <para>Shows that this is an SGML declaration for the document
 	    type.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term><literal>html</literal></term>
 	
 	<listitem>
 	  <para>Names the first <link linkend="sgml-primer-elements">element</link> that
 	    will appear in the document.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term>
 
 	<listitem>
 	  <para>Lists the Formal Public Identifier (FPI)<indexterm>
 	      <primary>Formal Public Identifier</primary>
 	    </indexterm>
 	    for the DTD that this
 	    document conforms to.  Your SGML parser will use this to find the
 	    correct DTD when processing this document.</para>
 
 	  <para><literal>PUBLIC</literal> is not a part of the FPI, but
 	    indicates to the SGML processor how to find the DTD referenced in
 	    the FPI.  Other ways of telling the SGML parser how to find the
 	    DTD are shown <link
 	      linkend="sgml-primer-fpi-alternatives">later</link>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>&gt;</literal></term>
 	
 	<listitem>
 	  <para>Returns to the document.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <sect2>
       <title>Formal Public Identifiers (FPIs)<indexterm significance="preferred">
 	  <primary>Formal Public Identifier</primary>
 	</indexterm>
 </title>
 
       <note>
 	<para>You don't need to know this, but it's useful background, and
 	  might help you debug problems when your SGML processor can't locate
 	  the DTD you are using.</para>
       </note>
       
       <para>FPIs must follow a specific syntax.  This syntax is as
 	follows;</para>
 
       <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term><replaceable>Owner</replaceable></term>
 	  
 	  <listitem>
 	    <para>This indicates the owner of the FPI.</para>
 
 	    <para>If this string starts with <quote>ISO</quote> then this is an
 	      ISO owned FPI.  For example, the FPI <literal>"ISO
 		8879:1986//ENTITIES Greek Symbols//EN"</literal> lists
 	      <literal>ISO 8879:1986</literal> as being the owner for the set
-	      of entities for greek symbols.  ISO 8879:1986 is the ISO number
+	      of entities for Greek symbols.  ISO 8879:1986 is the ISO number
 	      for the SGML standard.</para>
 
 	    <para>Otherwise, this string will either look like
 	      <literal>-//<replaceable>Owner</replaceable></literal> or
 	      <literal>+//<replaceable>Owner</replaceable></literal> (notice
 	      the only difference is the leading <literal>+</literal> or
 	      <literal>-</literal>).</para>
 
 	    <para>If the string starts with <literal>-</literal> then the
 	      owner information is unregistered, with a <literal>+</literal>
 	      it identifies it as being registered.</para>
 
 	    <para>ISO 9070:1991 defines how registered names are generated; it
 	      might be derived from the number of an ISO publication, an ISBN
 	      code, or an organisation code assigned according to ISO 6523.
 	      In addition, a registration authority could be created in order
 	      to assign registered names.  The ISO council delegated this to
 	      the American National Standards Institute (ANSI).</para>
 
 	    <para>Because the FreeBSD Project hasn't been registered the
 	      owner string is <literal>-//FreeBSD</literal>.  And as you can
 	      see, the W3C are not a registered owner either.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Keyword</replaceable></term>
 	  
 	  <listitem>
 	    <para>There are several keywords that indicate the type of
 	      information in the file.  Some of the most common keywords are
 	      <literal>DTD</literal>, <literal>ELEMENT</literal>,
 	      <literal>ENTITIES</literal>, and <literal>TEXT</literal>.
 	      <literal>DTD</literal> is used only for DTD files,
 	      <literal>ELEMENT</literal> is usually used for DTD fragments
 	      that contain only entity or element declarations.
 	      <literal>TEXT</literal> is used for SGML content (text and
 	      tags).</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Description</replaceable></term>
 	  
 	  <listitem>
 	    <para>Any description you want to supply for the contents of this
 	      file.  This may include version numbers or any short text that
 	      is meaningful to you and unique for the SGML system.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Language</replaceable></term>
 	  
 	  <listitem>
 	    <para>This is an ISO two-character code that identifies the native
 	      language for the file.  <literal>EN</literal> is used for
 	      English.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <sect3>
 	<title><filename>catalog</filename> files</title>
 	
 	<para>If you use the syntax above and try and process this document
 	  using an SGML processor, the processor will need to have some way of
 	  turning the FPI into the name of the file on your computer that
 	  contains the DTD.</para>
 	
 	<para>In order to do this it can use a catalog file.  A catalog file
 	  (typically called <filename>catalog</filename>) contains lines that
 	  map FPIs to filenames.  For example, if the catalog file contained
 	  the line;</para>
 	
 	<programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"</programlisting>
 
 	<para>The SGML processor would know to look up the DTD from
 	  <filename>strict.dtd</filename> in the <filename>4.0</filename>
 	  subdirectory of whichever directory held the
 	  <filename>catalog</filename> file that contained that line.</para>
 
 	<para>Look at the contents of
 	  <filename>/usr/local/share/sgml/html/catalog</filename>.  This is
 	  the catalog file for the HTML DTDs that will have been installed as
 	  part of the <filename>textproc/docproj</filename> port.</para>
       </sect3>
 
       <sect3>
 	<title><envar>SGML_CATALOG_FILES</envar></title>
 
 	<para>In order to locate a <filename>catalog</filename> file, your
 	  SGML processor will need to know where to look.  Many of them
 	  feature command line parameters for specifying the path to one or
 	  more catalogs.</para>
 
 	<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
 	  point to the files.  This environment variable should consist of a
 	  colon-separated list of catalog files (including their full
 	  path).</para>
 
 	<para>Typically, you will want to include the following files;</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/docbook/4.1/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/html/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/jade/catalog</filename></para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>You should <link linkend="sgml-primer-envars">already have done
 	    this</link>.</para>
       </sect3>
     </sect2>
     
     <sect2 id="sgml-primer-fpi-alternatives">
       <title>Alternatives to FPIs</title>
       
       <para>Instead of using an FPI to indicate the DTD that the document
 	conforms to (and therefore, which file on the system contains the DTD)
 	you can explicitly specify the name of the file.</para>
       
       <para>The syntax for this is slightly different:</para>
       
       <programlisting><![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
       
       <para>The <literal>SYSTEM</literal> keyword indicates that the SGML
 	processor should locate the DTD in a system specific fashion.  This
 	typically (but not always) means the DTD will be provided as a
 	filename.</para>
       
       <para>Using FPIs is preferred for reasons of portability.  You don't
 	want to have to ship a copy of the DTD around with your document, and
 	if you used the <literal>SYSTEM</literal> identifier then everyone
 	would need to keep their DTDs in the same place.</para>
     </sect2>
   </sect1>
   
   <sect1 id="sgml-primer-sgml-escape">
     <title>Escaping back to SGML</title>
 
     <para>Earlier in this primer I said that SGML is only used when writing a
       DTD.  This is not strictly true.  There is certain SGML syntax that you
       will want to be able to use within your documents.  For example,
       comments can be included in your document, and will be ignored by the
       parser.  Comments are entered using SGML syntax.  Other uses for SGML
       syntax in your document will be shown later too.</para>
       
     <para>Obviously, you need some way of indicating to the SGML processor
       that the following content is not elements within the document, but is
       SGML that the parser should act upon.</para>
 
     <para>These sections are marked by <literal>&lt;! ...  &gt;</literal> in
       your document.  Everything between these delimiters is SGML syntax as
       you might find within a DTD.</para>
 
     <para>As you may just have realised, the <link
 	linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
       is an example of SGML syntax that you need to include in your
       document&hellip;</para>
   </sect1>
   
   <sect1>
     <title>Comments</title>
     
     <para>Comments are an SGML construction, and are normally only valid
       inside a DTD.  However, as <xref linkend="sgml-primer-sgml-escape">
       shows, it is possible to use SGML syntax within your document.</para>
 
     <para>The delimiter for SGML comments is the string
-      <quote><literal>--</literal></quote>.  The first occurence of this string
+      <quote><literal>--</literal></quote>.  The first occurrence of this string
       opens a comment, and the second closes it.</para>
 
     <example>
       <title>SGML generic comment</title>
 
       <programlisting>&lt;!-- test comment --></programlisting>
       
       <programlisting><![ CDATA [
 <!-- This is inside the comment -->
 
 <!-- This is another comment    -->
 
 <!-- This is one way
      of doing multiline comments -->
 
 <!-- This is another way of   --
   -- doing multiline comments -->]]></programlisting>
     </example>
 
     <![ %output.print; [
     <important>
       <title>Use 2 dashes</title>
 
       <para>There is a problem with producing the Postscript and PDF versions
 	of this document.  The above example probably shows just one hyphen
 	symbol, <literal>-</literal> after the <literal>&lt;!</literal> and
 	before the <literal>&gt;</literal>.</para>
 
       <para>You <emphasis>must</emphasis> use two <literal>-</literal>,
 	<emphasis>not</emphasis> one.  The Postscript and PDF versions have
 	translated the two <literal>-</literal> in the original to a longer,
 	more professional <emphasis>em-dash</emphasis>, and broken this
 	example in the process.</para>
 
       <para>The HTML, plain text, and RTF versions of this document are not
 	affected.</para>
     </important>
     ]]>
     
     <para>If you have used HTML before you may have been shown different rules
       for comments.  In particular, you may think that the string
       <literal>&lt!--</literal> opens a comment, and it is only closed by
       <literal>--&gt;</literal>.</para>
 
     <para>This is <emphasis>not</emphasis> the case.  A lot of web browsers
       have broken HTML parsers, and will accept that as valid.  However, the
       SGML parsers used by the Documentation Project are much stricter, and
       will reject documents that make that error.</para>
 
     <example>
       <title>Errorneous SGML comments</title>
 
       <programlisting><![ CDATA [
 <!-- This is in the comment --
 
      THIS IS OUTSIDE THE COMMENT!
 
   -- back inside the comment -->]]></programlisting>
 
       <para>The SGML parser will treat this as though it were actually;</para>
 
       <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
 
       <para>This is not valid SGML, and may give confusing error
 	messages.</para>
 
       <programlisting><![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting>
 
       <para>As the example suggests, <emphasis>do not</emphasis> write
 	comments like that.</para>
 
       <programlisting><![ CDATA [<!--===================================================-->]]></programlisting>
 
       <para>That is a (slightly) better approach, but it still potentially
 	confusing to people new to SGML.</para>
     </example>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Add some comments to <filename>example.sgml</filename>, and
 	    check that the file still validates using &man.nsgmls.1;</para>
 	</step>
 
 	<step>
 	  <para>Add some invalid comments to
 	    <filename>example.sgml</filename>, and see the error messages that
 	    &man.nsgmls.1; gives when it encounters an invalid comment.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
     
   <sect1>
     <title>Entities</title>
 
     <para>Entities are a mechanism for assigning names to chunks of content.
       As an SGML parser processes your document, any entities it finds are
       replaced by the content of the entity.</para>
     
     <para>This is a good way to have re-usable, easily changeable chunks of
       content in your SGML documents.  It is also the only way to include one
       marked up file inside another using SGML.</para>
     
     <para>There are two types of entities which can be used in two different
       situations; <emphasis>general entities</emphasis> and
       <emphasis>parameter entities</emphasis>.</para>
     
     <sect2 id="sgml-primer-general-entities">
       <title>General Entities</title>
       
       <para>You cannot use general entities in an SGML context (although you
 	define them in one).  They can only be used in your document.
 	Contrast this with <link
 	  linkend="sgml-primer-parameter-entities">parameter
 	  entities</link>.</para>
 
       <para>Each general entity has a name.  When you want to reference a
 	general entity (and therefore include whatever text it represents in
 	your document), you write
 	<literal>&amp;<replaceable>entity-name</replaceable>;</literal>.  For
 	example, suppose you had an entity called
 	<literal>current.version</literal> which expanded to the current
 	version number of your product.  You could write;</para>
 
       <programlisting><![ CDATA [<para>The current version of our product is
   &current.version;.</para>]]></programlisting>
 
       <para>When the version number changes you can simply change the
 	definition of the value of the general entity and reprocess your
 	document.</para>
 
       <para>You can also use general entities to enter characters that you
 	could not otherwise include in an SGML document.  For example, &lt;
 	and &amp; cannot normally appear in an SGML document.  When the SGML
 	parser sees the &lt; symbol it assumes that a tag (either a start tag
 	or an end tag) is about to appear, and when it sees the &amp; symbol
 	it assumes the next text will be the name of an entity.</para>
 
       <para>Fortunately, you can use the two general entities &amp;lt; and
 	&amp;amp; whenever you need to include one or other of these </para>
 	
       <para>A general entity can only be defined within an SGML context.
 	Typically, this is done immediately after the DOCTYPE
 	declaration.</para>
 
       <example>
 	<title>Defining general entities</title>
 
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>]]></programlisting>
 	  
 	<para>Notice how the DOCTYPE declaration has been extended by adding a
 	  square bracket at the end of the first line.  The two entities are
 	  then defined over the next two lines, before the square bracket is
 	  closed, and then the DOCTYPE declaration is closed.</para>
 
 	<para>The square brackets are necessary to indicate that we are
 	  extending the DTD indicated by the DOCTYPE declaration.</para>
       </example>
     </sect2>
     
     <sect2 id="sgml-primer-parameter-entities">
       <title>Parameter entities</title>
 
       <para>Like <link linkend="sgml-primer-general-entities">general
 	  entities</link>, parameter entities are used to assign names to
 	reusable chunks of text.  However, where as general entities can only
 	be used within your document, parameter entities can only be used
 	within an <link linkend="sgml-primer-sgml-escape">SGML
 	  context</link>.</para>
 
       <para>Parameter entities are defined in a similar way to general
 	entities.  However, instead of using
 	<literal>&amp;<replaceable>entity-name</replaceable>;</literal> to
 	refer to them, use
 	<literal>%<replaceable>entity-name</replaceable>;</literal><footnote>
 	  <para><emphasis>P</emphasis>arameter entities use the
 	    <emphasis>P</emphasis>ercent symbol.</para>
 	</footnote>.  The definition also includes the <literal>%</literal>
 	between the <literal>ENTITY</literal> keyword and the name of the
 	entity.</para>
       
       <example>
 	<title>Defining parameter entities</title>
 	
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % param.some "some">
 <!ENTITY % param.text "text">
 <!ENTITY % param.new  "%param.some more %param.text">
 
 <!-- %param.new now contains "some more text" -->
 ]>]]></programlisting>
       </example>
 	
       <para>This may not seem particularly useful.  It will be.</para>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Add a general entity to
 	    <filename>example.sgml</filename>.</para>
 
 	  <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
 <!ENTITY version "1.1">
 ]>	  
 
 <html>
   <head>	     
     <title>An example HTML file</title>
   </head>
 
   <!-- You might well have some comments in here as well -->
 	  
   <body>	    
     <p>This is a paragraph containing some text.</p>
 
     <p>This paragraph contains some more text.</p>
 
     <p align="right">This paragraph might be right-justified.</p>
 
     <p>The current version of this document is: &version;</p>	  
   </body>	    
 </html>]]></programlisting>	  
 	</step>
 
 	<step>
 	  <para>Validate the document using &man.nsgmls.1;</para>
 	</step>
 
 	<step>
 	  <para>Load <filename>example.sgml</filename> into your web browser
 	    (you may need to copy it to <filename>example.html</filename>
 	    before your browser recognises it as an HTML document).</para>
 
 	  <para>Unless your browser is very advanced, you won't see the entity
 	    reference <literal>&amp;version;</literal> replaced with the
 	    version number.  Most web browsers have very simplistic parsers
 	    which do not handle proper SGML<footnote>
 	      <para>This is a shame.  Imagine all the problems and hacks (such
 		as Server Side Includes) that could be avoided if they
 		did.</para>
 	    </footnote>.</para>
 	</step>
 
 	<step>
 	  <para>The solution is to <emphasis>normalise</emphasis> your
 	    document using an SGML normaliser.  The normaliser reads in valid
 	    SGML and outputs equally valid SGML which has been transformed in
 	    some way.  One of the ways in which the normaliser transforms the
 	    SGML is to expand all the entity references in the document,
 	    replacing the entities with the text that they represent.</para>
 
 	  <para>You can use &man.sgmlnorm.1; to do this.</para>
 
           <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen>
 
 	  <para>You should find a normalised (i.e., entity references
 	    expanded) copy of your document in
 	    <filename>example.html</filename>, ready to load into your web
 	    browser.</para>
 	</step>
 
 	<step>
 	  <para>If you look at the output from &man.sgmlnorm.1; you will see
 	    that it does not include a DOCTYPE declaration at the start.  To
 	    include this you need to use the <option>-d</option>
 	    option;</para>
 
           <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	</step>
       </procedure>
     </sect2>
   </sect1>
   
   <sect1>
     <title>Using entities to include files</title>
     
     <para>Entities (both <link
 	linkend="sgml-primer-general-entities">general</link> and <link
 	linkend="sgml-primer-parameter-entities">parameter</link>) are
       particularly useful when used to include one file inside another.</para>
 
     <sect2 id="sgml-primer-include-using-gen-entities">
       <title>Using general entities to include files</title>
       
       <para>Suppose you have some content for an SGML book organised into
 	files, one file per chapter, called
 	<filename>chapter1.sgml</filename>,
 	<filename>chapter2.sgml</filename>, and so forth, with a
 	<filename>book.sgml</filename> file that will contain these
 	chapters.</para>
 
       <para>In order to use the contents of these files as the values for your
 	entities, you declare them with the <literal>SYSTEM</literal> keyword.
 	This directs the SGML parser to use the contents of the named file as
 	the value of the entity.</para>
 
       <example>
 	<title>Using general entities to include files</title>
 	
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY chapter.1 SYSTEM "chapter1.sgml">
 <!ENTITY chapter.2 SYSTEM "chapter2.sgml">
 <!ENTITY chapter.3 SYSTEM "chapter3.sgml">
 <!-- And so forth -->
 ]>
 
 <html>
   <!-- Use the entities to load in the chapters -->
 
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>]]></programlisting>
       </example>
       
       <warning>
 	<para>When using general entities to include other files within a
 	  document, the files being included
 	  (<filename>chapter1.sgml</filename>,
 	  <filename>chapter2.sgml</filename>, and so on) <emphasis>must
 	    not</emphasis> start with a DOCTYPE declaration.  This is a syntax
 	  error.</para>
       </warning>
     </sect2>
     
     <sect2>
       <title>Using parameter entities to include files</title>
       
       <para>Recall that parameter entities can only be used inside an SGML
 	context.  Why then would you want to include a file within an SGML
 	context?</para>
 
       <para>You can use this to ensure that you can reuse your general
 	entities.</para>
 
       <para>Suppose that you had many chapters in your document, and you
 	reused these chapters in two different books, each book organising the
 	chapters in a different fashion.</para>
 
       <para>You could list the entities at the top of each book, but this
 	quickly becomes cumbersome to manage.</para>
 
       <para>Instead, place the general entity definitions inside one file,
 	and use a parameter entity to include that file within your
 	document.</para>
 
       <example>
 	<title>Using parameter entities to include files</title>
 
 	<para>First, place your entity definitions in a separate file, called
 	  <filename>chapters.ent</filename>.  This file contains the
 	  following;</para>
 	  
 	<programlisting><![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml">
 <!ENTITY chapter.2 SYSTEM "chapter2.sgml">
 <!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting>
 
 	<para>Now create a parameter entity to refer to the contents of the
 	  file.  Then use the parameter entity to load the file into the
 	  document, which will then make all the general entities available
 	  for use.  Then use the general entities as before;</para>
 
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!-- Define a parameter entity to load in the chapter general entities -->
 <!ENTITY % chapters SYSTEM "chapters.ent">
 
 <!-- Now use the parameter entity to load in this file -->
 %chapters;
 ]>
 
 <html>
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>]]></programlisting>
       </example>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <sect3>
 	<title>Use general entities to include files</title>
 
 	<procedure>
 	  <step>
 	    <para>Create three files, <filename>para1.sgml</filename>,
 	      <filename>para2.sgml</filename>, and
 	      <filename>para3.sgml</filename>.</para>
 
 	    <para>Put content similar to the following in each file;</para>
 
 	    <programlisting><![ CDATA [<p>This is the first paragraph.</p>]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Edit <filename>example.sgml</filename> so that it looks like
 	      this;</para>
 
 	    <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">
 ]>
 
 <html>
   <head>
     <title>An example HTML file</title>
   </head>
 
   <body>
     <p>The current version of this document is: &version;</p>
 
     &para1;
     &para2;
     &para3;
   </body>
 </html>]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Produce <filename>example.html</filename> by normalising
 	      <filename>example.sgml</filename>.</para>
 
             <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	  </step>
 
 	  <step>
 	    <para>Load <filename>example.html</filename> in to your web
 	      browser, and confirm that the
 	      <filename>para<replaceable>n</replaceable>.sgml</filename> files
 	      have been included in <filename>example.html</filename>.</para>
 	  </step>
 	</procedure>
       </sect3>
 
       <sect3>
 	<title>Use parameter entities to include files</title>
 
 	<note>
 	  <para>You must have taken the previous steps first.</para>
 	</note>
 	
 	<procedure>
 	  <step>
 	    <para>Edit <filename>example.sgml</filename> so that it looks like
 	      this;</para>
 	    
 	    <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
 ]>
 
 <html>
   <head>
     <title>An example HTML file</title>
   </head>
 
   <body>
     <p>The current version of this document is: &version;</p>
 
     &para1;
     &para2;
     &para3;
   </body>
 </html>]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Create a new file, <filename>entities.sgml</filename>, with
 	      this content:</para>
 
 	    <programlisting><![ CDATA [<!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Produce <filename>example.html</filename> by normalising
 	      <filename>example.sgml</filename>.</para>
 
             <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	  </step>
 
 	  <step>
 	    <para>Load <filename>example.html</filename> in to your web
 	      browser, and confirm that the
 	      <filename>para<replaceable>n</replaceable>.sgml</filename> files
 	      have been included in <filename>example.html</filename>.</para>
 	  </step>
 	</procedure>
       </sect3>
     </sect2>
   </sect1>
   
   <sect1 id="sgml-primer-marked-sections">
     <title>Marked sections</title>
     
     <para>SGML provides a mechanism to indicate that particular pieces of the
       document should be processed in a special way.  These are termed
       <quote>marked sections</quote>.</para>
 
     <example>
       <title>Structure of a marked section</title>
 
       <programlisting>&lt;![ <replaceable>KEYWORD</replaceable> [
   Contents of marked section
 ]]&gt;</programlisting>
     </example>
 
     <para>As you would expect, being an SGML construct, a marked section
       starts with <literal>&lt!</literal>.</para>
 
     <para>The first square bracket begins to delimit the marked
       section.</para>
 
     <para><replaceable>KEYWORD</replaceable> describes how this marked
       section should be processed by the parser.</para>
 
     <para>The second square bracket indicates that the content of the marked
       section starts here.</para>
     
     <para>The marked section is finished by closing the two square brackets,
       and then returning to the document context from the SGML context with
       <literal>&gt;</literal></para>
     
     <sect2>
       <title>Marked section keywords</title>
       
       <sect3>
 	<title><literal>CDATA</literal>, <literal>RCDATA</literal></title>
 	
 	<para>These keywords denote the marked sections <emphasis>content
 	    model</emphasis>, and allow you to change it from the
 	  default.</para>
 	
 	<para>When an SGML parser is processing a document it keeps track
 	  of what is called the <quote>content model</quote>.</para>
 	
 	<para>Briefly, the content model describes what sort of content the
 	  parser is expecting to see, and what it will do with it when it
 	  finds it.</para>
 
 	<para>The two content models you will probably find most useful are
 	  <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
 	
 	<para><literal>CDATA</literal> is for <quote>Character Data</quote>.
 	  If the parser is in this content model then it is expecting to see
 	  characters, and characters only.  In this model the &lt; and &amp;
 	  symbols lose their special status, and will be treated as ordinary
 	  characters.</para>
 	
 	<para><literal>RCDATA</literal> is for <quote>Entity references and
 	  character data</quote> If the parser is in this content model then it
 	  is expecting to see characters <emphasis>and</emphasis> entities.
 	  &lt; loses its special status, but &amp; will still be treated as
 	  starting the beginning of a general entity.</para>
 	
 	<para>This is particularly useful if you are including some verbatim
 	  text that contains lots of &lt; and &amp; characters.  While you
 	  could go through the text ensuring that every &lt; is converted to a
 	  &amp;lt; and every &amp; is converted to a &amp;amp;, it can be
 	  easier to mark the section as only containing CDATA.  When the SGML
 	  parser encounters this it will ignore the &lt; and &amp; symbols
 	  embedded in the content.</para>
 
 	<!-- The nesting of CDATA within the next example is disgusting -->
 	  
 	<example>
 	  <title>Using a CDATA marked section</title>
 	  
 	  <programlisting>&lt;para>Here is an example of how you would include some text
   that contained many &amp;lt; and &amp;amp; symbols.  The sample
   text is a fragment of HTML.  The surrounding text (&lt;para> and
   &lt;programlisting>) are from DocBook.&lt;/para>
 
 &lt;programlisting>
   &lt![ CDATA [  <![ CDATA [
     <p>This is a sample that shows you some of the elements within
       HTML.  Since the angle brackets are used so many times, it's
       simpler to say the whole example is a CDATA marked section
       than to use the entity names for the left and right angle
       brackets throughout.</p>
 
     <ul>
       <li>This is a listitem</li>
       <li>This is a second listitem</li>
       <li>This is a third listitem</li>
     </ul>
 
     <p>This is the end of the example.</p>]]>
   ]]&gt;
 &lt/programlisting></programlisting>
 
 	  <para>If you look at the source for this document you will see this
 	    technique used throughout.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title><literal>INCLUDE</literal> and
 	  <literal>IGNORE</literal></title>
 	
 	<para>If the keyword is <literal>INCLUDE</literal> then the contents
 	  of the marked section will be processed.  If the keyword is
 	  <literal>IGNORE</literal> then the marked section is ignored and
 	  will not be processed.  It will not appear in the output.</para>
 
 	<example>
 	  <title>Using <literal>INCLUDE</literal> and
 	    <literal>IGNORE</literal> in marked sections</title>
 
 	  <programlisting>&lt;![ INCLUDE [
   This text will be processed and included.
 ]]&gt;
 
 &lt;![ IGNORE [
   This text will not be processed or included.
 ]]&gt;</programlisting>
 	</example>
 	
 	<para>By itself, this isn't too useful.  If you wanted to remove text
 	  from your document you could cut it out, or wrap it in
 	  comments.</para>
 	  
 	<para>It becomes more useful when you realise you can use <link
 	    linkend="sgml-primer-parameter-entities">parameter entities</link>
 	  to control this.  Remember that parameter entities can only be used
 	  in SGML contexts, and the keyword of a marked section
 	  <emphasis>is</emphasis> an SGML context.</para>
 
 	<para>For example, suppose that you produced a hard-copy version of
 	  some documentation and an electronic version.  In the electronic
 	  version you wanted to include some extra content that wasn't to
 	  appear in the hard-copy.</para>
 
 	<para>Create a parameter entity, and set it's value to
 	  <literal>INCLUDE</literal>.  Write your document, using marked
 	  sections to delimit content that should only appear in the
 	  electronic version.  In these marked sections use the parameter
 	  entity in place of the keyword.</para>
 
 	<para>When you want to produce the hard-copy version of the document,
 	  change the parameter entity's value to <literal>IGNORE</literal> and
 	  reprocess the document.</para>
 
 	<example>
 	  <title>Using a parameter entity to control a marked
 	    section</title>
 	  
 	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 &lt;!ENTITY % electronic.copy "INCLUDE">	     
 ]]&gt;
 
 ...
 
 &lt;![ %electronic.copy [
   This content should only appear in the electronic
   version of the document.
 ]]&gt;</programlisting>
 
 	  <para>When producing the hard-copy version, change the entity's
 	    definition to;</para>
 	  
 	  <programlisting>&lt!ENTITY % electronic.copy "IGNORE"></programlisting>
 
 	  <para>On reprocessing the document, the marked sections that use
 	    <literal>%electronic.copy</literal> as their keyword will be
 	    ignored.</para>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Create a new file, <filename>section.sgml</filename>, that
 	    contains the following;</para>
 
 	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 &lt;!ENTITY % text.output "INCLUDE">
 ]&gt;
 
 &lt;html>
   &lt;head>
     &lt;title>An example using marked sections&lt;/title>
   &lt;/head>
 
   &lt;body>	    
     &lt;p>This paragraph &lt;![ CDATA [contains many &lt;
       characters (&lt; &lt; &lt; &lt; &lt;) so it is easier
       to wrap it in a CDATA marked section ]]&gt;&lt/p>
 
     &lt;![ IGNORE [
     &lt;p>This paragraph will definitely not be included in the
       output.&lt;/p>
     ]]&gt;
 
     &lt;![ <![ CDATA [%text.output]]> [
     &lt;p>This paragraph might appear in the output, or it
       might not.&lt;/p>
 
     &lt;p>Its appearance is controlled by the <![CDATA[%text.output]]>
       parameter entity.&lt;/p>	    
     ]]&gt;
   &lt;/body>
 &lt;/html></programlisting>	    
 	</step>
 
 	<step>
 	  <para>Normalise this file using &man.sgmlnorm.1; and examine the
 	    output.  Notice which paragraphs have appeared, which have
 	    disappeared, and what has happened to the content of the CDATA
 	    marked section.</para>
 	</step>
 
 	<step>
 	  <para>Change the definition of the <literal>text.output</literal>
 	    entity from <literal>INCLUDE</literal> to
 	    <literal>IGNORE</literal>.  Re-normalise the file, and examine the
 	    output to see what has changed.  </para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
   
   <sect1>
     <title>Conclusion</title>
     
     <para>That is the conclusion of this SGML primer.  For reasons of space
       and complexity several things have not been covered in depth (or at
       all).  However, the previous sections cover enough SGML for you to be
       able to follow the organisation of the FDP documentation.</para>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
index fb1614180a..24f64eacc5 100644
--- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
@@ -1,218 +1,218 @@
 <!-- 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="the-website">
   <title>The Website</title>
   
   <sect1>
     <title>Preparation</title>
     
     <para>Get 200MB free disk space. You will need the disk space for the
       SGML tools, a subset of the CVS tree, temporary build space and the
-      installed web pages. If you aready have installed the SGML tools and
+      installed web pages. If you already have installed the SGML tools and
       the CVS tree, you need only ~100MB free disk space.</para>
     
     <note>
       <para>Make sure your documentation ports are up to date!  When in
 	doubt, remove the old ports using &man.pkg.delete.1; command before
 	installing the port.  For example, we currently depend on
 	jade-1.2 and if you have installed jade-1.1, please do</para>
 
       <screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen>
     </note>
 
     <para>Setup a CVS repository. You need the directories www, doc and
       ports in the CVS tree (plus the CVSROOT of course).  Please read the
       CVSup introduction <ulink
 	url="../handbook/synching.html#CVSUP">
 	http://www.FreeBSD.org/handbook/synching.html#CVSUP</ulink> how to
       mirror a CVS tree or parts of a CVS tree.</para>
     
     <para>The essential cvsup collections are: <literal>www</literal>,
       <literal>doc-all</literal>, <literal>cvs-base</literal>, and
       <literal>ports-base</literal>.</para>
     
     <para>These collections require ~100MB free disk space.</para>
     
     <para>A full CVS tree - including <literal>src</literal>,
       <literal>doc</literal>, <literal>www</literal>, and
       <literal>ports</literal> - is currently 650MB large.</para>
   </sect1>
   
   <sect1>
     <title>Build the web pages from scratch</title>
     
     <procedure> 
       <step>
 	<para>Go to into a build directory with at least 60MB of free
 	  space.</para>
 	
 	<screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput>
 &prompt.root; <userinput>cd /var/tmp/webbuild</userinput></screen>
       </step>
 
       <step>
 	<para>Checkout the SGML files from the CVS tree.</para>
 	
 	<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
       </step>
       
       <step>
         <para>Change in to the <filename>www</filename> directory, and
 	  run the &man.make.1; <maketarget>links</maketarget> target, to
 	  create the necessary symbolic links.</para>
 	
 	<screen>&prompt.root; <userinput>cd www</userinput>
 &prompt.root; <userinput>make links</userinput></screen>
       </step>
 
       <step>
 	<para>Change in to the <filename>en</filename> directory, and run
 	  the &man.make.1; <maketarget>all</maketarget> target, to create
 	  the web pages.</para>
 	
 	<screen>&prompt.root; <userinput>cd en</userinput>
 &prompt.root; <userinput>make all</userinput></screen>
       </step>
     </procedure>
   </sect1>
   
   <sect1>
     <title>Install the web pages into your web server</title>
     
     <procedure>
       <step>
 	<para>If you have moved out of the <filename>en</filename>
 	  directory, change back to it.</para>
 	
 	  <screen>&prompt.root; <userinput>cd <replaceable>path</replaceable>/www/en</userinput></screen>
       </step>
 
       <step>
 	<para>Run the &man.make.1; <maketarget>install</maketarget> target,
 	  setting the <makevar>DESTDIR</makevar> variable to the name of the 
 	  directory you want to install the files to.</para>
 	
 	<screen>&prompt.root; <userinput>make DESTDIR=<replaceable>/usr/local/www</replaceable> install</userinput></screen>
       </step>
 
       <step>
 	<para>If you have previously installed the web pages in to the same
 	  directory the install process will not have deleted any old or
 	  outdated pages.  For example, if you build and install a new copy
 	  of the site every day, this command will find and delete all
 	  files that have not been updated in three days.</para>
 	
 	<screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -print0 | xargs -0 rm</userinput></screen>
       </step>
     </procedure>
   </sect1>
   
   <sect1>
     <title>Environment variables</title>
     
     <variablelist>
       <varlistentry>
 	<term><envar>CVSROOT</envar></term>
 	
 	<listitem>
 	  <para>Location of the CVS tree. Essential.</para>
 	  
 	  <screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen>
 	</listitem>
       </varlistentry>
 	
       <varlistentry>
 	<term><makevar>ENGLISH_ONLY</makevar></term>
 	
 	<listitem>
 	  <para>If set and not empty, the makefiles will build and
 	    install only the English documents. All translations will be
 	    ignored. E.g.:</para>
 	  
 	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
 
 	  <para>If you want unset the variable
 	    <makevar>ENGLISH_ONLY</makevar> and build all pages, including
 	    translations, set the variable <makevar>ENGLISH_ONLY</makevar>
 	    to an empty value</para>
 	  
 	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term><makevar>WEB_ONLY</makevar></term>
 	
 	<listitem>
 	  <para>If set and not empty, the makefiles wil build and install
 	    only the HTML pages from the www directory. All documents from
 	    the doc directory (Handbook, FAQ, Tutorials) will be ignored.
 	    E.g.:</para>
 	  
 	  <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
 	</listitem>
       </varlistentry>
 	
       <varlistentry>
 	<term><makevar>NOPORTSCVS</makevar></term>
 	
 	<listitem>
 	  <para>If set, the makefiles will not checkout files from the ports
 	    cvs repository. Instead, it will copy the files from
 	    <filename>/usr/ports</filename> (or where the variable
 	    <envar>PORTSBASE</envar> points to).</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <para><envar>CVSROOT</envar> is an environment variable. You must set it
-      on the commandline or in your dot files (~/.profile).</para>
+      on the command line or in your dot files (~/.profile).</para>
     
     <para><makevar>WEB_ONLY</makevar>, <makevar>ENGLISH_ONLY</makevar> and
       <makevar>NOPORTSCVS</makevar> are makefile variables. You can set the
       variables in <filename>/etc/make.conf</filename>,
       <filename>Makefile.inc</filename> or as environment variables on the
-      commandline or in your dot files.</para>
+      command line or in your dot files.</para>
   </sect1>
 </chapter>
   
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
index 21167ba5a6..d595f15ff5 100644
--- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
@@ -1,285 +1,285 @@
 <!-- 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: doc/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml,v 1.13 2001/06/22 10:29:03 nik Exp $
+     $FreeBSD$
 -->
 
 <chapter id="tools">
   <title>Tools</title>
   
   <para>The FDP uses a number of different software tools to help
     manage the FreeBSD documentation, convert it to different output
     formats, and so on.  You will need to use these tools yourself if
     you are to work with the FreeBSD documentation.</para>                    
 
   <para>All these tools are available as FreeBSD Ports and Packages,
     greatly simplifying the work you have to do to install
     them.</para>                                                              
   
   <para>You will need to install these tools before you work through
     any of the examples in later chapters.  The actual usage of these
     tools is covered in later chapters.</para>     
 
   <tip>
     <title>Use <filename>textproc/docproj</filename> if possible</title>
 
     <para>You can save yourself a lot of time if you install the
       <filename>textproc/docproj</filename> port.  This is a
       <emphasis>meta-port</emphasis> which does not contain any software
       itself.  Instead, it depends on various other ports being installed
       correctly.  Installing this port <emphasis>should</emphasis>
       automatically download and install all of the packages listed in this
       chapter that you need.</para>
 
     <para>One of the packages that you might need is the JadeTeX macro set.
       In turn, this macro set requires that TeX is installed.  TeX is a large
       package, and you only need it if you want to produce Postscript or PDF
       output.</para>
 
     <para>To save yourself time and space you must specify whether or not you
       want JadeTeX (and therefore TeX) installed when you install this port.
       Either do;
 
       <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
 
       or
 
       <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
 
       as necessary.</para>
   </tip>
 
   <sect1>
     <title>Mandatory tools</title>
 
     <sect2>
       <title>Software</title>
       
       <para>These programs are required before you can usefully work with the
 	FreeBSD documentation, and they will allow you to convert the
 	documentation to HTML, plain text, and RTF formats.  They are all
 	included in <filename>textproc/docproj</filename>.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term><application>SP</application>
 	    (<filename>textproc/sp</filename>)</term>
 	  
 	  <listitem>
 	    <para>A suite of applications, including a validating SGML parser,
 	      and an SGML normaliser.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Jade</application>
 	    (<filename>textproc/jade</filename>)</term>
 	  
 	  <listitem>
 	    <para>A DSSSL implementation.  Used for converting marked up
 	      documents to other formats, including HTML and TeX.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Tidy</application>
 	    (<filename>www/tidy</filename>)</term>
 	  
 	  <listitem>
 	    <para>An HTML 'pretty printer', used to reformat some of the
 	      automatically generated HTML so that it is easier to
 	      follow.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Links</application>
 	    (<filename>www/links</filename>)</term>
 	  
 	  <listitem>
 	    <para>A text-mode WWW browser, &man.links.1; can also convert
 	      HTML files to plain text.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><application>peps</application>
 	    (<filename>graphics/peps</filename>)</term>
 	  
 	  <listitem>
 	    <para>Some of the documentation includes images, some of which are
 	      stored as EPS files.  These must be converted to PNG before most
 	      web browsers will display them.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>DTDs and Entities</title>
 
       <para>These are the DTDs and entity sets used by the FDP.  They need to
 	be installed before you can work with any of the documentation.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term>HTML DTD (<filename>textproc/html</filename>)</term>
 	  
 	  <listitem>
 	    <para>HTML is the markup language of choice for the World Wide
 	      Web, and is used throughout the FreeBSD web site.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>DocBook DTD (<filename>textproc/docbook</filename>)</term>
 	  
 	  <listitem>
 	    <para>DocBook is designed for marking up technical documentation.
 	      All the FreeBSD documentation is written in DocBook.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>ISO 8879 entities
 	    (<filename>textproc/iso8879</filename>)</term>
 	  
 	  <listitem>
 	    <para>19 of the ISO 8879:1986 character entity sets used by many
 	      DTDs.  Includes named mathematical symbols, additional
-	      characters in the 'latin' character set (accents, diacriticals,
-	      and so on), and greek symbols.</para>
+	      characters in the 'Latin' character set (accents, diacriticals,
+	      and so on), and Greek symbols.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>Stylesheets</title>
 
       <para>The stylesheets are used when converting and formatting the
 	documentation for display on screen, printing, and so on.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term>Modular DocBook Stylesheets
 	    (<filename>textproc/dsssl-docbook-modular</filename>)</term>
 	  
 	  <listitem>
 	    <para>The Modular DocBook Stylesheets are used when converting
 	      documentation marked up in DocBook to other formats, such as
 	      HTML or RTF.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Optional tools</title>
 
     <para>You do not need to have any of the following installed.  However,
       you may find it easier to work with the documentation if you do, and
       they may give you more flexibility in the output formats that can be
       generated.</para>
 
     <sect2>
       <title>Software</title>
       
       <variablelist>
 	<varlistentry>
 	  <term><application>JadeTeX</application> and
 	    <application>teTeX</application>
 	    (<filename>print/jadetex</filename> and
 	    <filename>print/teTeX</filename>)</term>
 	  
 	  <listitem>
 	    <para><application>Jade</application> and
 	      <application>teTeX</application> are used to convert DocBook
 	      documents to DVI, Postscript, and PDF formats.  The
 	      <application>JadeTeX</application> macros are needed in order to
 	      do this.</para>
 
 	    <para>If you do not intend to convert your documentation to one of
 	      these formats (i.e., HTML, plain text, and RTF are sufficient)
 	      then you do not need to install
 	      <application>JadeTeX</application> and
 	      <application>teTeX</application>.  This can be a significant
 	      space and time saver, as <application>teTeX</application> is
 	      over 30MB in size.</para>
 
 	    <important>
 	      <para>If you decide to install
 		<application>JadeTeX</application> and
 		<application>teTeX</application> then you will need to
 		configure <application>teTeX</application> after
 		<application>JadeTeX</application> has been installed.
 		<filename>print/jadetex/pkg-message</filename> contains
 		detailed instructions explaining what you need to do.</para>
 	    </important>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Emacs</application> or
 	    <application>xemacs</application> 
 	    (<filename>editors/emacs</filename> or
 	    <filename>editors/xemacs</filename>)</term>
 	  
 	  <listitem>
 	    <para>Both these editors include a special mode for editing
 	      documents marked up according to an SGML DTD.  This mode
 	      includes commands to reduce the amount of typing you need, and
 	      help reduce the possibility of errors.</para>
 
 	    <para>You do not need to use them; any text editor can be used to
 	      edit marked up documents.  You may find they make you more
 	      efficient.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <para>If anyone has recommendations for other software that is useful
 	when manipulating SGML documents, please let Nik Clayton
 	(<email>nik@FreeBSD.org</email>) know, so they can be added to this
 	list.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
index 7112678304..f6d68d370d 100644
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -1,388 +1,388 @@
 <!-- Copyright (c) 1998 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="writing-style">
   <title>Writing style</title>
   
   <para>In order to promote consistency between the myriad authors of the
     FreeBSD documentation, some guidelines have been drawn up for authors to
     follow.</para>
   
   <variablelist>
     <varlistentry>
       <term>Do not use contractions</term>
       
       <listitem>
 	<para>Do not use contractions.  Always spell the phrase out in full.
 	  <quote>Don't use contractions</quote> would be wrong.</para>
 
 	<para>Avoiding contractions makes for a more formal tone, is more
 	  precise, and is slightly easier for translators.</para>
       </listitem>
     </varlistentry>
     
     <varlistentry>
       <term>Use the serial comma</term>
       
       <listitem>
 	<para>In a list of items within a paragraph, separate each item from
-	  the others with a comma.  Seperate the last item from the others with
+	  the others with a comma.  Separate the last item from the others with
 	  a comma and the word <quote>and</quote>.</para>
 
 	<para>For example, look at the following:</para>
 	
 	<blockquote>
 	  <para>This is a list of one, two and three items.</para>
 	</blockquote>
 	
 	<para>Is this a list of three items, <quote>one</quote>,
 	  <quote>two</quote>, and <quote>three</quote>, or a list of two items,
 	  <quote>one</quote> and <quote>two and three</quote>?</para>
 	
 	<para>It is better to be explicit and include a serial comma:</para>
 	
 	<blockquote>
 	  <para>This is a list of one, two, and three items.</para>
 	</blockquote>
       </listitem>
     </varlistentry>
     
     <varlistentry>
       <term>Avoid redundant phrases</term>
       
       <listitem>
 	<para>Try not to use redundant phrases.  In particular, <quote>the
 	  command</quote>, <quote>the file</quote>, and <quote>man
 	  command</quote> are probably redundant.</para>
 
 	<para>These two examples show this for commands.  The second example
 	  is preferred.</para>
 	
 	<informalexample>
 	  <para>Use the command <command>cvsup</command> to update your
 	    sources</para>
 	</informalexample>
       
 	<informalexample>
 	  <para>Use <command>cvsup</command> to update your sources</para>
 	</informalexample>
 	
 	<para>These two examples show this for filenames.  The second example
 	  is preferred.</para>
 	
 	<informalexample>
 	  <para>&hellip; in the filename
 	    <filename>/etc/rc.local</filename>&hellip;</para>
 	</informalexample>
 	
 	<informalexample>
 	  <para>&hellip; in
 	    <filename>/etc/rc.local</filename>&hellip;</para>
 	</informalexample>
 	
 	<para>These two examples show this for manual references.  The second
 	  example is preferred (the second example uses
 	  <sgmltag>citerefentry</sgmltag>).</para>
 	
 	<informalexample>
 	  <para>See <command>man csh</command> for more
 	    information.</para>
 	</informalexample>
 	
 	<informalexample>
 	  <para>See &man.csh.1;</para>
 	</informalexample>
       </listitem>
     </varlistentry>
     <varlistentry>
       <term>Two spaces at the end of sentences</term>
 
       <listitem>
 	<para>Always use two spaces at the end of sentences, as this
 	  improves readability, and eases use of tools such as
 	  <application>emacs</application>.</para>
 
 	<para>While it may be argued that a capital letter following
 	  a period denotes a new sentence, this is not the case, especially
 	  in name usage.  <quote>Jordan K. Hubbard</quote> is a good
 	  example; it has a capital <literal>H</literal> following a
 	  period and a space, and there certainly isn't a new sentence
 	  there.</para>
       </listitem>
     </varlistentry>
   </variablelist>
 
   <para>For more information about writing style, see <ulink
       url="http://www.bartleby.com/141/">Elements of
       Style</ulink>, by William Strunk.</para>
 
   <sect1>
     <title>Style guide</title>
 
     <para>To keep the source for the Handbook consistent when many different
       people are editing it, please follow these style conventions.</para>
 
     <sect2>
       <title>Letter case</title>
 
       <para>Tags are entered in lower case, <literal>&lt;para&gt;</literal>,
 	<emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
 
       <para>Text that appears in SGML contexts is generally written in upper
 	case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
 	<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
 	<literal>&lt;!entity&hellip;&gt;</literal> and
 	<literal>&lt;!doctype&hellip;&gt;</literal>.</para>
     </sect2>
 
     <sect2>
       <title>Indentation</title>
 
       <para>Each file starts with indentation set at column 0,
 	<emphasis>regardless</emphasis> of the indentation level of the file
 	which might contain this one.</para>
 
       <para>Every start tag increases the indentation level by 2 spaces, and
 	every end tag decreases the indentation level by 2 spaces.  Replace
 	as many leading spaces with tabs as appropriate.  Do not use
 	spaces in front of tabs, and do not add extraneous whitespace at the
 	end of a line.  Content
 	within elements should be indented by two spaces if the content runs
 	over more than one line.</para>
 
       <para>For example, the source for this section looks something
 	like:</para>
 
       <programlisting><![ CDATA [+--- This is column 0
 V
 <chapter>
   <title>...</title>
 
   <sect1>
     <title>...</title>
 
     <sect2>
       <title>Indentation</title>
 
       <para>Each file starts with indentation set at column 0,
         <emphasis>regardless</emphasis> of the indentation level of the file
         which might contain this one.</para>
 
       <para>Every start tag increases the indentation level by 2 spaces, and
         every end tag decreases the indentation level by 2 spaces.  Content
         within elements should be indented by two spaces if the content runs
         over more than one line.</para>
 
       ...	
     </sect2>
   </sect1>
 </chapter>]]></programlisting>
 
       <para>If you use <application>Emacs</application> or
 	<application>Xemacs</application> to edit the files then
 	<literal>sgml-mode</literal> should be loaded automatically, and the
 	Emacs local variables at the bottom of each file should enforce these
 	styles.</para>
     </sect2>
 
     <sect2>
       <title>Tag style</title>
 
       <sect3>
 	<title>Tag spacing</title>
 	
 	<para>Tags that start at the same indent as a previous tag
 	  should be separated by a blank line, and those that are not
 	  at the same indent as a previous tag should not:</para>
 
 	<informalexample>
 	  <programlisting><![ CDATA [<article>
   <articleinfo>
     <title>NIS</title>
 
     <pubdate>October 1999</pubdata>
 
     <abstract>
       <para>...
 	...
 	...</para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>...</title>
 
     <para>...</para>
   </sect1>
 
   <sect1>
     <title>...</title>
 
     <para>...</para>
   </sect1>
 </article>]]></programlisting>
 	</informalexample>
       </sect3>
 
       <sect3>
 	<title>Separating tags</title>
 
 	<para>Tags like <sgmltag>itemizedlist</sgmltag> which will
 	  always have further tags inside them, and in fact don't take
 	  character data themselves, are always on a line by
 	  themselves.</para>
 
 	<para>Tags like <sgmltag>para</sgmltag> and
 	  <sgmltag>term</sgmltag> don't need other tags to contain
 	  normal character data, and their contents begin immediately
 	  after the tag, <emphasis>on the same line</emphasis>.</para>
 
 	<para>The same applies to when these two types of tags
 	  close.</para>
 
 	<para>This leads to an obvious problem when mixing these
 	  tags.</para>
 
 	<para>When a starting tag which cannot contain character data
 	  directly follows a tag of the type that requires other tags
 	  within it to use character data, they are on separate lines.
 	  The second tag should be properly indented.</para>
 
 	<para>When a tag which can contain character data closes
 	  directly after a tag which cannot contain character data
 	  closes, they co-exist on the same line.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>White space changes</title>
 
       <para>When committing changes, <emphasis>do not commit changes to the
 	  content at the same time as changes to the
 	  formatting</emphasis>.</para>
       
       <para>This is so that the teams that convert the Handbook to other
 	languages can quickly see what content has actually changed in your
 	commit, without having to decide whether a line has changed because of
 	the content, or just because it has been refilled.</para>
 
       <para>For example, if you have added two sentences to a paragraph, such
 	that the line lengths on the paragraph now go over 80 columns, first
 	commit your change with the too-long line lengths.  Then fix the line
 	wrapping, and commit this second change.  In the commit message for
 	the second change, be sure to indicate that this is a whitespace-only
 	change, and that the translation team can ignore it.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Word list</title>
 
     <para>The following is a small list of words spelled the way they
       should be used in the FreeBSD Documentation Project.  If the
       word you are looking for is not in this list, then please
       consult the <ulink
       url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
       word list</ulink>.</para>
 
     <itemizedlist>
       <listitem>
 	<para>2.2.X</para>
       </listitem>
 
       <listitem>
 	<para>4.X-STABLE</para>
       </listitem>
 
       <listitem>
 	<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
       </listitem>
 
       <listitem>
 	<para>FreeBSD Ports Collection</para>
       </listitem>
 
       <listitem>
 	<para>Internet</para>
       </listitem>
 
       <listitem>
 	<para>CDROM</para>
       </listitem>
 
       <listitem>
 	<para>MHz</para>
       </listitem>
 
       <listitem>
 	<para>ports collection</para>
       </listitem>
 
       <listitem>
 	<para>Unix</para>
       </listitem>
 
       <listitem>
 	<para>email</para>
       </listitem>
 
       <listitem>
 	<para>manual page(s)</para>
       </listitem>
 
       <listitem>
 	<para>mail server</para>
       </listitem>
 
       <listitem>
 	<para>name server</para>
       </listitem>
 
       <listitem>
 	<para>web server</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->