aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/Makefile38
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/book.sgml278
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/chapter.decl1
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/chapters.ent22
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml89
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml148
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml119
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml2210
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml1554
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml68
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml47
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml210
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml137
13 files changed, 4921 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile
new file mode 100644
index 0000000000..6321390a6d
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/Makefile
@@ -0,0 +1,38 @@
+#
+# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $
+#
+# Build the FreeBSD Documentation Project Primer.
+#
+
+MAINTAINER=nik@FreeBSD.ORG
+
+DOC?= book
+
+FORMATS?= html-split
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+#
+# SRCS lists the individual SGML files that make up the document. Changes
+# to any of these files will force a rebuild
+#
+
+# SGML content
+SRCS= book.sgml
+SRCS+= overview/chapter.sgml
+SRCS+= psgml-mode/chapter.sgml
+SRCS+= see-also/chapter.sgml
+SRCS+= sgml-markup/chapter.sgml
+SRCS+= sgml-primer/chapter.sgml
+SRCS+= stylesheets/chapter.sgml
+SRCS+= the-faq/chapter.sgml
+SRCS+= the-handbook/chapter.sgml
+SRCS+= the-website/chapter.sgml
+SRCS+= tools/chapter.sgml
+SRCS+= writing-style/chapter.sgml
+
+# Entities
+SRCS+= chapters.ent
+
+.include "../../../share/mk/docproj.docbook.mk"
diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml
new file mode 100644
index 0000000000..2355b1683d
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml
@@ -0,0 +1,278 @@
+<!-- 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.
+-->
+
+<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
+
+<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
+%man;
+
+<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
+]>
+
+<book>
+ <bookinfo>
+ <title>FreeBSD Documentation Project Primer for New Contributors</title>
+
+ <author>
+ <firstname>Nik</firstname>
+ <surname>Clayton</surname>
+ <affiliation>
+ <address><email>nik@FreeBSD.ORG</email></address>
+ </affiliation>
+ </author>
+
+ <copyright>
+ <year>1998</year>
+ <year>1999</year>
+ <holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder>
+ </copyright>
+
+ <pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate>
+
+ <releaseinfo>$ID$</releaseinfo>
+
+ <legalnotice>
+ <para>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:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </orderedlist>
+
+ <important>
+ <para>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.</para>
+ </important>
+ </legalnotice>
+
+ <abstract>
+ <para>Thank you for becoming a part of the FreeBSD Documentation
+ Project. Your contribution is extremely valuable.</para>
+
+ <para>This primer covers everything you will need to know in order
+ to start contributing to the FreeBSD Documentation Project, from
+ the tools and software you will be using (both mandatory and
+ recommended) to the philosophy behind the Documentation
+ Project.</para>
+
+ <para>This document is a work in progress, and is not complete. Sections
+ that are known to be incomplete are indicated with a
+ <literal>*</literal> in their name.</para>
+ </abstract>
+ </bookinfo>
+
+ <preface>
+ <title>Preface</title>
+
+ <sect1>
+ <title>Shell Prompts</title>
+
+ <para>The following table shows the default system prompt and superuser
+ prompt. The examples will use this prompt to indicate which user you
+ should be running the example as.</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>User</entry>
+ <entry>Prompt</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Normal user</entry>
+ <entry>&prompt.user;</entry>
+ </row>
+
+ <row>
+ <entry><username>root</username></entry>
+ <entry>&prompt.root;</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+ <sect1>
+ <title>Typographic Conventions</title>
+
+ <para>The following table describes the typographic conventions used in
+ this book.</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Meaning</entry>
+ <entry>Examples</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>The name of commands, files, and directories. On screen
+ computer output.</entry>
+ <entry><para>Edit your <filename>.login</filename>
+ file.</para><para>Use <command>ls -a</command> to list all
+ files.</para><para><screen>You have mail.</screen>
+ </para></entry>
+ </row>
+
+ <row>
+ <entry>What you type, when contrasted with on-screen computer
+ output.</entry>
+
+ <entry><screen>&prompt.user; <userinput>su</userinput>
+Password:</screen></entry>
+ </row>
+
+ <row>
+ <entry>Manual page references.</entry>
+
+ <entry>Use <citerefentry>
+ <refentrytitle>su</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> to change user names.</entry>
+ </row>
+
+ <row>
+ <entry>User and group names</entry>
+
+ <entry>Only <username>root</username> can do this.</entry>
+ </row>
+
+ <row>
+ <entry>Emphasis</entry>
+
+ <entry>You <emphasis>must</emphasis> do this.</entry>
+ </row>
+
+ <row>
+ <entry>Command line variables; replace with the real name or
+ variable.</entry>
+
+ <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry>
+ </row>
+
+ <row>
+ <entry>Environment variables</entry>
+
+ <entry><envar>$HOME</envar> is your home directory.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+ <sect1>
+ <title>Notes, warnings, and examples</title>
+
+ <para>Within the text appear notes, warnings, and examples.</para>
+
+ <note>
+ <para>Notes are represented like this, and contain information that
+ you should take note of, as it may affect what you do.</para>
+ </note>
+
+ <warning>
+ <para>Warnings are represented like this, and contain information
+ warning you about possible damage if you do not follow the
+ instructions. This damage may be physical, to your hardware or to
+ you, or it may be non-physical, such as the inadvertant deletion of
+ important files.</para>
+ </warning>
+
+ <example>
+ <title>A sample example</title>
+
+ <para>Examples are represented like this, and typically contain
+ examples you should walk through, or show you what the results of a
+ particular action should be.</para>
+ </example>
+ </sect1>
+
+ <sect1>
+ <title>Acknowledgments</title>
+
+ <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter
+ Flynn, and Christopher Maden, who took the time to read early drafts
+ of this document and offer many valuable comments and
+ criticisms.</para>
+ </sect1>
+ </preface>
+
+ &chap.overview;
+ &chap.sgml-primer;
+ &chap.tools;
+ &chap.sgml-markup;
+ &chap.stylesheets;
+ &chap.the-faq;
+ &chap.the-handbook;
+ &chap.the-website;
+ &chap.writing-style;
+ &chap.psgml-mode;
+ &chap.see-also;
+
+</book>
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ End:
+-->
diff --git a/en_US.ISO8859-1/books/fdp-primer/chapter.decl b/en_US.ISO8859-1/books/fdp-primer/chapter.decl
new file mode 100644
index 0000000000..494cb2946d
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/chapter.decl
@@ -0,0 +1 @@
+<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN">
diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
new file mode 100644
index 0000000000..974039f391
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
@@ -0,0 +1,22 @@
+<!--
+ Creates entities for each chapter in the Documentation Project Primer.
+ Each entity is named chap.foo, where foo is the value of the id
+ attribute on that chapter, and corresponds to the name of the
+ directory in which that chapter's .sgml file is stored.
+
+ Chapters should be listed in the order in which they are referenced.
+
+ $Id: chapters.ent,v 1.1 1999-04-20 20:59:49 nik Exp $
+-->
+
+<!ENTITY chap.overview SYSTEM "overview/chapter.sgml">
+<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml">
+<!ENTITY chap.tools SYSTEM "tools/chapter.sgml">
+<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml">
+<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml">
+<!ENTITY chap.the-faq SYSTEM "the-faq/chapter.sgml">
+<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml">
+<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml">
+<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml">
+<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml">
+<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml">
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
new file mode 100644
index 0000000000..84fef1dc71
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
@@ -0,0 +1,89 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="overview">
+ <title>Overview</title>
+
+ <para>Welcome to the FreeBSD Documentation Project, and thank you for
+ volunteering. One of the keys to the success of a project such as FreeBSD
+ is the availability of good quality documentation, and your contribution
+ will help that success.</para>
+
+ <para>After you have read this primer you should;</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Have an understanding of the text formats used by the
+ Documentation Project, and why they were chosen.</para>
+ </listitem>
+
+ <listitem>
+ <para>Be able to read and understand the source code for the Handbook,
+ FAQ, and website, and follow how they are converted into HTML,
+ PostScript, and other formats.</para>
+ </listitem>
+
+ <listitem>
+ <para>Be able to make changes to the documentation, test them, and
+ either contribute them back to the project or (if you have commit
+ privileges) commit them.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This primer assumes that you already understand;</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>How to maintain an up-to-date copy of the FreeBSD CVS tree using
+ CVS and one of CVSup or CTM, and how to check out particular versions
+ of files.</para>
+
+ <para>Alternatively, how to retrieve versions of files using the
+ <application>CVSWeb</application> interface.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to use the ports system to download and install new
+ software.</para>
+ </listitem>
+ </itemizedlist>
+</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/psgml-mode/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml
new file mode 100644
index 0000000000..5208c5f016
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml
@@ -0,0 +1,148 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="psgml-mode">
+ <title>Using <literal>sgml-mode</literal> with
+ <application>Emacs</application></title>
+
+ <para>Recent versions of Emacs or Xemacs (available from the ports
+ collection) contain a very useful package called PSGML. Automatically
+ invoked when a file with <filename>.sgml</filename> extension is loaded,
+ or by typing <command>M-x sgml-mode</command>, it is a major mode for
+ dealing with SGML files, elements and attributes.</para>
+
+ <para>An understanding of some of the commands provided by this mode can
+ make working with SGML documents such as the Handbook much easier.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><command>C-c C-e</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-insert-element</literal>. You will be
+ prompted for the name of the element to insert at the current point.
+ You can use the TAB key to complete the element. Elements that are
+ not valid at the current point will be disallowed.</para>
+
+ <para>The start and end tags for the element will be inserted. If the
+ element contains other, mandatory, elements then these will be
+ inserted as well.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>C-c =</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-change-element-name</literal>. Place the
+ point within an element and run this command. You will be prompted
+ for the name of the element to change to. Both the start and end
+ tags of the current element will be changed to the new
+ element.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>C-c C-r</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-tag-region</literal>. Select some text (move
+ to start of text, C-space, move to end of text, C-space) and then
+ run this command. You will be prompted for the element to use. This
+ element will then be inserted immediately before and after your
+ marked region.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>C-c -</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-untag-element</literal>. Place the point
+ within the start or end tag of an element you want to remove, and
+ run this command. The element's start and end tags will be
+ removed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>C-c C-q</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-fill-element</literal>. Will recursively fill
+ (i.e., reformat) content from the current element in. The filling
+ <emphasis>will</emphasis> affect content in which whitespace is
+ significant, such as within <sgmltag>programlisting</sgmltag>
+ elements, so run this command with care.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>C-c C-a</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-edit-attributes</literal>. Opens a second
+ buffer containing a list of all the attributes for the closest
+ enclosing element, and their current values. Use TAB to navigate
+ between attributes, <command>C-k</command> to remove an existing
+ value and replace it with a new one, <command>C-c</command> to close
+ this buffer and return to the main document.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>C-c C-v</command></term>
+
+ <listitem>
+ <para>Runs <literal>sgml-validate</literal>. Prompts you to save the
+ current document (if necessary) and then runs an SGML validator. The
+ output from the validator is captured into a new buffer, and you can
+ then navigate from one troublespot to the next, fixing markup errors
+ as you go.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Doubtless there are other useful functions of this mode, but those are
+ the ones I use most often.</para>
+</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/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
new file mode 100644
index 0000000000..eaecab8f99
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
@@ -0,0 +1,119 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="see-also">
+ <title>See Also</title>
+
+ <para>This document is deliberately not an exhaustive discussion of SGML,
+ the DTDs listed, and the FreeBSD Documentation Project. For more
+ information about these, you are encouraged to see the following web
+ sites.</para>
+
+ <sect1>
+ <title>The FreeBSD Documentation Project</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.freebsd.org/docproj/">The FreeBSD
+ Documentation Project web pages</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://www.freebsd.org/handbook/">The FreeBSD Handbook</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>SGML</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web
+ page</ulink>, a comprehensive SGML resource</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG'>Gentle introduction to SGML</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>HTML</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.w3.org/">The World Wide Web
+ organisation</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0
+ specification</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>DocBook</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.oreilly.com/davenport/">The Davenport
+ Group</ulink>, maintainers of the DocBook DTD</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>The Linux Documentation Project</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://metalab.unc.edu/LDP/">The Linux Documentation
+ Project web pages</ulink></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:
+-->
+
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
new file mode 100644
index 0000000000..e749463375
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -0,0 +1,2210 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="sgml-markup">
+ <title>SGML Markup</title>
+
+ <para>This chapter describes the three markup languages you will encounter
+ when you contribute to the FreeBSD documentation project. Each section
+ describes the markup language, and details the markup that you are likely
+ to want to use, or that is already in use.</para>
+
+ <para>These markup languages contain a large number of elements, and it can
+ be confusing sometimes to know which element to use for a particular
+ situation. This section goes through the elements you are most likely to
+ need, and gives examples of how you would use them.</para>
+
+ <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
+ that would just reiterate the documentation for each language. The aim of
+ this section is to list those elements more likely to be useful to you. If
+ you have a question about how best to markup a particular piece of
+ content, please post it to the FreeBSD Documentation Project mailing list
+ <email>freebsd-doc@freebsd.org</email>.</para>
+
+ <note>
+ <title>Inline vs. block</title>
+
+ <para>In the remainder of this document, when describing elements,
+ <emphasis>inline</emphasis> means that the element can occur within a
+ block element, and does not cause a line break. A
+ <emphasis>block</emphasis> element, by comparison, will cause a line
+ break (and other processing) when it is encountered.</para>
+ </note>
+
+ <sect1>
+ <title>HTML</title>
+
+ <para>HTML, the HyperText Markup Language, is the markup language of
+ choice on the World Wide Web. More information can be found at
+ &lt;URL:<ulink
+ url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</para>
+
+ <para>HTML is used to markup pages on the FreeBSD web site. It should not
+ (generally) be used to mark up other documention, since DocBook offers a
+ far richer set of elements to choose from. Consequently, you will
+ normally only encounter HTML pages if you are writing for the web
+ site.</para>
+
+ <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
+ latest, 4.0 (available in both <emphasis>strict</emphasis> and
+ <emphasis>loose</emphasis> variants).</para>
+
+ <para>The HTML DTDs are available from the ports collection in the
+ <filename>textproc/html</filename> port. They are automatically
+ installed as part of the <filename>textproc/docproj</filename> port.</para>
+
+ <sect2>
+ <title>Formal Public Identifier (FPI)</title>
+
+ <para>There are a number of HTML FPIs, depending upon the version (also
+ known as the level) of HTML that you want to declare your document to
+ be compliant with.</para>
+
+ <para>The majority of HTML documents on the FreeBSD web site comply with
+ the loose version of HTML 4.0.</para>
+
+ <programlisting>
+PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Sectional elements</title>
+
+ <para>An HTML document is normally split in to two sections. The first
+ section, called the <emphasis>head</emphasis>, contains
+ meta-information about the document, such as its title, the name of
+ the author, the parent document, and so on. The second section, the
+ <emphasis>body</emphasis>, contains the content that will be displayed
+ to the user.</para>
+
+ <para>These sections are indicated with <sgmltag>head</sgmltag> and
+ <sgmltag>body</sgmltag> elements respectively. These elements are
+ contained within the top-level <sgmltag>html</sgmltag> element.</para>
+
+ <example>
+ <title>Normal HTML document structure</title>
+
+ <programlisting>
+&lt;html>
+ &lt;head>
+ &lt;title><replaceable>The document's title</replaceable>&lt;/title>
+ &lt;/head>
+
+ &lt;body>
+
+ &hellip;
+
+ &lt;/body>
+&lt;/html></programlisting>
+ </example>
+ </sect2>
+
+ <sect2>
+ <title>Block elements</title>
+
+ <sect3>
+ <title>Headings</title>
+
+ <para>HTML allows you to denote headings in your document, at up to
+ six different levels.</para>
+
+ <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>,
+ then <sgmltag>h2</sgmltag>, continuing down to
+ <sgmltag>h6</sgmltag>.</para>
+
+ <para>The element's content is the text of the heading.</para>
+
+ <example>
+ <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<h1>First section</h1>
+
+<!-- Document introduction goes here -->
+
+<h2>This is the heading for the first section</h2>
+
+<!-- Content for the first section goes here -->
+
+<h3>This is the heading for the first sub-section</h3>
+
+<!-- Content for the first sub-section goes here -->
+
+<h2>This is the heading for the second section</h2>
+
+<!-- Content for the second section goes here -->]]></programlisting>
+ </example>
+
+ <para>Generally, an HTML page should have one first level heading
+ (<sgmltag>h1</sgmltag>). This can contain many second level headings
+ (<sgmltag>h2</sgmltag>), which can in turn contain many third level
+ headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag>
+ element should have the same element, but one further up the
+ hierarchy, preceeding it. Leaving gaps in the numbering is to be
+ avoided.</para>
+
+ <example>
+ <title>Bad ordering of
+ <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<h1>First section</h1>
+
+<!-- Document introduction -->
+
+<h3>Sub-section</h3>
+
+<!-- This is bad, <h2> has been left out -->]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Paragraphs</title>
+
+ <para>HTML supports a single paragraph element,
+ <sgmltag>p</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>p</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>This is a paragraph. It can contain just about any
+ other element.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Block quotations</title>
+
+ <para>A block quotation is an extended quotation from another document
+ that should not appear within the current paragraph.</para>
+
+ <example>
+ <title><sgmltag>blockquote</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>A small excerpt from the US Constitution;</p>
+
+<blockquote>We the People of the United States, in Order to form
+ a more perfect Union, establish Justice, insure domestic
+ Tranquility, provide for the common defence, promote the general
+ Welfare, and secure the Blessings of Liberty to ourselves and our
+ Posterity, do ordain and establish this Constitution for the
+ United States of America.</blockquote>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Lists</title>
+
+ <para>You can present the user with three types of lists, ordered,
+ unordered, and definition.</para>
+
+ <para>Typically, each entry in an ordered list will be numbered, while
+ each entry in an unordered list will be proceeded by a bullet
+ point. Definition lists are composed of two sections for each
+ entry. The first section is the term being defined, and the second
+ section is the definition of the term.</para>
+
+ <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
+ element, unordered lists by the <sgmltag>ul</sgmltag> element, and
+ definition lists by the <sgmltag>dl</sgmltag> element.</para>
+
+ <para>Ordered and unordered lists contain listitems, indicated by the
+ <sgmltag>li</sgmltag> element. A listitem can contain textual
+ content, or it may be further wrapped in one or more
+ <sgmltag>p</sgmltag> elements.</para>
+
+ <para>Definition lists contain definition terms
+ (<sgmltag>dt</sgmltag>) and definition descriptions
+ (<sgmltag>dd</sgmltag>). A definition term can only contain inline
+ elements. A definition description can contain other block
+ elements.</para>
+
+ <example>
+ <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>An unordered list. Listitems will probably be
+ preceeded by bullets.</p>
+
+<ul>
+ <li>First item</li>
+
+ <li>Second item</li>
+
+ <li>Third item</li>
+</ul>
+
+<p>An ordered list, with list items consisting of multiple
+ paragraphs. Each item (note: not each paragraph) will be
+ numbered.</p>
+
+<ol>
+ <li><p>This is the first item. It only has one paragraph.</p></li>
+
+ <li><p>This is the first paragraph of the second item.</p>
+
+ <p>This is the second paragraph of the second item.</p></li>
+
+ <li><p>This is the first and only paragraph of the third
+ item.</p></li>
+</ol>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Definition lists with <sgmltag>dl</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<dl>
+ <dt>Term 1</dt>
+
+ <dd><p>Paragraph 1 of definition 1.</p></dd>
+
+ <p>Paragraph 2 of definition 1.</p></dd>
+
+ <dt>Term 2</dt>
+
+ <dd><p>Paragraph 1 of definition 2.</p></dd>
+
+ <dt>Term 3</dt>
+
+ <dd>Paragraph 1 of definition 3. Note that the &lt;p&gt;
+ element is not required in the single paragraph case.</dd>
+</dl>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Pre-formatted text</title>
+
+ <para>You can indicate that text should be shown to the user exactly
+ as it is in the file. Typically, this means that the text is shown
+ in a fixed font, multiple spaces are not merged in to one, and line
+ breaks in the text are significant.</para>
+
+ <para>In order to do this, wrap the content in the
+ <sgmltag>pre</sgmltag> element.</para>
+
+ <example>
+ <title><sgmltag>pre</sgmltag></title>
+
+ <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
+ message;</para>
+
+ <programlisting>
+<![ CDATA [<pre>
+ From: nik@freebsd.org
+ To: freebsd-doc@freebsd.org
+ Subject: New documentation available
+
+ There's a new copy of my primer for contributers to the FreeBSD
+ Documentation Project available at
+
+ <URL:http://www.freebsd.org/~nik/primer/index.html>
+
+ Comments appreciated.
+
+ N
+</pre>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Tables</title>
+
+ <note>
+ <para>Most text-mode browsers (such as Lynx) do not render tables
+ particularly effectively. If you are relying on the tabular
+ display of your content, you should consider using alternative
+ markup to prevent confusion.</para>
+ </note>
+
+ <para>Mark up tabular information using the <sgmltag>table</sgmltag>
+ element. A table consists of one or more table rows
+ (<sgmltag>tr</sgmltag>), each containing one or more cells of table
+ data (<sgmltag>td</sgmltag>). Each cell can contain other block
+ elements, such as paragraphs or lists. It can also contain another
+ table (this nesting can repeat indefinitely). If the cell only
+ contains one paragraph then you do not need to include the
+ <sgmltag>p</sgmltag> element.</para>
+
+ <example>
+ <title>Simple use of <sgmltag>table</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>This is a simple 2x2 table.</p>
+
+<table>
+ <tr>
+ <td>Top left cell</td>
+
+ <td>Top right cell</td>
+ </tr>
+
+ <tr>
+ <td>Bottom left cell</td>
+
+ <td>Bottom right cell</td>
+ </tr>
+</table>]]></programlisting></example>
+
+ <para>A cell can span multiple rows and columns. To indicate this, add
+ the <literal>rowspan</literal> and/or <literal>colspan</literal>
+ attributes, with values indicating the number of rows of columns
+ that should be spanned.</para>
+
+ <example>
+ <title>Using <literal>rowspan</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>One tall thin cell on the left, two short cells next to
+ it on the right.</p>
+
+<table>
+ <tr>
+ <td rowspan="2">Long and thin</td>
+ </tr>
+
+ <tr>
+ <td>Top cell</td>
+
+ <td>Bottom cell</td>
+ </tr>
+</table>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Using <literal>colspan</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>One long cell on top, two short cells below it.</p>
+
+<table>
+ <tr>
+ <td colspan="2">Top cell</td>
+ </tr>
+
+ <tr>
+ <td>Bottom left cell</td>
+
+ <td>Bottom right cell</td>
+ </tr>
+</table>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Using <literal>rowspan</literal> and
+ <literal>colspan</literal> together</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
+ cells merged in to one. The other cells are normal.</p>
+
+<table>
+ <tr>
+ <td colspan="2" rowspan="2">Top left large cell</td>
+
+ <td>Top right cell</td>
+ </tr>
+
+ <tr>
+ <!-- Because the large cell on the left merges in to
+ this row, the first <td> will occur on its
+ right -->
+
+ <td>Middle right cell</td>
+ </tr>
+
+ <tr>
+ <td>Bottom left cell</td>
+
+ <td>Bottom middle cell</td>
+
+ <td>Bottom right cell</td>
+ </tr>
+</table>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>In-line elements</title>
+
+ <sect3>
+ <title>Emphasising information</title>
+
+ <para>You have two levels of emphasis available in HTML,
+ <sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal
+ level of emphasis and <sgmltag>strong</sgmltag> indicates stronger
+ emphasis.</para>
+
+ <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
+ <sgmltag>strong</sgmltag> is rendered in bold. This is not always
+ the case however, and you should not rely on it.</para>
+
+ <example>
+ <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p><em>This</em> has been emphasised, while
+ <strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Bold and italics</title>
+
+ <para>Because HTML includes presentational markup, you can also
+ indicate that particular content should be rendered in bold or
+ italic. The elements are <sgmltag>b</sgmltag> and
+ <sgmltag>i</sgmltag> respectively.</para>
+
+ <example>
+ <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
+
+ <programlisting>
+<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
+ in italics.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Indicating fixed pitch text</title>
+
+ <para>If you have content that should be rendered in a fixed pitch
+ (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
+ &ldquo;teletype&rdquo;).</para>
+
+ <example>
+ <title><sgmltag>tt</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>This document was originally written by
+ Nik Clayton, who can be reached by e-mail as
+ <tt>nik@freebsd.org</tt>.</p>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Content size</title>
+
+ <para>You can indicate that content should be shown in a larger or
+ smaller font. There are three ways of doing this.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag>
+ around the content you wish to change size. These tags can be
+ nested, so <literal>&lt;big&gt;&lt;big&gt;This is much
+ bigger&lt;/big&gt;&lt;/big&gt;</literal> is possible.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
+ attribute set to <literal>+1</literal> or <literal>-1</literal>
+ respectively. This has the same effect as using
+ <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the
+ use of this approach is deprecated.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
+ attribute set to a number between 1 and 7. The default font size
+ is <literal>3</literal>. This approach is deprecated.</para>
+ </listitem>
+ </orderedlist>
+
+ <example>
+ <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
+ <sgmltag>font</sgmltag></title>
+
+ <para>The following fragments all do the same thing.</para>
+
+ <programlisting>
+<![ CDATA [<p>This text is <small>slightly smaller</small>. But
+ this text is <big>slightly bigger</big>.</p>
+
+<p>This text is <font size="-1">slightly smaller</font>. But
+ this text is <font size="+1">slightly bigger</font.</p>
+
+<p>This text is <font size="2">slightly smaller</font>. But
+ this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Links</title>
+
+ <note>
+ <para>Links are also in-line elements.</para>
+ </note>
+
+ <sect3>
+ <title>Linking to other documents on the WWW</title>
+
+ <para>In order to include a link to another document on the WWW you
+ must know the URL of the document you want to link to.</para>
+
+ <para>The link is indicated with <sgmltag>a</sgmltag>, and the
+ <literal>href</literal> attribute contains the URL of the target
+ document. The content of the element becomes the link, and is
+ normally indicated to the user in some way (underlining, change of
+ colour, different mouse cursor when over the link, and so on).</para>
+
+ <example>
+ <title>Using <literal>&lt;a href="..."&gt;</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p>More information is available at the
+ <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting>
+ </example>
+
+ <para>These links will take the user to the top of the chosen
+ document.</para>
+ </sect3>
+
+ <sect3>
+ <title>Linking to other parts of documents</title>
+
+ <para>Linking to a point within another document (or within the same
+ document) requires that the document author include anchors that you
+ can link to.</para>
+
+ <para>Anchors are indicated with <sgmltag>a</sgmltag> and the
+ <literal>name</literal> attribute instead of
+ <literal>href</literal>.</para>
+
+ <example>
+ <title>Using <literal>&lt;a name="..."&gt;</literal></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
+ in other links with the name <tt>para1</tt>.</p>]]></programlisting>
+ </example>
+
+ <para>To link to a named part of a document, write a normal link to
+ that document, but include the name of the anchor after a
+ <literal>#</literal> symbol.</para>
+
+ <example>
+ <title>Linking to a named part of another document</title>
+
+ <para>Assume that the <literal>para1</literal> example resides in a
+ document called <filename>foo.html</filename>.</para>
+
+ <programlisting>
+<![ CDATA [<p>More information can be found in the
+ <a href="foo.html#para1">first paragraph</a> of
+ <tt>foo.html</tt>.</p>]]></programlisting>
+ </example>
+
+ <para>If you are linking to a named anchor within the same document
+ then you can omit the document's URL, and just include the name of
+ the anchor (with the preceeding <literal>#</literal>).</para>
+
+ <example>
+ <title>Linking to a named part of another document</title>
+
+ <para>Assume that the <literal>para1</literal> example resides in
+ this document</para>
+
+ <programlisting>
+<![ CDATA [<p>More information can be found in the
+ <a href="#para1">first paragraph</a> of this
+ document.</p>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>DocBook</title>
+
+ <para>DocBook was designed by the <ulink
+ url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be
+ a DTD for writing technical documentation. As such, and unlike LinuxDoc
+ and HTML, DocBook is very heavily orientated towards markup that
+ describes <emphasis>what</emphasis> something is, rather than describing
+ <emphasis>how</emphasis> it should be presented.</para>
+
+ <note>
+ <title><literal>formal</literal> vs. <literal>informal</literal></title>
+
+ <para>Some elements may exist in two forms, <emphasis>formal</emphasis>
+ and <emphasis>informal</emphasis>. Typically, the formal version of
+ the element will consist of a title followed by the information
+ version of the element. The informal version will not have a
+ title.</para>
+ </note>
+
+ <para>The DocBook DTD is available from the ports collection in the
+ <filename>textproc/docbook</filename> port. It is automatically
+ installed as part of the <filename>textproc/docproj</filename>
+ port.</para>
+
+ <sect2>
+ <title>FreeBSD extensions</title>
+
+ <para>The FreeBSD Documentation Project has extended the DocBook DTD by
+ adding some new elements. These elements serve to make some of the
+ markup more precise.</para>
+
+ <para>Where a FreeBSD specific element is listed below it is clearly
+ marked.</para>
+
+ <para>Throughout the rest of this document, the term
+ &ldquo;DocBook&rdquo; is used to mean the FreeBSD extended DocBook
+ DTD.</para>
+
+ <note>
+ <para>There is nothing about these extensions that is FreeBSD
+ specific, it was just felt that they were useful enhancements for
+ this particular project. Should anyone from any of the other *nix
+ camps (NetBSD, OpenBSD, Linux, &hellip;) be interested in
+ collaborating on a standard DocBook extension set, please get in
+ touch with Nik Clayton <email>nik@freebsd.org</email>.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Formal Public Identifier (FPI)</title>
+
+ <para>In compliance with the DocBook guidelines for writing FPIs for
+ DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
+ is;</para>
+
+ <programlisting>
+PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Sectional elements</title>
+
+ <para>DocBook contains a number of elements for marking up the structure
+ of a book.</para>
+
+ <para>Generally, the top level (first) element will be
+ <sgmltag>book</sgmltag>.</para>
+
+ <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a
+ mandatory requirement. There may be <sgmltag>part</sgmltag>s between
+ the book and the chapter to provide another layer of organisation. The
+ Handbook is arranged in this way.</para>
+
+ <para>A chapter may (or may not) contain one or more sections. These are
+ indicated with the <sgmltag>sect1</sgmltag> element. If a section
+ contains another section then use the <sgmltag>sect2</sgmltag>
+ element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
+
+ <para>Chapters and sections contain the remainder of the content.</para>
+
+ <sect3>
+ <title>Starting a book</title>
+
+ <para>The content of the book is contained within the
+ <sgmltag>book</sgmltag> element. As well as containing structural
+ markup, this element can contain elements that include additional
+ information about the book. This is either meta-information, used
+ for reference purposes, or additional content used to produce a
+ title page.</para>
+
+ <para>This additional information should be contained within
+ <sgmltag>bookinfo</sgmltag>.</para>
+
+ <example>
+ <title>Boilerplate <sgmltag>book</sgmltag> with
+ <sgmltag>bookinfo</sgmltag></title>
+
+ <!-- Can't put this in a marked section because of the
+ replaceable elements -->
+ <programlisting>
+&lt;book>
+ &lt;bookinfo>
+ &lt;title><replaceable>Your title here</replaceable>&lt;/title>
+
+ &lt;author>
+ &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
+ &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
+ &lt;affiliation>
+ &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
+ &lt;/affiliation>
+ &lt;/author>
+
+ &lt;copyright>
+ &lt;year><replaceable>1998</replaceable>&lt;/year>
+ &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
+ &lt;/copyright>
+
+ &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
+
+ &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
+
+ &lt;abstract>
+ &lt;para><replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para>
+ &lt;/abstract>
+ &lt;/bookinfo>
+
+ &hellip;
+
+&lt;/book></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Indicating chapters</title>
+
+ <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each
+ chapter has a mandatory <sgmltag>title</sgmltag>.</para>
+
+ <example>
+ <title>A simple chapter</title>
+
+ <programlisting>
+<![ CDATA [<chapter>
+ <title>The chapter's title</title>
+
+ ...
+</chapter>]]></programlisting>
+ </example>
+
+ <para>A chapter can not be empty, it must contain elements in addition
+ to <sgmltag>title</sgmltag>. If you need to include an empty chapter
+ then just use an empty paragraph.</para>
+
+ <example>
+ <title>Empty chapters</title>
+
+ <programlisting>
+<![ CDATA [<chapter>
+ <title>This is an empty chapter</title>
+
+ <para></para>
+</chapter>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Sections below chapters</title>
+
+ <para>Chapters can be broken up into sections, subsections, and so
+ on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag>
+ element. The <replaceable>n</replaceable> indicates the section
+ number, which identifies the section level.</para>
+
+ <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is
+ <sgmltag>sect1</sgmltag>. You can have one or more of these in a
+ chapter. They can contain one or more <sgmltag>sect2</sgmltag>
+ elements, and so on, down to <sgmltag>sect5</sgmltag>.</para>
+
+ <example>
+ <title>Sections in chapters</title>
+
+ <programlisting>
+<![ CDATA [<chapter>
+ <title>A sample chapter</title>
+
+ <para>Some text in the chapter.</para>
+
+ <sect1>
+ <title>First section (1.1)</title>
+
+ ...
+ </sect1>
+
+ <sect1>
+ <title>Second section (1.2)</title>
+
+ <sect2>
+ <title>First sub-section (1.2.1)</title>
+
+ <sect3>
+ <title>First sub-sub-section (1.2.1.1)</title>
+
+ ...
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Second sub-section (1.2.2)</title>
+
+ ...
+ </sect2>
+ </sect1>
+</chapter>]]></programlisting>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Subdividing using <sgmltag>part</sgmltag>s</title>
+
+ <para>You can introduce another layer of organisation between
+ <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
+ more <sgmltag>part</sgmltag>s.</para>
+
+ <programlisting>
+<![ CDATA [<part>
+ <title>Introduction</title>
+
+ <chapter>
+ <title>Overview</title>
+
+ ...
+ </chapter>
+
+ <chapter>
+ <title>What is FreeBSD?</title>
+
+ ...
+ </chapter>
+
+ <chapter>
+ <title>History</title>
+
+ ...
+ </chapter>
+</part>]]></programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Block elements</title>
+
+ <sect3>
+ <title>Paragraphs</title>
+
+ <para>DocBook supports three types of paragraphs;
+ <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
+ <sgmltag>simpara</sgmltag>.</para>
+
+ <para>Most of the time you will only need to use
+ <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a
+ <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag>
+ disallows some elements from within <sgmltag>para</sgmltag>. Stick
+ with <sgmltag>para</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>para</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>This is a paragraph. It can contain just about any
+ other element.</para> ]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>This is a paragraph. It can contain just about any other
+ element.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Block quotations</title>
+
+ <para>A block quotation is an extended quotation from another document
+ that should not appear within the current paragraph. You will
+ probably only need it infrequently.</para>
+
+ <para>Blockquotes can optionally contain a title and an attribution
+ (or they can be left untitled and unattributed).</para>
+
+ <example>
+ <title><sgmltag>blockquote</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>A small excerpt from the US Constitution;</para>
+
+<blockquote>
+ <title>Preamble to the Constitution of the United States</para>
+
+ <attribution>Copied from a web site somewhere</attribution>
+
+ <para>We the People of the United States, in Order to form a more perfect
+ Union, establish Justice, insure domestic Tranquility, provide for the
+ common defence, promote the general Welfare, and secure the Blessings
+ of Liberty to ourselves and our Posterity, do ordain and establish this
+ Constitution for the United States of America.</para>
+</blockquote>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <blockquote>
+ <title>Preamble to the Constitution of the United States</title>
+
+ <attribution>Copied from a web site somewhere</attribution>
+
+ <para>We the People of the United States, in Order to form a more
+ perfect Union, establish Justice, insure domestic Tranquility,
+ provide for the common defence, promote the general Welfare, and
+ secure the Blessings of Liberty to ourselves and our Posterity,
+ do ordain and establish this Constitution for the United States
+ of America.</para>
+ </blockquote>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Tips, notes, warnings, cautions, important information and
+ sidebars.</title>
+
+ <para>You may need to include extra information separate from the
+ main body of the text. Typically this is &ldquo;meta&rdquo;
+ information that the user should be aware of.</para>
+
+ <para>Depending on the nature of the information, one of
+ <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
+ <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
+ <sgmltag>important</sgmltag> should be used. Alternatively, if the
+ information is related to the main text but is not one of the above,
+ use <sgmltag>sidebar</sgmltag>.</para>
+
+ <para>The circumstances in which to choose one of these elements over
+ another is unclear. The DocBook documentation suggests;</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A Note is for information that should be heeded by all
+ readers.</para>
+ </listitem>
+
+ <listitem>
+ <para>An Important element is a variation on Note.</para>
+ </listitem>
+
+ <listitem>
+ <para>A Caution is for information regarding possible data loss
+ or software damage.</para>
+ </listitem>
+
+ <listitem>
+ <para>A Warning is for information regarding possible hardware
+ damage or injury to life or limb.</para>
+ </listitem>
+ </itemizedlist>
+
+ <example>
+ <title><sgmltag>warning</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<warning>
+ <para>Installing FreeBSD may make you want to delete Windows from your
+ harddisk.</para>
+</warning>]]></programlisting>
+ </example>
+
+ <!-- Need to do this outside of the example -->
+ <warning>
+ <para>Installing FreeBSD may make you want to delete Windows from
+ your harddisk.</para>
+ </warning>
+ </sect3>
+
+ <sect3>
+ <title>Lists and procedures</title>
+
+ <para>You will often need to list pieces of information to the user,
+ or present them with a number of steps that must be carried out in
+ order to accomplish a particular goal.</para>
+
+ <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>,
+ <sgmltag>orderedlist</sgmltag>, or
+ <sgmltag>procedure</sgmltag><footnote><para>There are other types of
+ list element in DocBook, but we're not concerned with those at
+ the moment.</para>
+ </footnote>
+ </para>
+
+ <para><sgmltag>itemizedlist</sgmltag> and
+ <sgmltag>orderedlist</sgmltag> are similar to the counterparts in
+ HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one
+ consists of one or more <sgmltag>listentry</sgmltag> elements, and
+ each <sgmltag>listentry</sgmltag> contains one or more block
+ elements. The <sgmltag>listentry</sgmltag> elements are analagous to
+ HTMLs <sgmltag>li</sgmltag> tags. However, unlike HTML they are
+ required.</para>
+
+ <para><sgmltag>procedure</sgmltag> is slightly different. It consists
+ of <sgmltag>step</sgmltag>s, which may in turn consists of more
+ <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each
+ <sgmltag>step</sgmltag> contains block elements.</para>
+
+ <example>
+ <title><sgmltag>itemizedlist</sgmltag>,
+ <sgmltag>orderedlist</sgmltag>, and
+ <sgmltag>procedure</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<itemizedlist>
+ <listitem>
+ <para>This is the first itemized item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second itemized item.</para>
+ </listitem>
+</itemizedlist>
+
+<orderedlist>
+ <listitem>
+ <para>This is the first ordered item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second ordered item.</para>
+ </listitem>
+</orderedlist>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>This is the first itemized item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second itemized item.</para>
+ </listitem>
+ </itemizedlist>
+
+ <orderedlist>
+ <listitem>
+ <para>This is the first ordered item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second ordered item.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Showing file samples</title>
+
+ <para>If you want to show a fragment of a file (or perhaps a complete
+ file) to the user, wrap it in the <sgmltag>programlisting</sgmltag>
+ element.</para>
+
+ <para>White space and line breaks within
+ <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
+ significant. In particular, this means that the closing tag should
+ appear on the same line as the last line of the output, otherwise a
+ spurious blank line will be included.</para>
+
+ <example>
+ <title><sgmltag>programlisting</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA[<para>When you have finished, your program should look like
+ this;</para>
+
+<programlisting>
+#include &lt;stdio.h&gt;
+
+int
+main(void)
+{
+ printf("hello, world\n");
+}</programlisting>]]></programlisting>
+
+ <para>Notice how the angle brackets in the
+ <literal>#include</literal> line need to be referenced by their
+ entities instead of being included literally.</para>
+
+ <para>Appearance:</para>
+
+ <para>When you have finished, your program should look like
+ this;</para>
+
+ <programlisting>
+#include &lt;stdio.h&gt;
+
+int
+main(void)
+{
+ printf("hello, world\n");
+}</programlisting>
+ </example>
+
+ <note>
+ <para>There is a mechanism within DocBook for referring to sections
+ of a previously occuring <sgmltag>programlisting</sgmltag>, called
+ callouts (see <sgmltag>programlistingco</sgmltag> for more
+ information). I don't fully understand (i.e., have never used)
+ this feature, so can't document it here. For the mean time, you
+ can include line numbers within the content, and then refer to
+ them later on in your description. That will change, as soon as I
+ find the time to understand and document callouts.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Tables</title>
+
+ <para>Unlike HTML, you do not need to use tables for layout purposes,
+ as the stylesheet handles those issues for you. Instead, just use
+ tables for marking up tabular data.</para>
+
+ <para>In general terms (and see the DocBook documentation for more
+ detail) a table (which can be either formal or informal) consists of
+ a <sgmltag>table</sgmltag> element. This contains at least one
+ <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
+ the number of columns in this table group. Within the tablegroup you
+ can then have one <sgmltag>thead</sgmltag> element, which contains
+ elements for the table headings (column headings), and one
+ <sgmltag>tbody</sgmltag> which contains the body of the
+ table.</para>
+
+ <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag>
+ contain <sgmltag>row</sgmltag> elements, which in turn contain
+ <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag>
+ element specifies one cell in the table.</para>
+
+ <example>
+ <title><sgmltag>informaltable</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>This is column head 1</entry>
+ <entry>This is column head 2</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Row 1, column 1</entry>
+ <entry>Row 1, column 2</entry>
+ </row>
+
+ <row>
+ <entry>Row 2, column 1</entry>
+ <entry>Row 2, column 2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>This is column head 1</entry>
+ <entry>This is column head 2</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Row 1, column 1</entry>
+ <entry>Row 1, column 2</entry>
+ </row>
+
+ <row>
+ <entry>Row 2, column 1</entry>
+ <entry>Row 2, column 2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </example>
+
+ <para>If you don't want a border around the table the
+ <literal>frame</literal> attribute can be added to the
+ <sgmltag>informaltable</sgmltag> element with a value of
+ <literal>none</literal> (i.e., <literal>&lt;informaltable
+ frame="none"&gt;</literal>).</para>
+
+ <example>
+ <title>Tables where <literal>frame="none"</literal></title>
+
+ <para>Appearance:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>This is column head 1</entry>
+ <entry>This is column head 2</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Row 1, column 1</entry>
+ <entry>Row 1, column 2</entry>
+ </row>
+
+ <row>
+ <entry>Row 2, column 1</entry>
+ <entry>Row 2, column 2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Examples for the user to follow</title>
+
+ <para>A lot of the time you need to show examples for the user to
+ follow. Typically, these will consist of dialogs with the computer;
+ the user types in a command, the user gets a response back, they
+ type in another command, and so on.</para>
+
+ <para>A number of distinct elements and entities come in to play
+ here.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><sgmltag>informalexample</sgmltag></term>
+
+ <listitem>
+ <para>Most of the time these examples will occur
+ &ldquo;mid-flow&rdquo; as it were, and you won't need to put a
+ title on them. So, most of the time, the outermost element
+ will be <sgmltag>informalexample</sgmltag>. For those times
+ when you do need to include a title on the example, use
+ <sgmltag>example</sgmltag>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><sgmltag>screen</sgmltag></term>
+
+ <listitem>
+ <para>Everything the user sees in this example will be on the
+ computer screen, so the next element is
+ <sgmltag>screen</sgmltag>.</para>
+
+ <para>Within <sgmltag>screen</sgmltag>, white space is
+ significant.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><sgmltag>prompt</sgmltag>,
+ <literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal></term>
+
+ <listitem>
+ <para>Some of the things the user will be seeing on the screen
+ are prompts from the computer (either from the OS, command
+ shell, or application. These should be marked up using
+ <sgmltag>prompt</sgmltag>.</para>
+
+ <para>As a special case, the two shell prompts for the normal
+ user and the root user have been provided as entities. Every
+ time you want to indicate the user is at a shell prompt, use
+ one of <literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal> as necessary. They do not
+ need to be inside <sgmltag>prompt</sgmltag>.</para>
+
+ <note>
+ <para><literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal> are FreeBSD
+ extensions to DocBook, and are not part of the original
+ DTD.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><sgmltag>userinput</sgmltag></term>
+
+ <listitem>
+ <para>When displaying text that the user should type in, wrap it
+ in <sgmltag>userinput</sgmltag> tags. It will probably be
+ displayed differently to the user.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title><sgmltag>informalexample</sgmltag>,
+ <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
+ <sgmltag>userinput</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<informalexample>
+ <screen>&prompt.user; <userinput>ls -1</userinput>
+foo1
+foo2
+foo3
+&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+foo2
+&prompt.user; <userinput>su</userinput>
+<prompt>Password: </prompt>
+&prompt.root; <userinput>cat foo2</userinput>
+This is the file called 'foo2'</screen>
+</informalexample>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>ls -1</userinput>
+foo1
+foo2
+foo3
+&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+foo2
+&prompt.user; <userinput>su</userinput>
+<prompt>Password: </prompt>
+&prompt.root; <userinput>cat foo2</userinput>
+This is the file called 'foo2'</screen>
+ </informalexample>
+ </example>
+
+ <note>
+ <para>Even though we are displaying the contents of the file
+ <filename>foo2</filename>, it is <emphasis>not</emphasis> marked
+ up as <sgmltag>programlisting</sgmltag>. Reserve
+ <sgmltag>programlisting</sgmltag> for showing fragments of files
+ outside the context of user actions.</para>
+ </note>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>In-line elements</title>
+
+ <sect3>
+ <title>Emphasising information</title>
+
+ <para>When you want to emphasise a particular word or phrase, use
+ <sgmltag>emphasis</sgmltag>. This may be presented as italic, or
+ bold, or might be spoken differently with a text-to-speech
+ system.</para>
+
+ <para>There is no way to change the presentation of the emphasis
+ within your document, no equivalent of HTML's <sgmltag>b</sgmltag>
+ and <sgmltag>i</sgmltag>. If the information you are presenting is
+ important then consider presenting it in
+ <sgmltag>important</sgmltag> rather than
+ <sgmltag>emphasis</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>emphasis</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
+ premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix
+ like operating system for the Intel architecture.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Applications, commands, options, and cites</title>
+
+ <para>You will frequently want to refer to both applications and
+ commands when writing for the Handbook. The distinction between them
+ is simple; an application is the name for a suite (or possibly just
+ 1) of programs that fulfil a particular task. A command is the name
+ of a program that the user can run.</para>
+
+ <para>In addition, you will occasionally need to list one or more of
+ the options that a command might take.</para>
+
+ <para>Finally, you will often want to list a command with it's manual
+ section number, in the &ldquo;command(number)&rdquo; format so
+ common in Unix manuals.</para>
+
+ <para>Mark up application names with
+ <sgmltag>application</sgmltag>.</para>
+
+ <para>When you want to list a command with it's manual section number
+ (which should be most of the time) the DocBook element is
+ <sgmltag>citerefentry</sgmltag>. This will contain a further two
+ elements, <sgmltag>refentrytitle</sgmltag> and
+ <sgmltag>manvolnum</sgmltag>. The content of
+ <sgmltag>refentrytitle</sgmltag> is the name of the command, and the
+ content of <sgmltag>manvolnum</sgmltag> is the manual page
+ section.</para>
+
+ <para>This can be cumbersome to write, and so a series of <link
+ linkend="general-entities">general entities</link> have been
+ created to make this easier. Each entity takes the form
+ <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
+
+ <para>The file that contains these entities is in
+ <filename>doc/share/sgml/man-refs.ent</filename>, and can be
+ referred to using this FPI;</para>
+
+ <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
+
+ <para>Therefore, the introduction to your documentation will probably
+ look like this;</para>
+
+ <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
+
+&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
+%man;
+
+&hellip;
+
+]]&gt;</programlisting>
+
+ <para>Use <sgmltag>command</sgmltag> when you want to include a
+ command name &ldquo;in-line&rdquo; but present it as something the
+ user should type in.</para>
+
+ <para>Use <sgmltag>option</sgmltag> to mark up a command's
+ options.</para>
+
+ <para>This can be confusing, and sometimes the choice is not always
+ clear. Hopefully this example makes it clearer.</para>
+
+ <example>
+ <title>Applications, commands, and options.</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para><application>Sendmail</application> is the most
+ widely used Unix mail application.</para>
+
+<para><application>Sendmail</application> includes the
+ <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, &amp;man.sendmail.8;, and &man.newaliases.8;
+ programs.</para>
+
+<para>One of the command line parameters to <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, <option>-bp</option>, will display the current
+ status of messages in the mail queue. Check this on the command
+ line by running <command>sendmail -bp</command>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para><application>Sendmail</application> is the most widely used
+ Unix mail application.</para>
+
+ <para><application>Sendmail</application> includes the
+ <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, <citerefentry>
+ <refentrytitle>mailq</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, and <citerefentry>
+ <refentrytitle>newaliases</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry> programs.</para>
+
+ <para>One of the command line parameters to <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, <option>-bp</option>, will display the current
+ status of messages in the mail queue. Check this on the command
+ line by running <command>sendmail -bp</command>.</para>
+ </example>
+
+ <note>
+ <para>Notice how the
+ <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Files, directories, extensions</title>
+
+ <para>Whenever you wish to refer to the name of a file, a directory,
+ or a file extension, use <sgmltag>filename</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>filename</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>The SGML source for the Handbook in English can be
+ found in <filename>/usr/doc/en/handbook/</filename>. The first
+ file is called <filename>handbook.sgml</filename> in that
+ directory. You should also see a <filename>Makefile</filename>
+ and a number of files with a <filename>.ent</filename>
+ extension.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The SGML source for the Handbook in English can be found in
+ <filename>/usr/doc/en/handbook/</filename>. The first file is
+ called <filename>handbook.sgml</filename> in that directory. You
+ should also see a <filename>Makefile</filename> and a number of
+ files with a <filename>.ent</filename> extension.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Devices</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>When referring to devices you have two choices. You can either
+ refer to the device as it appears in <filename>/dev</filename>, or
+ you can use the name of the device as it appears in the kernel. For
+ this latter course, use <sgmltag>devicename</sgmltag>.</para>
+
+ <para>Sometimes you will not have a choice. Some devices, such as
+ networking cards, do not have entries in <filename>/dev</filename>,
+ or the entries are markedly different from those entries.</para>
+
+ <example>
+ <title><sgmltag>devicename</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para><devicename>sio</devicename> is used for serial
+ communication in FreeBSD. <devicename>sio</devicename> manifests
+ through a number of entries in <filename>/dev</filename>, including
+ <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
+
+<para>By contrast, the networking devices, such as
+ <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.
+
+<para>In MS-DOS, the first floppy drive is referred to as
+ <devicename>a:</devicename>. In FreeBSD it is
+ <filename>/dev/fd0</filename>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para><devicename>sio</devicename> is used for serial communication
+ in FreeBSD. <devicename>sio</devicename> manifests through a
+ number of entries in <filename>/dev</filename>, including
+ <filename>/dev/ttyd0</filename> and
+ <filename>/dev/cuaa0</filename>.</para>
+
+ <para>By contrast, the networking devices, such as
+ <devicename>ed0</devicename> do not appear in
+ <filename>/dev</filename>.</para>
+
+ <para>In MS-DOS, the first floppy drive is referred to as
+ <devicename>a:</devicename>. In FreeBSD it is
+ <filename>/dev/fd0</filename>.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Hosts, domains, IP addresses, and so forth</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>You can markup identification information for networked
+ computers (hosts) in several ways, depending on the nature of the
+ information. All of them use <sgmltag>hostid</sgmltag> as the
+ element, with the <literal>role</literal> attribute selecting the
+ type of the marked up information.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>No role attribute, or
+ <literal>role="hostname"</literal></term>
+
+ <listitem>
+ <para>With no role attribute (i.e.,
+ <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the
+ marked up information is the simple hostname, such as
+ <literal>freefall</literal> or <literal>wcarchive</literal>.
+ You can explicitly specify this with
+ <literal>role="hostname"</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="domainname"</literal></term>
+
+ <listitem>
+ <para>The text is a domain name, such as
+ <literal>freebsd.org</literal> or
+ <literal>ngo.org.uk</literal>. There is no hostname
+ component.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="fqdn"</literal></term>
+
+ <listitem>
+ <para>The text is a Fully Qualified Domain Name, with both
+ hostname and domain name parts.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="ipaddr"</literal></term>
+
+ <listitem>
+ <para>The text is an IP address, probably expressed as a dotted
+ quad.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="netmask"</literal></term>
+
+ <listitem>
+ <para>The text is a network mask, which might be expressed as a
+ dotted quad, a hexadecimal string, or as a
+ <literal>/</literal> followed by a number.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="mac"</literal></term>
+
+ <listitem>
+ <para>The text is an ethernet MAC address, expressed as a series
+ of 2 digit hexadecimal numbers seperated by colons.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title><sgmltag>hostid</sgmltag> and roles</title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>The local machine can always be referred to by the
+ name <hostid>localhost</hostid>, which will have the IP address
+ <hostid role="ipaddr">127.0.0.1</hostid>.</para>
+
+<para>The <hostid role="domainname">freebsd.org</hostid> domain
+ contains a number of different hosts, including
+ <hostid role="fqdn">freefall.freebsd.org</hostid> and
+ <hostid role="fqdn">bento.freebsd.org</hostid>.</para>
+
+<para>When adding an IP alias to an interface (using
+ <command>ifconfig</command>) <emphasis>always</emphasis> use a
+ netmask of <hostid role="netmask">255.255.255.255</hostid>
+ (which can also be expressed as <hostid
+ role="netmask">0xffffffff</hostid>.</para>
+
+<para>The MAC address uniquely identifies every network card in
+ in existence. A typical MAC address looks like <hostid
+ role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The local machine can always be referred to by the name
+ <hostid>localhost</hostid>, which will have the IP address <hostid
+ role="ipaddr">127.0.0.1</hostid>.</para>
+
+ <para>The <hostid role="domainname">freebsd.org</hostid> domain
+ contains a number of different hosts, including <hostid
+ role="fqdn">freefall.freebsd.org</hostid> and <hostid
+ role="fqdn">bento.freebsd.org</hostid>.</para>
+
+ <para>When adding an IP alias to an interface (using
+ <command>ifconfig</command>) <emphasis>always</emphasis> use a
+ netmask of <hostid role="netmask">255.255.255.255</hostid> (which
+ can also be expressed as <hostid
+ role="netmask">0xffffffff</hostid>.</para>
+
+ <para>The MAC address uniquely identifies every network card in
+ existence. A typical MAC address looks like <hostid
+ role="mac">08:00:20:87:ef:d0</hostid>.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Usernames</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>When you need to refer to a specific username, such as
+ <literal>root</literal> or <literal>bin</literal>, use
+ <sgmltag>username</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>username</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>To carry out most system administration functions you
+ will need to be <username>root</username>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>To carry out most system administration functions you will
+ need to be <username>root</username>.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Describing <filename>Makefile</filename>s</title>
+
+ <note>
+ <title>FreeBSD extension</title>
+
+ <para>These elements are part of the FreeBSD extension to DocBook,
+ and do not exist in the original DocBook DTD.</para>
+ </note>
+
+ <para>Two elements exist to describe parts of
+ <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and
+ <sgmltag>makevar</sgmltag>.</para>
+
+ <para><sgmltag>maketarget</sgmltag> identifies a build target exported
+ by a <filename>Makefile</filename> that can be given as a parameter
+ to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a
+ variable that can be set (in the environment, on the
+ <command>make</command> command line, or within the
+ <filename>Makefile</filename>) to influence the process.</para>
+
+ <example>
+ <title><sgmltag>maketarget</sgmltag> and
+ <sgmltag>makevar</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>Two common targets in a <filename>Makefile</filename>
+ are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
+
+<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
+ application, and invoking <maketarget>clean</maketarget> will remove
+ the temporary files (<filename>.o</filename> for example) created by
+ the build process.</para>
+
+<para><maketarget>clean</maketarget> may be controlled by a number of
+ variables, including <makevar>CLOBBER</makevar> and
+ <makevar>RECURSE</makevar>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>Two common targets in a <filename>Makefile</filename> are
+ <maketarget>all</maketarget> and
+ <maketarget>clean</maketarget>.</para>
+
+ <para>Typically, invoking <maketarget>all</maketarget> will rebuild
+ the application, and invoking <maketarget>clean</maketarget> will
+ remove the temporary files (<filename>.o</filename> for example)
+ created by the build process.</para>
+
+ <para><maketarget>clean</maketarget> may be controlled by a number
+ of variables, including <makevar>CLOBBER</makevar> and
+ <makevar>RECURSE</makevar>.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Literal text</title>
+
+ <para>You will often need to include &ldquo;literal&rdquo; text in the
+ Handbook. This is text that is excerpted from another file, or which
+ should be copied from the Handbook into another file
+ verbatim.</para>
+
+ <para>Some of the time, <sgmltag>programlisting</sgmltag> will be
+ sufficient to denote this text. <sgmltag>programlisting</sgmltag> is
+ not always appropriate, particularly when you want to include a
+ portion of a file &ldquo;in-line&rdquo; with the rest of the
+ paragraph.</para>
+
+ <para>On these occasions, use <sgmltag>literal</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>literal</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel
+ configuration file determines the size of many system tables, and is
+ a rough guide to how many simultaneous logins the system will
+ support.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The <literal>maxusers 10</literal> line in the kernel
+ configuration file determines the size of many system tables, and
+ is a rough guide to how many simultaneous logins the system will
+ support.</para>
+ </example>
+ </sect3>
+
+ <sect3>
+ <title>Showing items that the user <emphasis>must</emphasis> fill
+ in</title>
+
+ <para>There will often be times when you want to show the user what to
+ do, or refer to a file, or command line, or similar, where the user
+ can not simply copy the examples that you provide, but must instead
+ include some information themselves.</para>
+
+ <para><sgmltag>replaceable</sgmltag> is designed for this eventuality.
+ Use it <emphasis>inside</emphasis> other elements to indicate parts
+ of that element's content that the user must replace.</para>
+
+ <example>
+ <title><sgmltag>replaceable</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<informalexample>
+ <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
+</informalexample>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
+ </informalexample>
+
+ <para><sgmltag>replaceable</sgmltag> can be used in many different
+ elements, including <sgmltag>literal</sgmltag>. This example also
+ shows that <sgmltag>replaceable</sgmltag> should only be wrapped
+ around the content that the user <emphasis>is</emphasis> meant to
+ provide. The other content should be left alone.</para>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal>
+ line in the kernel configuration file determines the size of many system
+ tables, and is a rough guide to how many simultaneous logins the system will
+ support.</para>
+
+<para>For a desktop workstation, <literal>32</literal> is a good value
+ for <replaceable>n</replaceable>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The <literal>maxusers <replaceable>n</replaceable></literal>
+ line in the kernel configuration file determines the size of many
+ system tables, and is a rough guide to how many simultaneous
+ logins the system will support.</para>
+
+ <para>For a desktop workstation, <literal>32</literal> is a good
+ value for <replaceable>n</replaceable>.</para>
+ </example>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Links</title>
+
+ <note>
+ <para>Links are also in-line elements.</para>
+ </note>
+
+ <sect3>
+ <title>Linking to other parts of the same document</title>
+
+ <para>Linking within the same document requires you to to specify
+ where you are linking from (i.e., the text the user will click, or
+ otherwise indicate, as the source of the link) and where you are
+ linking to (the link's destination).</para>
+
+ <para>Each element within DocBook has an attribute called
+ <literal>id</literal>. You can place text in this attribute to
+ uniquely name the element it is attached to.</para>
+
+ <para>This value will be used when you specify the link
+ source.</para>
+
+ <para>Normally, you will only be linking to chapters or sections, so
+ you would add the <literal>id</literal> attribute to these
+ elements.</para>
+
+ <example>
+ <title><literal>id on chapters and sections</literal></title>
+
+ <programlisting>
+<![ CDATA [<chapter id="chapter1">
+ <title>Introduction</title>
+
+ <para>This is the introduction. It contains a subsection,
+ which is identified as well.</para>
+
+ <sect1 id="chapter1-sect1">
+ <title>Sub-sect 1</title>
+
+ <para>This is the subsection.</para>
+ </sect1>
+</chapter>]]></programlisting>
+ </example>
+
+ <para>Obviously, you should use more descriptive values. The values
+ must be unique within the document (i.e., not just the file, but the
+ document the file might be included in as well). Notice how the
+ <literal>id</literal> for the subsection is constructed by appending
+ text to the <literal>id</literal> of the chapter. This helps to
+ ensure that they are unique.</para>
+
+ <para>If you want to allow the user to jump into a specific portion of
+ the document (possibly in the middle of a paragraph or an example),
+ use <sgmltag>anchor</sgmltag>. This element has no content, but
+ takes an <literal>id</literal> attribute.</para>
+
+ <example>
+ <title><sgmltag>anchor</sgmltag></title>
+
+ <programlisting>
+<![ CDATA [<para>This paragraph has an embedded
+ <anchor id="para1">link target in it. It won't show up in
+ the document.</para>]]></programlisting>
+ </example>
+
+ <para>When you want to provide the user with a link they can activate
+ (probably by clicking) to go to a section of the document that has
+ an <literal>id</literal> attribute, you can use either
+ <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para>
+
+ <para>Both of these elements have a <literal>linkend</literal>
+ attribute. The value of this attribute should be the value that you
+ have used in a <literal>id</literal> attribute (it does not matter
+ if that value has not yet occured in your document, this will work
+ for forward links as well as backward links).</para>
+
+ <para>If you use <sgmltag>xref</sgmltag> then you have no control over
+ the text of the link. It will be generated for you.</para>
+
+ <example>
+ <title>Using <sgmltag>xref</sgmltag></title>
+
+ <para>Assume that this fragment appears somewhere in a document that
+ includes the <literal>id</literal> example;</para>
+
+ <programlisting>
+<![ CDATA [<para>More information can be found
+ in <xref linkend="chapter1">.</para>
+
+<para>More specific information can be found
+ in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
+
+ <para>The text of the link will be generated automatically, and will
+ look like (<emphasis>emphasised</emphasis> text indicates the text
+ that will be the link);</para>
+
+ <blockquote>
+ <para>More information can be found in <emphasis>Chapter
+ One</emphasis>.</para>
+
+ <para>More specific information can be found in <emphasis>the
+ section called Sub-sect 1</emphasis>.</para>
+ </blockquote>
+ </example>
+
+ <para>Notice how the text from the link is derived from the section
+ title or the chapter number.</para>
+
+ <note>
+ <para>This means that you <emphasis>can not</emphasis> use
+ <sgmltag>xref</sgmltag> to link to an <literal>id</literal>
+ attribute on an <sgmltag>anchor</sgmltag> element. The
+ <sgmltag>anchor</sgmltag> has no content, so the
+ <sgmltag>xref</sgmltag> can not generate the text for the
+ link.</para>
+ </note>
+
+ <para>If you want to control the text of the link then use
+ <sgmltag>link</sgmltag>. This element wraps content, and the content
+ will be used for the link.</para>
+
+ <example>
+ <title>Using <sgmltag>link</sgmltag></title>
+
+ <para>Assume that this fragment appears somewhere in a document that
+ includes the <literal>id</literal> example.</para>
+
+ <programlisting>
+<![ CDATA [<para>More information can be found in
+ <link linkend="chapter1">the first chapter</link>.</para>
+
+<para>More specific information can be found in
+ <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting>
+
+ <para>This will generate the following
+ (<emphasis>emphasised</emphasis> text indicates the text that will
+ be the link);</para>
+
+ <blockquote>
+ <para>More information can be found in <emphasis>the first
+ chapter</emphasis>.</para>
+
+ <para>More specific information can be found in
+ <emphasis>this</emphasis> section.</para>
+ </blockquote>
+ </example>
+
+ <note>
+ <para>That last one is a bad example. Never use words like
+ &ldquo;this&rdquo; or &ldquo;here&rdquo; as the source for the
+ link. The reader will need to hunt around the surrounding context
+ to see where the link is actually taking them.</para>
+ </note>
+
+ <note>
+ <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to
+ include a link to an <literal>id</literal> on an
+ <sgmltag>anchor</sgmltag> element, since the
+ <sgmltag>link</sgmltag> content defines the text that will be used
+ for the link.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Linking to documents on the WWW</title>
+
+ <para>Linking to external documents is much simpler, as long as you
+ know the URL of the document you want to link to. Use
+ <sgmltag>ulink</sgmltag>. The <literal>url</literal> attribute is
+ the URL of the page that the link points to, and the content of the
+ element is the text that will be displayed for the user to
+ activate.</para>
+
+ <example>
+ <title><sgmltag>ulink</sgmltag></title>
+
+ <para>Use:</para>
+
+ <programlisting>
+<![ CDATA [<para>Of course, you could stop reading this document and
+ go to the <ulink url="http://www.freebsd.org/">FreeBSD
+ home page</ulink> instead.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>Of course, you could stop reading this document and go to the
+ <ulink url="http://www.freebsd.org/">FreeBSD home page</ulink>
+ instead.</para>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>* LinuxDoc</title>
+
+ <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the
+ <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
+ Project</ulink>, and subsequently adopted by the FreeBSD Documentation
+ Project.</para>
+
+ <para>The LinuxDoc DTD contains primarily appearance related markup rather
+ than content related markup (i.e., it describes what something looks
+ like rather than what it is).</para>
+
+ <para>Both the FreeBSD Documentation Project and the Linux Documentation
+ Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para>
+
+ <para>The LinuxDoc DTD is available from the ports collection in the
+ <filename>textproc/linuxdoc</filename> category.</para>
+ </sect1>
+</chapter>
+
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-declaration: "../chapter.decl"
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ sgml-parent-document: ("../book.sgml" "part" "chapter")
+ End:
+-->
+
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
new file mode 100644
index 0000000000..c25bacf1f1
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
@@ -0,0 +1,1554 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="sgml-primer">
+ <title>SGML Primer</title>
+
+ <para>The Documentation Project makes heavy use of the Standard Generalized
+ Markup Language (SGML). This chapter describes what SGML is, how to read
+ and understand markup, and some of the SGML tricks you will see used in
+ the FAQ, Handbook, and website.</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 &ldquo;typewriter&rdquo; style
+ font for viewing on screen, but as &ldquo;italics&rdquo; 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 the 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>
+
+ <para><command>rm /tmp/foo</command></para>
+ </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 can not. For this we need
+ markup.</para>
+
+ <para>&ldquo;Markup&rdquo; is commonly used to describe &ldquo;adding
+ value&rdquo; or &ldquo;increasing cost&rdquo;. 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 they are 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> of 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>
+
+<para><command>rm /tmp/foo</command></para>]]></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>SGML is <emphasis>not</emphasis> a markup langugage. Instead, SGML
+ is <emphasis>the language in which you write markup
+ languages</emphasis>. There have been many markup languages written
+ using SGML. HTML and DocBook are two of these.</para>
+
+ <para>This is an important point to understand. Most of the time you are
+ not writing SGML documents. Instead, you are writing documents in a
+ particular markup language. The definition of the markup language you
+ are using is written in SGML.</para>
+
+ <para>Each language definition (which is written in SGML) 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.</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 a
+ <emphasis>parser</emphasis> which reads in 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="elements">
+ <title>Elements, tags, and attributes</title>
+
+ <para>All the DTDs written in SGML share certain characteristics. This is
+ hardly surprising, as the philisophy behind SGML will inevitably show
+ through. One of the most obvious manifestations of this philisophy 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 &ldquo;book&rdquo; 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 &ldquo;chunking&rdquo; 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
+ 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 types of content.</para>
+
+ <para>Of course, we don't 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 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
+ to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text
+ consisting of the three characters <literal>&lt;</literal>,
+ <literal>p</literal>, and <literal>&gt;</literal>. But the phrase
+ &ldquo;the &lt;p&gt; element&rdquo; 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
+ 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/3.0/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/3.0/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 <option>-s</option> is passed as a parameter to
+ it, &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
+ 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="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 the
+ it.</para>
+
+ <para>This information is generally expressed on one line, in the DOCTYPE
+ declaration.</para>
+
+ <para>A typical declaration for 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="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) 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="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)</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 &ldquo;ISO&rdquo; 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
+ 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/3.0/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="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-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="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-escape"> shows, it is
+ possible to use SGML syntax within your document.</para>
+
+ <para>The delimiters for SGML comments is the string
+ &ldquo;<literal>--</literal>&rdquo;. The first occurence 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 an SGML term. You might feel more comfortable thinking
+ of them as variables. There are two types of entity in SGML, general
+ entities and parameter entities.</para>
+
+ <sect2 id="general-entities">
+ <title>General Entities</title>
+
+ <para>General entities are a way of assigning names to chunks of text,
+ and reusing that text (which may contain markup) throughout your
+ document.</para>
+
+ <para>You can not 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="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 normally include in an SGML document. For example, &lt; and
+ &amp; can not normally appear in an SGML document. Normally, when the
+ SGML processor sees a &lt; symbol it assumes that a tag (either a start
+ tag or an end tag) is about to appear, and when it sees a &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="parameter-entities">
+ <title>Parameter entities</title>
+
+ <para>Like <link linkend="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-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 don't do 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. Normalising it involves converting all the entity
+ references to the values of those entities.</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="general-entities">general</link> and
+ <link linkend="parameter-entities">parameter</link>) come into their own
+ when you realise they can be used to include other files.</para>
+
+ <sect2 id="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>
+ <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
+ &ldquo;marked sections&rdquo;.</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 <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 processor is processing a document, it keeps track
+ of what is called the &ldquo;content model&rdquo;.</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 &ldquo;Character Data&rdquo;. 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 &ldquo;Entity references and
+ character data&rdquo; 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="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>
+</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/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
new file mode 100644
index 0000000000..85e5855414
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
@@ -0,0 +1,68 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="stylesheets">
+ <title>* Stylesheets</title>
+
+ <para>SGML says nothing about how a document should be displayed to the
+ user, or rendered on paper. To do that, various languages have been
+ developed to describe stylesheets, including DynaText, Panorama, SPICE,
+ JSSS, FOSI, CSS, and DSSSL.</para>
+
+ <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we
+ are using CSS.</para>
+
+ <sect1>
+ <title>* DSSSL</title>
+
+ <para>The Documentation Project uses a slightly customised version of
+ Norm Walsh's modular DocBook stylesheets.</para>
+
+ <para>These can be found in
+ <filename>textproc/dsssl-docbook-modular</filename>.</para>
+ </sect1>
+
+ <sect1>
+ <title>* CSS</title>
+
+ <para></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
new file mode 100644
index 0000000000..01e4e129f5
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
@@ -0,0 +1,47 @@
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+-->
+
+<chapter id="the-website">
+ <title>* The Website</title>
+
+ <para></para>
+</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
new file mode 100644
index 0000000000..2080134fad
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
@@ -0,0 +1,210 @@
+<chapter id="tools">
+ <title>* Tools</title>
+
+ <para>The Documentation Project uses a number of tools to assist in the
+ production of documentation. You will need to install some or all of these
+ tools before you will be able to make changes.</para>
+
+ <important>
+ <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 that are missing from your system.</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>
+ </important>
+
+ <sect1>
+ <title>Software</title>
+
+ <para>The project uses the following applications;</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><application>Jade</application> and
+ <application>SP</application></term>
+
+ <listitem>
+ <para>These are two application suites by James Clark, who has
+ produced many useful SGML-processing applications.
+ <application>Jade</application> is &ldquo;James' DSSSL
+ Engine&rdquo;, a system that takes SGML documentation and a DSSSL
+ stylesheet and produces converted output.
+ <application>SP</application> contains a number of useful
+ applications to manipulate, normalise, and interrogate SGML
+ documents.</para>
+
+ <para>Don't be concerned if these terms are unfamliar to you.</para>
+
+ <para>They can be found in the ports system as
+ <filename>textproc/jade</filename> and
+ <filename>textproc/sp</filename> respectively.</para>
+
+ <note>
+ <para>Installed as part of
+ <filename>textproc/docproj</filename>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><application>teTeX</application></term>
+
+ <listitem>
+ <para><application>teTeX</application> is a distrubution of the TeX
+ typesetting system, and is used (in conjunction with Jade) to
+ produce the Postscript and PDF output formats.</para>
+
+ <para>v0.9 of <application>teTeX</application> is required, which is
+ currently in the ports collection as
+ <filename>print/teTeX-beta</filename>.</para>
+
+ <note>
+ <para>Might be installed as part of
+ <filename>textproc/docproj</filename>, depending on the
+ <makevar>JADETEX</makevar> setting.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><application>Emacs</application> or
+ <application>Xemacs</application></term>
+
+ <listitem>
+ <para>Neither of these programs is required. However, both of them
+ feature PSGML-MODE, a useful extension when dealing with SGML
+ documents that can reduce the amount of typing you need to do, and
+ remove some of the more obvious errors.</para>
+
+ <para>They can be found in <filename>editor/emacs20</filename> and
+ <filename>editor/xemacs20</filename>.</para>
+
+ <note>
+ <para>Not installed as part of
+ <filename>textproc/docproj</filename>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>Document Type Definitions (DTDs)</title>
+
+ <para>The project uses the following DTDs;</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>HTML</term>
+
+ <listitem>
+ <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 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> category.</para>
+
+ <note>
+ <para>Installed as part of
+ <filename>textproc/docproj</filename>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>LinuxDoc</term>
+
+ <listitem>
+ <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
+ the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
+ Project</ulink>, and subsequently adopted by the FreeBSD
+ Documentation Project.</para>
+
+ <para>The LinuxDoc DTD contains primarily appearance related markup
+ rather than content related markup (i.e., it describes what
+ something looks like rather than what it is).</para>
+
+ <para>Both the FreeBSD Documentation Project and the Linux
+ Documentation Project are migrating from the LinuxDoc DTD to the
+ DocBook DTD.</para>
+
+ <para>The LinuxDoc DTD is available from the ports collection in the
+ <filename>textproc/linuxdoc</filename> category.</para>
+
+ <note>
+ <para>Installed as part of
+ <filename>textproc/docproj</filename>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DocBook</term>
+
+ <listitem>
+ <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, it
+ contains XXX</para>
+
+ <note>
+ <para>Installed as part of
+ <filename>textproc/docproj</filename>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>DSSSL Stylesheets</title>
+
+ <para>The Documentation Project uses a slightly customised version of
+ Norm Walsh's modular DocBook stylesheets.</para>
+
+ <para>These can be found in
+ <filename>textproc/dsssl-docbook-modular</filename>.</para>
+
+ <note>
+ <para>Installed as part of <filename>textproc/docproj</filename>.</para>
+ </note>
+ </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
new file mode 100644
index 0000000000..07361a43be
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -0,0 +1,137 @@
+<!-- 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.
+-->
+
+<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.
+ &ldquo;Don't use contractions&rdquo; would be wrong.</para>
+
+ <para>Avoiding contractions makes for a more formal tone, is more
+ precise, and slightly easier for translators.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Use the serial comma</term>
+
+ <listitem>
+ <para>In a list of items within a paragraph, seperate each item from
+ the others with a comma. Seperate the last item from the others with
+ a comma and the word &ldquo;and&rdquo;.</para>
+
+ <para>For example, look at the following quote;</para>
+
+ <blockquote>
+ <para>This is a list of one, two and three items.</para>
+ </blockquote>
+
+ <para>Is this a list of three items, &ldquo;one&rdquo;,
+ &ldquo;two&rdquo;, and &ldquo;three&rdquo;, or a list of two items,
+ &ldquo;one&rdquo; and &ldquo;two and three&rdquo;?</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, &ldquo;the
+ command&rdquo;, &ldquo;the file&rdquo;, and &ldquo;man
+ command&rdquo; 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>
+ </variablelist>
+</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:
+-->
+