aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2013-06-23 19:45:12 +0000
committerWarren Block <wblock@FreeBSD.org>2013-06-23 19:45:12 +0000
commit4047241ce668f7a77732b3598250136310d93419 (patch)
tree5fc40d041ad43853e85572f6ad03342853422ea1
parent9b0a5ed979240a403528ec25fd54e3461b3f4a74 (diff)
downloaddoc-4047241ce668f7a77732b3598250136310d93419.tar.gz
doc-4047241ce668f7a77732b3598250136310d93419.zip
Split the old sgml-markup chapter into two chapters, one for XHTML and
one for DocBook. Both are edited and expanded versions of the content from the old chapter.
Notes
Notes: svn path=/head/; revision=42005
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/Makefile3
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/book.xml3
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/chapters.ent3
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml2248
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml5
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml2759
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml613
7 files changed, 2870 insertions, 2764 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile
index 60eaeea096..88291309b9 100644
--- a/en_US.ISO8859-1/books/fdp-primer/Makefile
+++ b/en_US.ISO8859-1/books/fdp-primer/Makefile
@@ -23,7 +23,8 @@ SRCS= book.xml
SRCS+= overview/chapter.xml
SRCS+= psgml-mode/chapter.xml
SRCS+= see-also/chapter.xml
-SRCS+= sgml-markup/chapter.xml
+SRCS+= xhtml-markup/chapter.xml
+SRCS+= docbook-markup/chapter.xml
SRCS+= sgml-primer/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS+= structure/chapter.xml
diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml
index 3d7fd3fdc0..af5dcffcac 100644
--- a/en_US.ISO8859-1/books/fdp-primer/book.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/book.xml
@@ -248,7 +248,8 @@ Password:</screen></entry>
&chap.overview;
&chap.tools;
&chap.xml-primer;
- &chap.xml-markup;
+ &chap.xhtml-markup;
+ &chap.docbook-markup;
&chap.stylesheets;
&chap.structure;
&chap.doc-build;
diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
index 37c1e4f805..14b1677f56 100644
--- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent
+++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
@@ -13,7 +13,8 @@
<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
-<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml">
+<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
+<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
diff --git a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
new file mode 100644
index 0000000000..a2e014fef5
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
@@ -0,0 +1,2248 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+
+ $FreeBSD$
+-->
+
+<chapter id="docbook-markup">
+ <title>DocBook Markup</title>
+
+ <sect1 id="docbook-markup-introduction">
+ <title>Introduction</title>
+
+ <para>This chapter is an introduction to DocBook as it is used for
+ &os; documentation. DocBook is a large and complex markup
+ system, but the subset described here covers the parts that are
+ most widely used for &os; documentation. While a moderate
+ subset is covered, it is impossible to anticipate every
+ situation. Please post questions that this document does
+ not answer to the &a.doc;.</para>
+
+ <para>DocBook was originally developed by HaL Computer Systems and
+ O'Reilly &amp; Associates to be a <acronym>DTD</acronym> for
+ writing technical documentation <footnote><para>A short history
+ can be found under <ulink
+ url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
+ http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>.
+ Since 1998 it is maintained by the <ulink
+ url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
+ DocBook Technical Committee</ulink>. As such, and unlike
+ LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
+ oriented towards markup that describes <emphasis>what</emphasis>
+ something is, rather than describing <emphasis>how</emphasis> it
+ should be presented.</para>
+
+ <para>The DocBook <acronym>DTD</acronym> is available from the
+ Ports&nbsp;Collection in the
+ <filename role="package">textproc/docbook-xml-450</filename>
+ port. It is automatically installed as part of the
+ <filename role="package">textproc/docproj</filename>
+ port.</para>
+
+ <note>
+ <title>Formal Versus Informal</title>
+
+ <para>Some elements may exist in two forms,
+ <emphasis>formal</emphasis> and <emphasis>informal</emphasis>.
+ Typically, the formal version of the element will consist of a
+ title followed by the informal version of the element. The
+ informal version will not have a title.</para>
+ </note>
+
+ <note>
+ <title>Inline Versus Block</title>
+
+ <para>In the remainder of this document, when describing
+ elements, <emphasis>inline</emphasis> means that the element
+ can occur within a block element, and does not cause a line
+ break. A <emphasis>block</emphasis> element, by comparison,
+ will cause a line break (and other processing) when it is
+ encountered.</para>
+ </note>
+ </sect1>
+
+ <sect1 id="docbook-markup-freebsd-extensions">
+ <title>&os; Extensions</title>
+
+ <para>The &os; Documentation Project has extended the
+ DocBook <acronym>DTD</acronym> by adding some new elements.
+ These elements serve to make some of the markup more
+ precise.</para>
+
+ <para>Where a &os;-specific element is listed below, it is
+ clearly marked.</para>
+
+ <para>Throughout the rest of this document, the term
+ <quote>DocBook</quote> is used to mean the &os;-extended
+ DocBook <acronym>DTD</acronym>.</para>
+
+ <note>
+ <para>There is nothing about these extensions that is &os;
+ 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
+ &a.doceng;.</para>
+ </note>
+
+ <para>The &os; extensions are not (currently) in the
+ Ports&nbsp;Collection. They are stored in the &os; Subversion
+ tree, as <ulink
+ url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para>
+ </sect1>
+
+ <sect1 id="docbook-markup-fpi">
+ <title>Formal Public Identifier (FPI)</title>
+
+ <para>In compliance with the DocBook guidelines for writing
+ <acronym>FPI</acronym>s for DocBook customizations, the
+ <acronym>FPI</acronym> for the &os; extended DocBook
+ <acronym>DTD</acronym> is:</para>
+
+ <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
+ </sect1>
+
+ <sect1 id="docbook-markup-document-structure">
+ <title>Document Structure</title>
+
+ <para>DocBook allows structuring documentation in several ways.
+ The &os; Documentation Project uses two primary types of DocBook
+ document: the book and the article.</para>
+
+ <para>Books are organized into <sgmltag>chapter</sgmltag>s.
+ This is a mandatory requirement. There may be
+ <sgmltag>part</sgmltag>s between the book and the chapter to
+ provide another layer of organization. For example, the
+ Handbook is arranged in this way.</para>
+
+ <para>A chapter may (or may not) contain one or more sections.
+ These are indicated with the <sgmltag>sect1</sgmltag> element.
+ If a section contains another section then use the
+ <sgmltag>sect2</sgmltag> element, and so on, up to
+ <sgmltag>sect5</sgmltag>.</para>
+
+ <para>Chapters and sections contain the remainder of the
+ content.</para>
+
+ <para>An article is simpler than a book, and does not use
+ chapters. Instead, the content of an article is organized into
+ one or more sections, using the same <sgmltag>sect1</sgmltag>
+ (and <sgmltag>sect2</sgmltag> and so on) elements that are used
+ in books.</para>
+
+ <para>The nature of the document being written should be used to
+ determine whether it is best marked up as a book or an article.
+ Articles are well suited to information that does not need to be
+ broken down into several chapters, and that is, relatively
+ speaking, quite short, at up to 20-25 pages of content. Books
+ are best suited to information that can be broken up into
+ several chapters, possibly with appendices and similar content
+ as well.</para>
+
+ <para>The <ulink url="&url.base;/docs.html">&os; tutorials</ulink>
+ are all marked up as articles, while this
+ document, the
+ <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
+ and the <ulink url="&url.books.handbook;/index.html">FreeBSD
+ Handbook</ulink> are all marked up as books, for
+ example.</para>
+
+ <sect2 id="docbook-markup-starting-a-book">
+ <title>Starting a Book</title>
+
+ <para>The content of a book is contained within the
+ <sgmltag>book</sgmltag> element. As well as containing
+ structural markup, this element can contain elements that
+ include additional information about the book. This is either
+ meta-information, used for reference purposes, or additional
+ content used to produce a title page.</para>
+
+ <para>This additional information is contained within
+ <sgmltag>bookinfo</sgmltag>.</para>
+
+ <example>
+ <title>Boilerplate <sgmltag>book</sgmltag> with
+ <sgmltag>bookinfo</sgmltag></title>
+
+ <!-- Cannot put this in a marked section because of the
+ replaceable elements -->
+
+ <programlisting>&lt;book&gt;
+ &lt;bookinfo&gt;
+ &lt;title&gt;<replaceable>Your Title Here</replaceable>&lt;/title&gt;
+
+ &lt;author&gt;
+ &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname&gt;
+ &lt;surname&gt;<replaceable>Your surname</replaceable>&lt;/surname&gt;
+ &lt;affiliation&gt;
+ &lt;address&gt;&lt;email&gt;<replaceable>Your email address</replaceable>&lt;/email&gt;&lt;/address&gt;
+ &lt;/affiliation&gt;
+ &lt;/author&gt;
+
+ &lt;copyright&gt;
+ &lt;year&gt;<replaceable>1998</replaceable>&lt;/year&gt;
+ &lt;holder role="mailto:<replaceable>your email address</replaceable>"&gt;<replaceable>Your name</replaceable>&lt;/holder&gt;
+ &lt;/copyright&gt;
+
+ &lt;releaseinfo&gt;&#36;FreeBSD&#36;&lt;/releaseinfo&gt;
+
+ &lt;abstract&gt;
+ &lt;para&gt;<replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para&gt;
+ &lt;/abstract&gt;
+ &lt;/bookinfo&gt;
+
+ &hellip;
+
+&lt;/book&gt;</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-starting-an-article">
+ <title>Starting an Article</title>
+
+ <para>The content of the article is contained within the
+ <sgmltag>article</sgmltag> element. As well as containing
+ structural markup, this element can contain elements that
+ include additional information about the article. This is
+ either meta-information, used for reference purposes, or
+ additional content used to produce a title page.</para>
+
+ <para>This additional information is contained within
+ <sgmltag>articleinfo</sgmltag>.</para>
+
+ <example>
+ <title>Boilerplate <sgmltag>article</sgmltag> with
+ <sgmltag>articleinfo</sgmltag></title>
+
+ <!-- Cannot put this in a marked section because of the
+ replaceable elements -->
+
+ <programlisting>&lt;article&gt;
+ &lt;articleinfo&gt;
+ &lt;title&gt;<replaceable>Your title here</replaceable>&lt;/title&gt;
+
+ &lt;author&gt;
+ &lt;firstname&gt;<replaceable>Your first name</replaceable>&lt;/firstname&gt;
+ &lt;surname&gt;<replaceable>Your surname</replaceable>&lt;/surname&gt;
+ &lt;affiliation&gt;
+ &lt;address&gt;&lt;email&gt;<replaceable>Your email address</replaceable>&lt;/email&gt;&lt;/address&gt;
+ &lt;/affiliation&gt;
+ &lt;/author&gt;
+
+ &lt;copyright&gt;
+ &lt;year&gt;<replaceable>1998</replaceable>&lt;/year&gt;
+ &lt;holder role="mailto:<replaceable>your email address</replaceable>"&gt;<replaceable>Your name</replaceable>&lt;/holder&gt;
+ &lt;/copyright&gt;
+
+ &lt;releaseinfo&gt;&#36;FreeBSD&#36;&lt;/releaseinfo&gt;
+
+ &lt;abstract&gt;
+ &lt;para&gt;<replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para&gt;
+ &lt;/abstract&gt;
+ &lt;/articleinfo&gt;
+
+ &hellip;
+
+&lt;/article&gt;</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-indicating-chapters">
+ <title>Indicating Chapters</title>
+
+ <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters.
+ Each chapter has a mandatory <sgmltag>title</sgmltag>.
+ Articles do not contain chapters, they are reserved for
+ books.</para>
+
+ <example>
+ <title>A Simple Chapter</title>
+
+ <programlisting><![CDATA[<chapter>
+ <title>The Chapter's Title</title>
+
+ ...
+</chapter>]]></programlisting>
+ </example>
+
+ <para>A chapter cannot be empty; it must contain elements in
+ addition to <sgmltag>title</sgmltag>. If you need to
+ include an empty chapter then just use an empty
+ paragraph.</para>
+
+ <example>
+ <title>Empty Chapters</title>
+
+ <programlisting><![CDATA[<chapter>
+ <title>This is An Empty Chapter</title>
+
+ <para></para>
+</chapter>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-sections-below-chapters">
+ <title>Sections Below Chapters</title>
+
+ <para>In books, chapters may (but do not need to) be broken up
+ into sections, subsections, and so on. In articles, sections
+ are the main structural element, and each article must contain
+ at least one section. Use the
+ <sgmltag>sect<replaceable>n</replaceable></sgmltag> element.
+ The <replaceable>n</replaceable> indicates the section number,
+ which identifies the section level.</para>
+
+ <para>The first
+ <sgmltag>sect<replaceable>n</replaceable></sgmltag> is
+ <sgmltag>sect1</sgmltag>. You can have one or more of these
+ in a chapter. They can contain one or more
+ <sgmltag>sect2</sgmltag> elements, and so on, down to
+ <sgmltag>sect5</sgmltag>.</para>
+
+ <example>
+ <title>Sections in Chapters</title>
+
+ <programlisting><![CDATA[<chapter>
+ <title>A Sample Chapter</title>
+
+ <para>Some text in the chapter.</para>
+
+ <sect1>
+ <title>First Section (1.1)</title>
+
+ &hellip;
+ </sect1>
+
+ <sect1>
+ <title>Second Section (1.2)</title>
+
+ <sect2>
+ <title>First Sub-Section (1.2.1)</title>
+
+ <sect3>
+ <title>First Sub-Sub-Section (1.2.1.1)</title>
+
+ &hellip;
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Second Sub-Section (1.2.2)</title>
+
+ &hellip;
+ </sect2>
+ </sect1>
+</chapter>]]></programlisting>
+ </example>
+
+ <note>
+ <para>This example includes section numbers in the section
+ titles. You should not do this in your documents. Adding
+ the section numbers is carried out by the stylesheets (of
+ which more later), and you do not need to manage them
+ yourself.</para>
+ </note>
+ </sect2>
+
+ <sect2 id="docbook-markup-subdividing-part">
+ <title>Subdividing Using <sgmltag>part</sgmltag>
+ Elements</title>
+
+ <para><sgmltag>part</sgmltag>s introduce another level of
+ organization between <sgmltag>book</sgmltag> and
+ <sgmltag>chapter</sgmltag> with one or more
+ <sgmltag>part</sgmltag>s. This cannot be done in an
+ <sgmltag>article</sgmltag>.</para>
+
+ <programlisting><![CDATA[<part>
+ <title>Introduction</title>
+
+ <chapter>
+ <title>Overview</title>
+
+ ...
+ </chapter>
+
+ <chapter>
+ <title>What is FreeBSD?</title>
+
+ ...
+ </chapter>
+
+ <chapter>
+ <title>History</title>
+
+ ...
+ </chapter>
+</part>]]></programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1 id="docbook-markup-block-elements">
+ <title>Block Elements</title>
+
+ <sect2 id="docbook-markup-paragraphs">
+ <title>Paragraphs</title>
+
+ <para>DocBook supports three types of paragraphs:
+ <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
+ <sgmltag>simpara</sgmltag>.</para>
+
+ <para>Almost all paragraphs in &os; documentation use
+ <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag>
+ includes a <sgmltag>title</sgmltag> element, and
+ <sgmltag>simpara</sgmltag> disallows some elements from
+ within <sgmltag>para</sgmltag>. Stick with
+ <sgmltag>para</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>para</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![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>
+ </sect2>
+
+ <sect2 id="docbook-markup-block-quotations">
+ <title>Block Quotations</title>
+
+ <para>A block quotation is an extended quotation from another
+ document that should not appear within the current
+ paragraph. These are rarely needed.</para>
+
+ <para>Blockquotes can optionally contain a title and an
+ attribution (or they can be left untitled and
+ unattributed).</para>
+
+ <example>
+ <title><sgmltag>blockquote</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>A small excerpt from the US Constitution:</para>
+
+<blockquote>
+ <title>Preamble to the Constitution of the United States</title>
+
+ <attribution>Copied from a web site somewhere</attribution>
+
+ <para>We the People of the United States, in Order to form a more
+ perfect Union, establish Justice, insure domestic Tranquility,
+ provide for the common defence, promote the general Welfare, and
+ secure the Blessings of Liberty to ourselves and our Posterity, do
+ ordain and establish this Constitution for the United States of
+ America.</para>
+</blockquote>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>A small excerpt from the US Constitution:</para>
+
+ <blockquote>
+ <title>Preamble to the Constitution of the United
+ States</title>
+
+ <attribution>Copied from a web site
+ somewhere</attribution>
+
+ <para>We the People of the United States, in Order to form
+ a more perfect Union, establish Justice, insure domestic
+ Tranquility, provide for the common defence, promote the
+ general Welfare, and secure the Blessings of Liberty to
+ ourselves and our Posterity, do ordain and establish
+ this Constitution for the United States of
+ America.</para>
+ </blockquote>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-tips-notes">
+ <title>Tips, Notes, Warnings, Cautions, Important Information
+ and Sidebars</title>
+
+ <para>Extra information may need to be separated from
+ the main body of the text. Typically this is
+ <quote>meta</quote> information of which the user should be
+ aware.</para>
+
+ <para>Depending on the nature of the information, one of
+ <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
+ <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
+ <sgmltag>important</sgmltag> should be used. Alternatively,
+ if the information is related to the main text but is not
+ one of the above, use <sgmltag>sidebar</sgmltag>.</para>
+
+ <para>The circumstances in which to choose one of these
+ elements over another is loosely defined by the DocBook
+ documentation, which suggests:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A Note is for information that should be heeded by
+ all readers.</para>
+ </listitem>
+
+ <listitem>
+ <para>An Important element is a variation on Note.</para>
+ </listitem>
+
+ <listitem>
+ <para>A Caution is for information regarding possible data
+ loss or software damage.</para>
+ </listitem>
+
+ <listitem>
+ <para>A Warning is for information regarding possible
+ hardware damage or injury to life or limb.</para>
+ </listitem>
+ </itemizedlist>
+
+ <example>
+ <title><sgmltag>warning</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<warning>
+ <para>Installing FreeBSD may make you want to delete Windows from your
+ hard disk.</para>
+</warning>]]></programlisting>
+ </example>
+
+ <para>Appearance:</para>
+ <!-- Need to do this outside of the example -->
+ <warning>
+ <para>Installing FreeBSD may make you want to delete Windows
+ from your hard disk.</para>
+ </warning>
+ </sect2>
+
+ <sect2 id="docbook-markup-lists-and-procedures">
+ <title>Lists and Procedures</title>
+
+ <para>Information often needs to be presented as lists, or as a
+ number of steps that must be carried out in order to
+ accomplish a particular goal.</para>
+
+ <para>To do this, use <sgmltag>itemizedlist</sgmltag>,
+ <sgmltag>orderedlist</sgmltag>, or
+ <sgmltag>procedure</sgmltag><footnote><para>There are other
+ types of list element in DocBook, but we are not
+ concerned with those at the
+ moment.</para></footnote></para>
+
+ <para><sgmltag>itemizedlist</sgmltag> and
+ <sgmltag>orderedlist</sgmltag> are similar to their
+ counterparts in <acronym>HTML</acronym>, <sgmltag>ul</sgmltag>
+ and <sgmltag>ol</sgmltag>. Each one consists of one or more
+ <sgmltag>listitem</sgmltag> elements, and each
+ <sgmltag>listitem</sgmltag> contains one or more block
+ elements. The <sgmltag>listitem</sgmltag> elements are
+ analogous to <acronym>HTML</acronym>'s <sgmltag>li</sgmltag>
+ tags. However, unlike HTML, they are required.</para>
+
+ <para><sgmltag>procedure</sgmltag> is slightly different. It
+ consists of <sgmltag>step</sgmltag>s, which may in turn
+ consists of more <sgmltag>step</sgmltag>s or
+ <sgmltag>substep</sgmltag>s. Each <sgmltag>step</sgmltag>
+ contains block elements.</para>
+
+ <example>
+ <title><sgmltag>itemizedlist</sgmltag>,
+ <sgmltag>orderedlist</sgmltag>, and
+ <sgmltag>procedure</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<itemizedlist>
+ <listitem>
+ <para>This is the first itemized item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second itemized item.</para>
+ </listitem>
+</itemizedlist>
+
+<orderedlist>
+ <listitem>
+ <para>This is the first ordered item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second ordered item.</para>
+ </listitem>
+</orderedlist>
+
+<procedure>
+ <step>
+ <para>Do this.</para>
+ </step>
+
+ <step>
+ <para>Then do this.</para>
+ </step>
+
+ <step>
+ <para>And now do this.</para>
+ </step>
+</procedure>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>This is the first itemized item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second itemized item.</para>
+ </listitem>
+ </itemizedlist>
+
+ <orderedlist>
+ <listitem>
+ <para>This is the first ordered item.</para>
+ </listitem>
+
+ <listitem>
+ <para>This is the second ordered item.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+
+ <!-- Cannot have <procedure> inside <example>, so this is a
+ cheat -->
+
+ <procedure>
+ <step>
+ <para>Do this.</para>
+ </step>
+
+ <step>
+ <para>Then do this.</para>
+ </step>
+
+ <step>
+ <para>And now do this.</para>
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2 id="docbook-markup-showing-file-samples">
+ <title>Showing File Samples</title>
+
+ <para>Fragments of a file (or perhaps a complete file) are shown
+ by wrapping them in the <sgmltag>programlisting</sgmltag>
+ element.</para>
+
+ <para>White space and line breaks within
+ <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
+ significant. In particular, this means that the opening tag
+ should appear on the same line as the first line of the
+ output, and the closing tag should appear on the same line
+ as the last line of the output, otherwise spurious blank
+ lines may be included.</para>
+
+ <example>
+ <title><sgmltag>programlisting</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>When finished, the program will 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 finished, the program will look like this:</para>
+
+ <programlisting>#include &lt;stdio.h&gt;
+
+int
+main(void)
+{
+ printf("hello, world\n");
+}</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-callouts">
+ <title>Callouts</title>
+
+ <para>A callout is a mechanism for referring back to an
+ earlier piece of text or specific position within an earlier
+ example without linking to it within the text.</para>
+
+ <para>To do this, mark areas of interest in the example
+ (<sgmltag>programlisting</sgmltag>,
+ <sgmltag>literallayout</sgmltag>, or whatever) with the
+ <sgmltag>co</sgmltag> element. Each element must have a
+ unique <literal>id</literal> assigned to it. After the
+ example include a <sgmltag>calloutlist</sgmltag> that refers
+ back to the example and provides additional
+ commentary.</para>
+
+ <example>
+ <title><sgmltag>co</sgmltag> and
+ <sgmltag>calloutlist</sgmltag></title>
+
+ <programlisting><![CDATA[<para>When finished, the program will look like
+ this:</para>
+
+<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>
+
+int <co id="co-ex-return"/>
+main(void)
+{
+ printf("hello, world\n"); <co id="co-ex-printf"/>
+}</programlisting>
+
+<calloutlist>
+ <callout arearefs="co-ex-include">
+ <para>Includes the standard IO header file.</para>
+ </callout>
+
+ <callout arearefs="co-ex-return">
+ <para>Specifies that <function>main()</function> returns an
+ int.</para>
+ </callout>
+
+ <callout arearefs="co-ex-printf">
+ <para>The <function>printf()</function> call that writes
+ <literal>hello, world</literal> to standard output.</para>
+ </callout>
+</calloutlist>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>When finished, the program will look like this:</para>
+
+ <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>
+
+int <co id="co-ex-return"/>
+main(void)
+{
+ printf("hello, world\n"); <co id="co-ex-printf"/>
+}</programlisting>
+
+ <calloutlist>
+ <callout arearefs="co-ex-include">
+ <para>Includes the standard IO header file.</para>
+ </callout>
+
+ <callout arearefs="co-ex-return">
+ <para>Specifies that <function>main()</function> returns
+ an int.</para>
+ </callout>
+
+ <callout arearefs="co-ex-printf">
+ <para>The <function>printf()</function> call that writes
+ <literal>hello, world</literal> to standard
+ output.</para>
+ </callout>
+ </calloutlist>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-tables">
+ <title>Tables</title>
+
+ <para>Unlike <acronym>HTML</acronym>, DocBook does not need
+ tables for layout purposes, as the stylesheet handles those
+ issues. Instead, just use tables for marking up tabular
+ data.</para>
+
+ <para>In general terms (and see the DocBook documentation for
+ more detail) a table (which can be either formal or informal)
+ consists of a <sgmltag>table</sgmltag> element. This contains
+ at least one <sgmltag>tgroup</sgmltag> element, which
+ specifies (as an attribute) the number of columns in this
+ table group. Within the tablegroup there is one
+ <sgmltag>thead</sgmltag> element, which contains elements for
+ the table headings (column headings), and one
+ <sgmltag>tbody</sgmltag> which contains the body of the
+ table.</para>
+
+ <para>Both <sgmltag>tgroup</sgmltag> and
+ <sgmltag>thead</sgmltag> contain <sgmltag>row</sgmltag>
+ elements, which in turn contain <sgmltag>entry</sgmltag>
+ elements. Each <sgmltag>entry</sgmltag> element specifies
+ one cell in the table.</para>
+
+ <example>
+ <title><sgmltag>informaltable</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<informaltable pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>This is Column Head 1</entry>
+ <entry>This is Column Head 2</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Row 1, column 1</entry>
+ <entry>Row 1, column 2</entry>
+ </row>
+
+ <row>
+ <entry>Row 2, column 1</entry>
+ <entry>Row 2, column 2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <informaltable pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>This is Column Head 1</entry>
+ <entry>This is Column Head 2</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Row 1, column 1</entry>
+ <entry>Row 1, column 2</entry>
+ </row>
+
+ <row>
+ <entry>Row 2, column 1</entry>
+ <entry>Row 2, column 2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </example>
+
+ <para>Always use the <literal>pgwide</literal> attribute with
+ a value of <literal>1</literal> with the
+ <sgmltag>informaltable</sgmltag> element. A bug in Internet
+ Explorer can cause the table to render incorrectly if this
+ is omitted.</para>
+
+ <para>Table borders can be suppressed by setting the
+ <literal>frame</literal> attribute to <literal>none</literal>
+ in the <sgmltag>informaltable</sgmltag> element. For example,
+ <literal>&lt;informaltable frame="none"&gt;</literal>.</para>
+
+ <example>
+ <title>Tables Where <literal>frame="none"</literal></title>
+
+ <para>Appearance:</para>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>This is Column Head 1</entry>
+ <entry>This is Column Head 2</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Row 1, column 1</entry>
+ <entry>Row 1, column 2</entry>
+ </row>
+
+ <row>
+ <entry>Row 2, column 1</entry>
+ <entry>Row 2, column 2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-examples">
+ <title>Examples for the User to Follow</title>
+
+ <para>Examples for the user to follow are often necessary.
+ Typically, these will consist of dialogs with the computer;
+ the user types in a command, the user gets a response back,
+ the user types another command, and so on.</para>
+
+ <para>A number of distinct elements and entities come into
+ play here.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><sgmltag>screen</sgmltag></term>
+
+ <listitem>
+ <para>Everything the user sees in this example will be
+ on the computer screen, so the next element is
+ <sgmltag>screen</sgmltag>.</para>
+
+ <para>Within <sgmltag>screen</sgmltag>, white space is
+ significant.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><sgmltag>prompt</sgmltag>,
+ <literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal></term>
+
+ <listitem>
+ <para>Some of the things the user will be seeing on the
+ screen are prompts from the computer (either from the
+ operating system, command shell, or application). These
+ should be marked up using
+ <sgmltag>prompt</sgmltag>.</para>
+
+ <para>As a special case, the two shell prompts for the
+ normal user and the root user have been provided as
+ entities. To indicate the user is at a shell prompt,
+ use one of <literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal> as necessary. They
+ do not need to be inside
+ <sgmltag>prompt</sgmltag>.</para>
+
+ <note>
+ <para><literal>&amp;prompt.root;</literal> and
+ <literal>&amp;prompt.user;</literal> are &os;
+ extensions to DocBook, and are not part of the
+ original <acronym>DTD</acronym>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><sgmltag>userinput</sgmltag></term>
+
+ <listitem>
+ <para>When displaying text that the user should type in,
+ wrap it in <sgmltag>userinput</sgmltag> tags. It will
+ be displayed differently than system output text.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>,
+ and <sgmltag>userinput</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput>
+foo1
+foo2
+foo3
+&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+foo2
+&prompt.user; <userinput>su</userinput>
+<prompt>Password: </prompt>
+&prompt.root; <userinput>cat foo2</userinput>
+This is the file called 'foo2'</screen>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <screen>&prompt.user; <userinput>ls -1</userinput>
+foo1
+foo2
+foo3
+&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+foo2
+&prompt.user; <userinput>su</userinput>
+<prompt>Password: </prompt>
+&prompt.root; <userinput>cat foo2</userinput>
+This is the file called 'foo2'</screen>
+ </example>
+
+ <note>
+ <para>Even though we are displaying the contents of the file
+ <filename>foo2</filename>, it is <emphasis>not</emphasis>
+ marked up as <sgmltag>programlisting</sgmltag>. Reserve
+ <sgmltag>programlisting</sgmltag> for showing fragments of
+ files outside the context of user actions.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 id="docbook-markup-inline-elements">
+ <title>In-line Elements</title>
+
+ <sect2 id="docbook-markup-inline-emphasizing">
+ <title>Emphasizing Information</title>
+
+ <para>To emphasize a particular word or phrase, use
+ <sgmltag>emphasis</sgmltag>. This may be presented as
+ italic, or bold, or might be spoken differently with a
+ text-to-speech system.</para>
+
+ <para>There is no way to change the presentation of the
+ emphasis within the document, no equivalent of
+ <acronym>HTML</acronym>'s <sgmltag>b</sgmltag> and
+ <sgmltag>i</sgmltag>. If the information being presented is
+ important, then consider presenting it in
+ <sgmltag>important</sgmltag> rather than
+ <sgmltag>emphasis</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>emphasis</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![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>
+ </sect2>
+
+ <sect2 id="docbook-markup-quotations">
+ <title>Quotations</title>
+
+ <para>To quote text from another document or source, or to
+ denote a phrase that is used figuratively, use
+ <sgmltag>quote</sgmltag>. Most of the markup tags available
+ for normal text are also available from within a
+ <sgmltag>quote</sgmltag>.</para>
+
+ <example>
+ <title>Quotations</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the
+ <quote>boundary between local and public administration</quote>,
+ as RFC 1535 calls it.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>However, make sure that the search does not go beyond
+ the <quote>boundary between local and public
+ administration</quote>, as RFC 1535 calls it.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-keys">
+ <title>Keys, Mouse Buttons, and Combinations</title>
+
+ <para>To refer to a specific key on the keyboard, use
+ <sgmltag>keycap</sgmltag>. To refer to a mouse button, use
+ <sgmltag>mousebutton</sgmltag>. And to refer to
+ combinations of key presses or mouse clicks, wrap them all
+ in <sgmltag>keycombo</sgmltag>.</para>
+
+ <para><sgmltag>keycombo</sgmltag> has an attribute called
+ <literal>action</literal>, which may be one of
+ <literal>click</literal>, <literal>double-click</literal>,
+ <literal>other</literal>, <literal>press</literal>,
+ <literal>seq</literal>, or <literal>simul</literal>. The
+ last two values denote whether the keys or buttons should be
+ pressed in sequence, or simultaneously.</para>
+
+ <para>The stylesheets automatically add any connecting
+ symbols, such as <literal>+</literal>, between the key
+ names, when wrapped in <sgmltag>keycombo</sgmltag>.</para>
+
+ <example>
+ <title>Keys, Mouse Buttons, and Combinations</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>To switch to the second virtual terminal, press
+ <keycombo action="simul"><keycap>Alt</keycap>
+ <keycap>F1</keycap></keycombo>.</para>
+
+<para>To exit <command>vi</command> without saving changes, type
+ <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
+ <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
+
+<para>My window manager is configured so that
+ <keycombo action="simul"><keycap>Alt</keycap>
+ <mousebutton>right</mousebutton>
+ </keycombo> mouse button is used to move windows.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>To switch to the second virtual terminal, press
+ <keycombo action="simul"><keycap>Alt</keycap>
+ <keycap>F1</keycap></keycombo>.</para>
+
+ <para>To exit <command>vi</command> without saving changes,
+ type <keycombo action="seq">
+ <keycap>Esc</keycap>
+ <keycap>:</keycap>
+ <keycap>q</keycap>
+ <keycap>!</keycap></keycombo>.</para>
+
+ <para>My window manager is configured so that
+ <keycombo action="simul">
+ <keycap>Alt</keycap>
+ <mousebutton>right</mousebutton></keycombo> mouse button
+ is used to move windows.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-applications">
+ <title>Applications, Commands, Options, and Cites</title>
+
+ <para>Both applications and commands are frequently referred to
+ when writing documentation. The distinction between them is
+ that an application is the name of a program or suite of
+ programs that fulfill a particular task. A command is the
+ filename of a program that the user can type and run at a
+ command line.</para>
+
+ <para>It is often necessary to show some of the options that a
+ command might take.</para>
+
+ <para>Finally, it is often useful to list a command with its
+ manual section number, in the <quote>command(number)</quote>
+ format so common in Unix manuals.</para>
+
+ <para>Mark up application names with
+ <sgmltag>application</sgmltag>.</para>
+
+ <para>To list a command with its manual section
+ number (which should be most of the time) the DocBook
+ element is <sgmltag>citerefentry</sgmltag>. This will
+ contain a further two elements,
+ <sgmltag>refentrytitle</sgmltag> and
+ <sgmltag>manvolnum</sgmltag>. The content of
+ <sgmltag>refentrytitle</sgmltag> is the name of the command,
+ and the content of <sgmltag>manvolnum</sgmltag> is the
+ manual page section.</para>
+
+ <para>This can be cumbersome to write, and so a series of
+ <link linkend="xml-primer-general-entities">general
+ entities</link> have been created to make this easier.
+ Each entity takes the form
+ <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
+
+ <para>The file that contains these entities is in
+ <filename>doc/share/xml/man-refs.ent</filename>, and can be
+ referred to using this <acronym>FPI</acronym>:</para>
+
+ <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
+
+ <para>Therefore, the introduction to &os; documentation will
+ usually include this:</para>
+
+ <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
+
+&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
+%man;
+
+&hellip;
+
+]&gt;</programlisting>
+
+ <para>Use <sgmltag>command</sgmltag> when to include a command
+ name <quote>in-line</quote> but present it as something the
+ user should type in.</para>
+
+ <para>Use <sgmltag>option</sgmltag> to mark up the options
+ which will be passed to a command.</para>
+
+ <para>When referring to the same command multiple times in
+ close proximity, it is preferred to use the
+ <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
+ notation to markup the first reference and use
+ <sgmltag>command</sgmltag> to markup subsequent references.
+ This makes the generated output, especially
+ <acronym>HTML</acronym>, appear visually better.</para>
+
+ <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>Usage:</para>
+
+ <programlisting><![CDATA[<para><application>Sendmail</application> is the most
+ widely used Unix mail application.</para>
+
+<para><application>Sendmail</application> includes the
+ <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
+ programs.</para>
+
+<para>One of the command line parameters to <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, <option>-bp</option>, will display the current
+ status of messages in the mail queue. Check this on the command
+ line by running <command>sendmail -bp</command>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para><application>Sendmail</application> is the most widely
+ used Unix mail application.</para>
+
+ <para><application>Sendmail</application> includes the
+ <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
+ programs.</para>
+
+ <para>One of the command line parameters to
+ <citerefentry>
+ <refentrytitle>sendmail</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>, <option>-bp</option>, will display the
+ current status of messages in the mail queue. Check this
+ on the command line by running
+ <command>sendmail -bp</command>.</para>
+ </example>
+
+ <note>
+ <para>Notice how the
+ <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
+ notation is easier to follow.</para>
+ </note>
+ </sect2>
+
+ <sect2 id="docbook-markup-files">
+ <title>Files, Directories, Extensions</title>
+
+ <para>To refer to the name of a file, a directory, or a file
+ extension, use <sgmltag>filename</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>filename</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>The XML source for the Handbook in English is
+ found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first
+ file is called <filename>book.xml</filename> in that
+ directory. There is also a <filename>Makefile</filename>
+ and a number of files with a <filename>.ent</filename>
+ extension.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The XML source for the Handbook in English can be
+ found in <filename>/usr/doc/en/handbook/</filename>. The
+ first file is called <filename>handbook.xml</filename> in
+ that directory. There is also a
+ <filename>Makefile</filename> and a number of files with a
+ <filename>.ent</filename> extension.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-name-of-ports">
+ <title>The Name of Ports</title>
+
+ <note>
+ <title>&os; Extension</title>
+
+ <para>These elements are part of the &os; extension to
+ DocBook, and do not exist in the original DocBook
+ <acronym>DTD</acronym>.</para>
+ </note>
+
+ <para>To include the name of a program from the &os;
+ Ports&nbsp;Collection in the document, use the
+ <sgmltag>filename</sgmltag> tag with the
+ <literal>role</literal> attribute set to
+ <literal>package</literal>. Since ports can be installed in
+ any number of locations, only include the category and the
+ port name; do not include
+ <filename>/usr/ports</filename>.</para>
+
+ <example>
+ <title><sgmltag>filename</sgmltag> Tag with
+ <literal>package</literal> Role</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>Install the <filename role="package">net/wireshark</filename> port to view network traffic.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>Install the <filename
+ role="package">net/wireshark</filename> port to view
+ network traffic.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-devices">
+ <title>Devices</title>
+
+ <note>
+ <title>&os; Extension</title>
+
+ <para>These elements are part of the &os; extension to
+ DocBook, and do not exist in the original DocBook
+ <acronym>DTD</acronym>.</para>
+ </note>
+
+ <para>There are two names for devices: the device name as it
+ appears in <filename>/dev</filename>, or the name of the
+ device as it appears in the kernel. For this latter course,
+ use <sgmltag>devicename</sgmltag>.</para>
+
+ <para>Sometimes there is no choice. Some devices, such as
+ network cards, do not have entries in
+ <filename>/dev</filename>, or the entries are markedly
+ different from their kernel device names.</para>
+
+ <example>
+ <title><sgmltag>devicename</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![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, network devices such as
+ <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>
+
+<para>In MS-DOS, the first floppy drive is referred to as
+ <devicename>a:</devicename>. In FreeBSD it is
+ <filename>/dev/fd0</filename>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para><devicename>sio</devicename> is used for serial
+ communication in FreeBSD. <devicename>sio</devicename>
+ manifests through a number of entries in
+ <filename>/dev</filename>, including
+ <filename>/dev/ttyd0</filename> and
+ <filename>/dev/cuaa0</filename>.</para>
+
+ <para>By contrast, network devices such as
+ <devicename>ed0</devicename> do not appear in
+ <filename>/dev</filename>.</para>
+
+ <para>In MS-DOS, the first floppy drive is referred to as
+ <devicename>a:</devicename>. In FreeBSD it is
+ <filename>/dev/fd0</filename>.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-hosts">
+ <title>Hosts, Domains, IP Addresses, and So Forth</title>
+
+ <note>
+ <title>&os; Extension</title>
+
+ <para>These elements are part of the &os; extension to
+ DocBook, and do not exist in the original DocBook
+ <acronym>DTD</acronym>.</para>
+ </note>
+
+ <para>Identification information for networked computers (hosts)
+ can be marked up in several ways, depending on the nature of
+ the information. All of them use <sgmltag>hostid</sgmltag> as
+ the element, with the <literal>role</literal> attribute
+ selecting the type of the marked up information.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>No <literal>role</literal> attribute, or
+ <literal>role="hostname"</literal></term>
+
+ <listitem>
+ <para>With no <literal>role</literal> attribute (i.e.,
+ <sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>)
+ the marked up information is the simple hostname, such
+ as <literal>freefall</literal> or
+ <literal>wcarchive</literal>. The hostname can be
+ explicitly specified with
+ <literal>role="hostname"</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="domainname"</literal></term>
+
+ <listitem>
+ <para>The text is a domain name, such as
+ <literal>FreeBSD.org</literal> or
+ <literal>ngo.org.uk</literal>. There is no hostname
+ component.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="fqdn"</literal></term>
+
+ <listitem>
+ <para>The text is a Fully Qualified Domain Name, with
+ both hostname and domain name parts.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="ipaddr"</literal></term>
+
+ <listitem>
+ <para>The text is an <acronym>IP</acronym> address,
+ probably expressed as a dotted quad.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="ip6addr"</literal></term>
+
+ <listitem>
+ <para>The text is an <acronym>IPv6</acronym>
+ address.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="netmask"</literal></term>
+
+ <listitem>
+ <para>The text is a network mask, which might be
+ expressed as a dotted quad, a hexadecimal string, or as
+ a <literal>/</literal> followed by a number
+ (<acronym>CIDR</acronym> notation).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>role="mac"</literal></term>
+
+ <listitem>
+ <para>The text is an Ethernet <acronym>MAC</acronym>
+ address, expressed as a series of 2 digit hexadecimal
+ numbers separated by colons.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title><sgmltag>hostid</sgmltag> and Roles</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![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 <acronym>IP</acronym> alias to an
+ interface (using <command>ifconfig</command>)
+ <emphasis>always</emphasis> use a netmask of
+ <hostid role="netmask">255.255.255.255</hostid> (which can
+ also be expressed as
+ <hostid role="netmask">0xffffffff</hostid>).</para>
+
+<para>The <acronym>MAC</acronym> address uniquely identifies
+ every network card in existence. A typical
+ <acronym>MAC</acronym> address looks like
+ <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>The local machine can always be referred to by the
+ name <hostid>localhost</hostid>, which will have the IP
+ address <hostid role="ipaddr">127.0.0.1</hostid>.</para>
+
+ <para>The <hostid role="domainname">FreeBSD.org</hostid>
+ domain contains a number of different hosts, including
+ <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
+ <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
+
+ <para>When adding an <acronym>IP</acronym> alias to an
+ interface (using <command>ifconfig</command>)
+ <emphasis>always</emphasis> use a netmask of
+ <hostid role="netmask">255.255.255.255</hostid> (which can
+ also be expressed as
+ <hostid role="netmask">0xffffffff</hostid>).</para>
+
+ <para>The <acronym>MAC</acronym> address uniquely identifies
+ every network card in existence. A typical
+ <acronym>MAC</acronym> address looks like
+ <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-usernames">
+ <title>Usernames</title>
+
+ <note>
+ <title>&os; Extension</title>
+
+ <para>These elements are part of the &os; extension to
+ DocBook, and do not exist in the original DocBook
+ <acronym>DTD</acronym>.</para>
+ </note>
+
+ <para>To refer to a specific username, such as
+ <literal>root</literal> or <literal>bin</literal>, use
+ <sgmltag>username</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>username</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>To carry out most system administration functions
+ requires logging in as <username>root</username>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>To carry out most system administration functions
+ requires logging in as <username>root</username>.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-describing-makefiles">
+ <title>Describing <filename>Makefile</filename>s</title>
+
+ <note>
+ <title>&os; Extension</title>
+
+ <para>These elements are part of the &os; extension to
+ DocBook, and do not exist in the original DocBook
+ <acronym>DTD</acronym>.</para>
+ </note>
+
+ <para>Two elements exist to describe parts of
+ <filename>Makefile</filename>s,
+ <sgmltag>maketarget</sgmltag> and
+ <sgmltag>makevar</sgmltag>.</para>
+
+ <para><sgmltag>maketarget</sgmltag> identifies a build target
+ exported by a <filename>Makefile</filename> that can be
+ given as a parameter to <command>make</command>.
+ <sgmltag>makevar</sgmltag> identifies a variable that can be
+ set (in the environment, on the <command>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>Usage:</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>
+ </sect2>
+
+ <sect2 id="docbook-markup-literal-text">
+ <title>Literal Text</title>
+
+ <para>Literal text, or text which should be entered verbatim, is
+ often needed in documentation. This is text that is excerpted
+ from another file, or which should be copied exactly as shown
+ from the documentation into another file.</para>
+
+ <para>Some of the time, <sgmltag>programlisting</sgmltag> will
+ be sufficient to denote this text. But
+ <sgmltag>programlisting</sgmltag> is not always appropriate,
+ particularly when you want to include a portion of a file
+ <quote>in-line</quote> with the rest of the
+ paragraph.</para>
+
+ <para>On these occasions, use
+ <sgmltag>literal</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>literal</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![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>
+ </sect2>
+
+ <sect2 id="docbook-markup-replaceable">
+ <title>Showing Items That the User <emphasis>Must</emphasis>
+ Fill In</title>
+
+ <para>There will often be times when the user is shown
+ what to do, or referred to a file or command line, but
+ cannot simply copy the example provided. Instead, they
+ must supply some information themselves.</para>
+
+ <para><sgmltag>replaceable</sgmltag> is designed for this
+ eventuality. Use it <emphasis>inside</emphasis> other
+ elements to indicate parts of that element's content that
+ the user must replace.</para>
+
+ <example>
+ <title><sgmltag>replaceable</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
+ </informalexample>
+
+ <para><sgmltag>replaceable</sgmltag> can be used in many
+ different elements, including <sgmltag>literal</sgmltag>.
+ This example also shows that
+ <sgmltag>replaceable</sgmltag> should only be wrapped
+ around the content that the user <emphasis>is</emphasis>
+ meant to provide. The other content should be left
+ alone.</para>
+
+ <para>Usage:</para>
+
+ <programlisting><![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>
+ </sect2>
+
+ <sect2 id="docbook-markup-system-errors">
+ <title>Quoting System Errors</title>
+
+ <para>System errors generated by &os; are marked with
+ <sgmltag>errorname</sgmltag>. This indicates the exact error
+ that appears.</para>
+
+ <example>
+ <title><sgmltag>errorname</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<screen><errorname>Panic: cannot mount root</errorname></screen>]]></programlisting>
+
+
+ <para>Appearance:</para>
+
+ <informalexample>
+ <screen><errorname>Panic: cannot mount root</errorname></screen>
+ </informalexample>
+ </example>
+ </sect2>
+ </sect1>
+
+ <sect1 id="docbook-markup-images">
+ <title>Images</title>
+
+ <important>
+ <para>Image support in the documentation is currently
+ extremely experimental. The mechanisms described here are
+ unlikely to change, but that is not guaranteed.</para>
+
+ <para>Installation of the
+ <filename role="package">graphics/ImageMagick</filename>
+ port is required. It is used to convert between the different
+ image formats. This port is <emphasis>not</emphasis> in
+ the <filename role="package">textproc/docproj</filename> meta
+ port, it must be installed by hand.</para>
+
+ <para>The best example of what follows in practice is the
+ <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
+ document. If the description that follows is unclear, take a
+ look at the files in that directory to see how everything
+ hangs together. Experiment with creating different formatted
+ versions of the document to see how the image markup appears
+ in the formatted output.</para>
+ </important>
+
+ <sect2 id="docbook-markup-image-formats">
+ <title>Image Formats</title>
+
+ <para>Two image formats are currently supported. Which to
+ choose will depend on the nature of the image.</para>
+
+ <para>Images that are primarily vector based, such as network
+ diagrams, time lines, and similar, should be in
+ <acronym>EPS</acronym> (Encapsulated Postscript) format.
+ These images have a <filename>.eps</filename>
+ extension.</para>
+
+ <para>For bitmaps, such as screen captures, use the
+ <acronym>PNG</acronym> (Portable Network Graphic) format.
+ These images have the <filename>.png</filename>
+ extension.</para>
+
+ <para>These are the <emphasis>only</emphasis> formats in which
+ images should be committed to the Subversion
+ repository.</para>
+
+ <para>Use the appropriate format for each image. It is to be
+ expected that documentation will have a mix of
+ <acronym>EPS</acronym> and <acronym>PNG</acronym> images. The
+ <filename>Makefile</filename>s ensure that the correct format
+ image is chosen depending on the output format that you use
+ for your documentation. <emphasis>Do not commit the same
+ image to the repository in two different
+ formats</emphasis>.</para>
+
+ <important>
+ <para>It is anticipated that the Documentation Project will
+ switch to using the <acronym>SVG</acronym> (Scalable Vector
+ Graphic) format for vector images. However, the current
+ state of <acronym>SVG</acronym> capable editing tools makes
+ this impractical.</para>
+ </important>
+ </sect2>
+
+ <sect2 id="docbook-markup-image-markup">
+ <title>Image Markup</title>
+
+ <para>The markup for an image is relatively simple. First,
+ markup a <sgmltag>mediaobject</sgmltag>. The
+ <sgmltag>mediaobject</sgmltag> can contain other, more
+ specific objects. We are concerned with two, the
+ <sgmltag>imageobject</sgmltag> and the
+ <sgmltag>textobject</sgmltag>.</para>
+
+ <para>Include one <sgmltag>imageobject</sgmltag>,
+ and two <sgmltag>textobject</sgmltag> elements. The
+ <sgmltag>imageobject</sgmltag> will point to the name of the
+ image file (without the extension). The
+ <sgmltag>textobject</sgmltag> elements contain information
+ that will be presented to the user as well as, or instead of,
+ the image itself.</para>
+
+ <para>There are two circumstances where this can
+ happen.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>When the reader is viewing the documentation in
+ <acronym>HTML</acronym>. In this case, each image will
+ need associated alternate text to show the user, typically
+ while the image is loading, or if they hover the mouse
+ pointer over the image.</para>
+ </listitem>
+
+ <listitem>
+ <para>When the reader is viewing the documentation in
+ plain text. In this case, each image should have an
+ <acronym>ASCII</acronym> art equivalent to show the
+ user.</para>
+
+ </listitem>
+ </itemizedlist>
+
+ <para>An example will make things easier to understand. Suppose
+ there is an image called <filename>fig1.png</filename> that is
+ to be included in the document. This image is of a rectangle
+ with an A inside it. The markup for this would be as
+ follows.</para>
+
+ <programlisting>&lt;mediaobject>
+ &lt;imageobject>
+ &lt;imagedata fileref="fig1"> <co id="co-image-ext"/>
+ &lt;/imageobject>
+
+ &lt;textobject>
+ &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal"/>
+| A |
++---------------+&lt;/literallayout>
+ &lt;/textobject>
+
+ &lt;textobject>
+ &lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase"/>
+ &lt;/textobject>
+&lt;/mediaobject></programlisting>
+
+ <calloutlist>
+ <callout arearefs="co-image-ext">
+ <para>Include an <sgmltag>imagedata</sgmltag> element
+ inside the <sgmltag>imageobject</sgmltag> element. The
+ <literal>fileref</literal> attribute should contain the
+ filename of the image to include, without the extension.
+ The stylesheets will work out which extension should be
+ added to the filename automatically.</para>
+ </callout>
+
+ <callout arearefs="co-image-literal">
+
+ <para>The first <sgmltag>textobject</sgmltag> contains a
+ <sgmltag>literallayout</sgmltag> element, where the
+ <literal>class</literal> attribute is set to
+ <literal>monospaced</literal>. This is an opportunity to
+ demonstrate <acronym>ASCII</acronym> art skills. This
+ content will be used if the document is converted to plain
+ text.</para>
+
+ <para>Notice how the first and last lines of the content
+ of the <sgmltag>literallayout</sgmltag> element butt up
+ next to the element's tags. This ensures no extraneous
+ white space is included.</para>
+ </callout>
+
+ <callout arearefs="co-image-phrase">
+ <para>The second <sgmltag>textobject</sgmltag> contains a
+ single <sgmltag>phrase</sgmltag> element. The contents of
+ this phrase will become the <literal>alt</literal>
+ attribute for the image when this document is converted to
+ <acronym>HTML</acronym>.</para>
+ </callout>
+ </calloutlist>
+ </sect2>
+
+ <sect2 id="docbook-markup-image-makefile-entries">
+ <title>Image <filename>Makefile</filename> Entries</title>
+
+ <para>Images must be listed in the <filename>Makefile</filename>
+ in the <makevar>IMAGES</makevar> variable. This variable must
+ contain the names of all the <emphasis>source</emphasis>
+ images. For example, if there are three figures,
+ <filename>fig1.eps</filename>, <filename>fig2.png</filename>,
+ <filename>fig3.png</filename>, then the
+ <filename>Makefile</filename> should have lines like this in
+ it.</para>
+
+ <programlisting>&hellip;
+IMAGES= fig1.eps fig2.png fig3.png
+&hellip;</programlisting>
+
+ <para>or</para>
+
+ <programlisting>&hellip;
+IMAGES= fig1.eps
+IMAGES+= fig2.png
+IMAGES+= fig3.png
+&hellip;</programlisting>
+
+ <para>Again, the <filename>Makefile</filename> will work out
+ the complete list of images it needs to build the source
+ document, you only need to list the image files
+ <emphasis>you</emphasis> provided.</para>
+ </sect2>
+
+ <sect2 id="docbook-markup-images-in-subdirectories">
+ <title>Images and Chapters in Subdirectories</title>
+
+ <para>Be careful when separating documentation into smaller
+ files in different directories (see <xref
+ linkend="xml-primer-include-using-gen-entities"/>).</para>
+
+ <para>Suppose there is a book with three chapters, and the
+ chapters are stored in their own directories, called
+ <filename>chapter1/chapter.xml</filename>,
+ <filename>chapter2/chapter.xml</filename>, and
+ <filename>chapter3/chapter.xml</filename>. If each chapter
+ has images associated with it, it is suggested to place
+ those images in each chapter's subdirectory
+ (<filename>chapter1/</filename>,
+ <filename>chapter2/</filename>, and
+ <filename>chapter3/</filename>).</para>
+
+ <para>However, doing this requires including the directory
+ names in the <makevar>IMAGES</makevar> variable in the
+ <filename>Makefile</filename>, <emphasis>and</emphasis>
+ including the directory name in the
+ <sgmltag>imagedata</sgmltag> element in the document
+ document.</para>
+
+ <para>For example, if the book has
+ <filename>chapter1/fig1.png</filename>, then
+ <filename>chapter1/chapter.xml</filename> should
+ contain:</para>
+
+ <programlisting>&lt;mediaobject>
+ &lt;imageobject>
+ &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/>
+ &lt;/imageobject>
+
+ &hellip;
+
+&lt;/mediaobject></programlisting>
+
+ <calloutlist>
+ <callout arearefs="co-image-dir">
+ <para>The directory name must be included in the
+ <literal>fileref</literal> attribute.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The <filename>Makefile</filename> must contain:</para>
+
+ <programlisting>&hellip;
+IMAGES= chapter1/fig1.png
+&hellip;</programlisting>
+
+ <para>Then everything will work.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="docbook-markup-links">
+ <title>Links</title>
+
+ <note>
+ <para>Links are also in-line elements.</para>
+ </note>
+
+ <sect2 id="docbook-markup-links-ids">
+ <title><literal>id</literal> Attributes</title>
+
+ <para>Most DocBook elements accept an <literal>id</literal>
+ attribute to give that part of the document a unique name.
+ The <literal>id</literal> can be used as a target for a
+ crossreference or link.</para>
+
+ <para>Any portion of the document that will be a link target
+ must have an <literal>id</literal> attribute. Assigning an
+ <literal>id</literal> to all chapters and sections, even if
+ there are no current plans to link to them, is a good idea.
+ These <literal>id</literal>s can be used as unique anchor
+ reference points by anyone referring to the
+ <acronym>HTML</acronym> version of the document.</para>
+
+ <example>
+ <title><literal>id</literal> on Chapters and
+ Sections</title>
+
+ <programlisting><![CDATA[<chapter id="sample-chapter1">
+ <title>Introduction</title>
+
+ <para>This is the introduction. It contains a subsection,
+ which is identified as well.</para>
+
+ <sect1 id="sample-chapter1-sect1">
+ <title>Sub-sect 1</title>
+
+ <para>This is a subsection.</para>
+ </sect1>
+</chapter>]]></programlisting>
+ </example>
+
+ <para>Use descriptive values for <literal>id</literal> names.
+ The values must be unique within the entire document, not just
+ in a single file. In the example, the subsection
+ <literal>id</literal> is constructed by appending text to the
+ chapter <literal>id</literal>. This ensures that the
+ <literal>id</literal>s are unique. It also helps both reader
+ and anyone editing the document to see where the link is
+ located within the document, similar to a directory
+ path to a file.</para>
+
+ <para>To allow the user to jump into a specific portion of the
+ document, even in the middle of a paragraph or an example, use
+ <sgmltag>anchor</sgmltag>. This element has no content, but
+ takes an <literal>id</literal> attribute.</para>
+
+ <example>
+ <title><sgmltag>anchor</sgmltag></title>
+
+ <programlisting><![CDATA[<para>This paragraph has an embedded
+ <anchor id="para1">link target in it. It will not
+ show up in the document.</para>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="docbook-markup-links-crossreferences">
+ <title>Crossreferences with <literal>xref</literal></title>
+
+ <para><sgmltag>xref</sgmltag> provides the reader with a link to
+ jump to another section of the document. The target
+ <literal>id</literal> is specified in the
+ <literal>linkend</literal> attribute, and
+ <sgmltag>xref</sgmltag> generates the link text
+ automatically.</para>
+
+ <example>
+ <title>Using <sgmltag>xref</sgmltag></title>
+
+ <para>Assume that this fragment appears somewhere in a
+ document that includes the <literal>id</literal>
+ example:</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 link text will be generated automatically, looking
+ like (<emphasis>emphasized</emphasis> text indicates the
+ link text):</para>
+
+ <blockquote>
+ <para>More information can be found in <emphasis>Chapter
+ 1, The Sample Chapter</emphasis>.</para>
+
+ <para>More specific information can be found in
+ <emphasis>Section 1.1,
+ <quote>Sample Sub-Sect</quote></emphasis>.</para>
+ </blockquote>
+ </example>
+
+ <para>The link text is generated automatically from the chapter
+ and section number and <literal>title</literal>
+ elements.</para>
+
+ <note>
+ <para><sgmltag>xref</sgmltag> cannot link to an
+ <literal>id</literal> attribute on an
+ <sgmltag>anchor</sgmltag> element. The
+ <sgmltag>anchor</sgmltag> has no content, so the
+ <sgmltag>xref</sgmltag> cannot generate the link
+ text.</para>
+ </note>
+ </sect2>
+
+ <sect2 id="docbook-markup-links-to-same-or-web-documents">
+ <title>Linking to the Same Document or Other Documents on the
+ Web</title>
+
+ <para>The link elements described here allow the writer to
+ define the link text. It is very important to use descriptive
+ link text to give the reader an idea of where the link will
+ take them. Remember that DocBook can be rendered to multiple
+ types of media. The reader may be looking at a printed book
+ or other form of media where there are no links. If the link
+ text is not descriptive enough, the reader may not be able to
+ locate the linked section.</para>
+
+ <sect3 id="docbook-markup-links-to-same-document">
+ <title>Links to the Same Document</title>
+
+ <para><sgmltag>link</sgmltag> is used to create a link
+ within the same document. The target <literal>id</literal>
+ is specified in the <literal>linkend</literal> attribute.
+ This element wraps content, which is used for the link
+ text.</para>
+
+ <example>
+ <title>Using <sgmltag>link</sgmltag></title>
+
+ <para>Assume that this fragment appears somewhere in a
+ document that includes the <literal>id</literal>
+ example.</para>
+
+ <programlisting><![CDATA[<para>More information can be found in the
+ <link linkend="chapter1">sample chapter</link>.</para>
+
+<para>More specific information can be found in the
+ <link linkend="chapter1-sect1">even more samples</link> section.</para>]]></programlisting>
+
+ <para>This output will be generated
+ (<emphasis>emphasized</emphasis> text is used to show the
+ link text):</para>
+
+ <blockquote>
+ <para>More information can be found in the
+ <emphasis>sample chapter</emphasis>.</para>
+
+ <para>More specific information can be found in the
+ <emphasis>even more samples</emphasis> section.</para>
+ </blockquote>
+ </example>
+
+ <note>
+ <para><sgmltag>link</sgmltag> can be used to include links
+ to the <literal>id</literal> of an
+ <sgmltag>anchor</sgmltag> element, since the
+ <sgmltag>link</sgmltag> content defines the link
+ text.</para>
+ </note>
+ </sect3>
+
+ <sect3 id="docbook-markup-links-to-web-documents">
+ <title>Linking to Other Documents on the Web</title>
+
+ <para>The <sgmltag>ulink</sgmltag> is used to link to
+ external documents on the web. The <literal>url</literal>
+ attribute is the <acronym>URL</acronym> of the page that the
+ link points to, and the content of the element is the text
+ that will be displayed for the user to activate.</para>
+
+ <example>
+ <title><sgmltag>ulink</sgmltag> to a &os; Documentation Web
+ Page</title>
+
+ <para>Link to the book or article <acronym>URL</acronym>
+ entity. To link to a specific chapter in a book, add a
+ slash and the chapter file name, followed by an optional
+ anchor within the chapter. For articles, link to the
+ article <acronym>URL</acronym> entity, followed by an
+ optional anchor within the article.
+ <acronym>URL</acronym> entities can be found in
+ <filename>doc/share/xml/urls.ent</filename>.</para>
+
+ <para>Usage for book links:</para>
+
+ <programlisting><![CDATA[<para>Read the <ulink
+ url="&url.books.handbook;/svn.html#svn-intro">SVN
+ introduction</ulink>, then pick the nearest mirror from
+ the list of <ulink
+ url="&url.books.handbook;/subversion-mirrors.html">Subversion
+ mirror sites</ulink>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>Read the <ulink
+ url="&url.books.handbook;/svn.html#svn-intro">SVN
+ introduction</ulink>, then pick the nearest mirror from
+ the list of <ulink
+ url="&url.books.handbook;/subversion-mirrors.html">Subversion
+ mirror sites</ulink>.</para>
+
+ <para>Usage for article links:</para>
+
+ <programlisting><![CDATA[<para>Read this <ulink url="&url.articles.bsdl-gpl;">article
+ about the BSD license</ulink>, or just the <ulink
+ url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>Read this <ulink url="&url.articles.bsdl-gpl;">article
+ about the BSD license</ulink>, or just the <ulink
+ url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>
+ </example>
+
+ <example>
+ <title><sgmltag>ulink</sgmltag> to a &os; Web Page</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>Of course, you could stop reading this document and
+ go to the <ulink url="&url.base;/index.html">FreeBSD
+ home page</ulink> instead.</para>]]></programlisting>
+
+ <para>Appearance:</para>
+
+ <para>Of course, you could stop reading this document and go
+ to the <ulink url="&url.base;/index.html">FreeBSD home
+ page</ulink> instead.</para>
+ </example>
+
+ <example>
+ <title><sgmltag>ulink</sgmltag> to an External Web
+ Page</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<para>Wikipedia has an excellent reference on
+ <ulink
+ url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
+ Partition Tables</ulink>.</para>]]></programlisting>
+
+ <para>Wikipedia has an excellent reference on
+ <ulink
+ url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
+ Partition Tables</ulink>.</para>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
index e1e15426fa..5ead068fd9 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
@@ -211,7 +211,8 @@
to the tags which surround the text or the entities that
represent that text in the <acronym>XML</acronym> file.
A reference to the commonly used tags and entities can be
- found in <xref linkend="xml-markup"/>.</para>
+ found in <xref linkend="xhtml-markup"/> and
+ <xref linkend="docbook-markup"/>.</para>
</step>
<step>
@@ -291,4 +292,4 @@
</step>
</procedure>
</sect1>
- </chapter> \ No newline at end of file
+ </chapter>
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml
deleted file mode 100644
index 49626b5055..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml
+++ /dev/null
@@ -1,2759 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
-
- Redistribution and use in source (SGML DocBook) and 'compiled' forms
- (SGML HTML, PDF, PostScript, RTF and so forth) with or without
- modification, are permitted provided that the following conditions
- are met:
-
- 1. Redistributions of source code (SGML DocBook) must retain the above
- copyright notice, this list of conditions and the following
- disclaimer as the first lines of this file unmodified.
-
- 2. Redistributions in compiled form (transformed to other DTDs,
- converted to PDF, PostScript, RTF and other formats) must reproduce
- the above copyright notice, this list of conditions and the
- following disclaimer in the documentation and/or other materials
- provided with the distribution.
-
- THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
-
- $FreeBSD$
--->
-
-<chapter id="xml-markup">
- <title>XML Markup</title>
-
- <para>This chapter describes the two markup languages you will
- encounter when you contribute to the FreeBSD documentation
- project. Each section describes the markup language, and details
- the markup that you are likely to want to use, or that is already
- in use.</para>
-
- <para>These markup languages contain a large number of elements, and
- it can be confusing sometimes to know which element to use for a
- particular situation. This section goes through the elements you
- are most likely to need, and gives examples of how you would use
- them.</para>
-
- <para>This is <emphasis>not</emphasis> an exhaustive list of
- elements, since that would just reiterate the documentation for
- each language. The aim of this section is to list those elements
- more likely to be useful to you. If you have a question about how
- best to markup a particular piece of content, please post it to
- the &a.doc;.</para>
-
- <note>
- <title>Inline Versus Block</title>
-
- <para>In the remainder of this document, when describing elements,
- <emphasis>inline</emphasis> means that the element can occur
- within a block element, and does not cause a line break. A
- <emphasis>block</emphasis> element, by comparison, will cause a
- line break (and other processing) when it is encountered.</para>
- </note>
-
- <sect1 id="xml-markup-xhtml">
- <title>XHTML</title>
-
- <para>XHTML is the XML version of the HyperText Markup Language,
- which is the markup language
- of choice on the World Wide Web. More information can be found
- at <ulink url="http://www.w3.org/"></ulink>.</para>
-
- <para>XHTML is used to markup pages on the FreeBSD web site. It
- should not (generally) be used to mark up other documentation,
- since DocBook offers a far richer set of elements to choose
- from. Consequently, you will normally only encounter XHTML 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,
- 4.0 and then an XML-compliant version has also been created, which
- is called XHTML and the latest widespread version of it is
- XHTML 1.0(available in both
- <emphasis>strict</emphasis> and <emphasis>transitional</emphasis>
- variants).</para>
-
- <para>The XHTML DTDs are available from the Ports&nbsp;Collection
- in the <filename role="package">textproc/xhtml</filename> port.
- They are automatically installed as part of the <filename
- role="package">textproc/docproj</filename> port.</para>
-
- <sect2>
- <title>Formal Public Identifier (FPI)</title>
-
- <para>There are a number of XHTML FPIs, depending upon the
- version (also known as the level) of XHTML that you want to
- declare your document to be compliant with.</para>
-
- <para>The majority of XHTML documents on the FreeBSD web site
- comply with the transitional version of XHTML 1.0.</para>
-
- <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
- </sect2>
-
- <sect2>
- <title>Sectional Elements</title>
-
- <para>An XHTML document is normally split into 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 XHTML Document Structure</title>
-
- <programlisting>&lt;html xmlns="http://www.w3.org/1999/xhtml">
- &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>XHTML 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>,
- and Other Header Tags</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 XHTML 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, preceding it. Leaving gaps in the numbering is
- to be avoided.</para>
-
- <example>
- <title>Bad Ordering of
- <sgmltag>h<replaceable>n</replaceable></sgmltag>
- Elements</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<h1>First section</h1>
-
-<!-- Document introduction -->
-
-<h3>Sub-section</h3>
-
-<!-- This is bad, <h2> has been left out -->]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Paragraphs</title>
-
- <para>XHTML supports a single paragraph element,
- <sgmltag>p</sgmltag>.</para>
-
- <example>
- <title><sgmltag>p</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any
- other element.</p>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Block Quotations</title>
-
- <para>A block quotation is an extended quotation from another
- document that should not appear within the current
- paragraph.</para>
-
- <example>
- <title><sgmltag>blockquote</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p>
-
-<blockquote>We the People of the United States, in Order to form
- a more perfect Union, establish Justice, insure domestic
- Tranquility, provide for the common defence, promote the general
- Welfare, and secure the Blessings of Liberty to ourselves and our
- Posterity, do ordain and establish this Constitution for the
- United States of America.</blockquote>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Lists</title>
-
- <para>You can present the user with three types of lists,
- ordered, unordered, and definition.</para>
-
- <para>Typically, each entry in an ordered list will be
- numbered, while each entry in an unordered list will be
- preceded by a bullet point. Definition lists are composed
- of two sections for each entry. The first section is the
- term being defined, and the second section is the definition
- of the term.</para>
-
- <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
- element, unordered lists by the <sgmltag>ul</sgmltag>
- element, and definition lists by the <sgmltag>dl</sgmltag>
- element.</para>
-
- <para>Ordered and unordered lists contain listitems, indicated
- by the <sgmltag>li</sgmltag> element. A listitem can
- contain textual content, or it may be further wrapped in one
- or more <sgmltag>p</sgmltag> elements.</para>
-
- <para>Definition lists contain definition terms
- (<sgmltag>dt</sgmltag>) and definition descriptions
- (<sgmltag>dd</sgmltag>). A definition term can only contain
- inline elements. A definition description can contain other
- block elements.</para>
-
- <example>
- <title><sgmltag>ul</sgmltag> and
- <sgmltag>ol</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>An unordered list. Listitems will probably be
- preceded by bullets.</p>
-
-<ul>
- <li>First item</li>
-
- <li>Second item</li>
-
- <li>Third item</li>
-</ul>
-
-<p>An ordered list, with list items consisting of multiple
- paragraphs. Each item (note: not each paragraph) will be
- numbered.</p>
-
-<ol>
- <li><p>This is the first item. It only has one paragraph.</p></li>
-
- <li><p>This is the first paragraph of the second item.</p>
-
- <p>This is the second paragraph of the second item.</p></li>
-
- <li><p>This is the first and only paragraph of the third
- item.</p></li>
-</ol>]]></programlisting>
- </example>
-
- <example>
- <title>Definition Lists with <sgmltag>dl</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<dl>
- <dt>Term 1</dt>
-
- <dd><p>Paragraph 1 of definition 1.</p>
-
- <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><p>Paragraph 1 of definition 3.</p></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 into 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
- email message:</para>
-
- <programlisting><![CDATA[<pre> From: nik@FreeBSD.org
- To: freebsd-doc@FreeBSD.org
- Subject: New documentation available
-
- There is a new copy of my primer for contributors to the FreeBSD
- Documentation Project available at
-
- &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;
-
- Comments appreciated.
-
- N</pre>]]></programlisting>
-
- <para>Keep in mind that <literal>&lt;</literal> and
- <literal>&amp;</literal> still are recognized as special
- characters in pre-formatted text. This is why the example
- shown had to use <literal>&amp;lt;</literal> instead of
- <literal>&lt;</literal>. For consistency,
- <literal>&amp;gt;</literal> was used in place of
- <literal>&gt;</literal>, too. Watch out for the special
- characters that may appear in text copied from a
- plain-text source, e.g., an email message or program
- code.</para>
- </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 or 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 into 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 into
- 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>Emphasizing Information</title>
-
- <para>You have two levels of emphasis available in XHTML,
- <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. According to best practices, webpages only hold
- structural and semantical information and stylesheets are
- later applied to use these two so you should think of
- semantics not formatting when using these tags.</para>
-
- <example>
- <title><sgmltag>em</sgmltag> and
- <sgmltag>strong</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p><em>This</em> has been emphasized, while
- <strong>this</strong> has been strongly emphasized.</p>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Indicating Fixed-Pitch Text</title>
-
- <para>If you have content that should be rendered in a fixed
- pitch (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
- <quote>teletype</quote>).</para>
-
- <example>
- <title><sgmltag>tt</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>This document was originally written by
- Nik Clayton, who can be reached by email as
- <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
- </example>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Links</title>
-
- <note>
- <para>Links are also inline 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 color, 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>id</literal> attribute instead of
- <literal>href</literal>.</para>
-
- <example>
- <title>Using <literal>&lt;a id="..."&gt;</literal></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p><a id="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 id 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 preceding
- <literal>#</literal>).</para>
-
- <example>
- <title>Linking to a Named Part of the Same Document</title>
-
- <para>Assume that the <literal>para1</literal> example
- resides in this document:</para>
-
- <programlisting><![CDATA[<p>More information can be found in the
- <a href="#para1">first paragraph</a> of this
- document.</p>]]></programlisting>
- </example>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="xml-markup-docbook">
- <title>DocBook</title>
-
- <para>DocBook was originally developed by HaL Computer Systems and
- O'Reilly &amp; Associates to be a DTD for writing technical
- documentation <footnote><para>A short history can be found under
- <ulink
- url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
- http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>.
- Since 1998 it is maintained by the <ulink
- url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
- DocBook Technical Committee</ulink>. As such, and unlike
- LinuxDoc and XHTML, DocBook is very heavily oriented towards
- markup that describes <emphasis>what</emphasis> something is,
- rather than describing <emphasis>how</emphasis> it should be
- presented.</para>
-
- <note>
- <title>Formal Versus Informal</title>
-
- <para>Some elements may exist in two forms,
- <emphasis>formal</emphasis> and <emphasis>informal</emphasis>.
- Typically, the formal version of the element will consist of a
- title followed by the informal version of the element. The
- informal version will not have a title.</para>
- </note>
-
- <para>The DocBook DTD is available from the Ports&nbsp;Collection
- in the <filename role="package">textproc/docbook-xml-450</filename>
- port. It is automatically installed as part of the <filename
- role="package">textproc/docproj</filename> port.</para>
-
- <sect2>
- <title>&os; Extensions</title>
-
- <para>The FreeBSD Documentation Project has extended the DocBook
- DTD by adding some new elements. These elements serve to make
- some of the markup more precise.</para>
-
- <para>Where a FreeBSD specific element is listed below it is
- clearly marked.</para>
-
- <para>Throughout the rest of this document, the term
- <quote>DocBook</quote> is used to mean the FreeBSD extended
- DocBook DTD.</para>
-
- <note>
- <para>There is nothing about these extensions that is FreeBSD
- specific, it was just felt that they were useful
- enhancements for this particular project. Should anyone
- from any of the other *nix camps (NetBSD, OpenBSD, Linux,
- &hellip;) be interested in collaborating on a standard
- DocBook extension set, please get in touch with
- &a.doceng;.</para>
- </note>
-
- <para>The &os; extensions are not (currently) in the
- Ports&nbsp;Collection. They are stored in the &os; Subversion
- tree, as <ulink
- url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para>
- </sect2>
-
- <sect2>
- <title>Formal Public Identifier (FPI)</title>
-
- <para>In compliance with the DocBook guidelines for writing FPIs
- for DocBook customizations, the FPI for the FreeBSD extended
- DocBook DTD is:</para>
-
- <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
- </sect2>
-
- <sect2>
- <title>Document Structure</title>
-
- <para>DocBook allows you to structure your documentation in
- several ways. In the FreeBSD Documentation Project we are
- using two primary types of DocBook document: the book and the
- article.</para>
-
- <para>A book is organized into <sgmltag>chapter</sgmltag>s.
- This is a mandatory requirement. There may be
- <sgmltag>part</sgmltag>s between the book and the chapter to
- provide another layer of organization. For example, the
- Handbook is arranged in this way.</para>
-
- <para>A chapter may (or may not) contain one or more sections.
- These are indicated with the <sgmltag>sect1</sgmltag> element.
- If a section contains another section then use the
- <sgmltag>sect2</sgmltag> element, and so on, up to
- <sgmltag>sect5</sgmltag>.</para>
-
- <para>Chapters and sections contain the remainder of the
- content.</para>
-
- <para>An article is simpler than a book, and does not use
- chapters. Instead, the content of an article is organized
- into one or more sections, using the same
- <sgmltag>sect1</sgmltag> (and <sgmltag>sect2</sgmltag> and so
- on) elements that are used in books.</para>
-
- <para>Obviously, you should consider the nature of the
- documentation you are writing in order to decide whether it is
- best marked up as a book or an article. Articles are well
- suited to information that does not need to be broken down
- into several chapters, and that is, relatively speaking, quite
- short, at up to 20-25 pages of content. Books are best suited
- to information that can be broken up into several chapters,
- possibly with appendices and similar content as well.</para>
-
- <para>The <ulink url="&url.base;/docs.html">FreeBSD
- tutorials</ulink> are all marked up as articles, while this
- document, the
- <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
- and the <ulink url="&url.books.handbook;/index.html">FreeBSD
- Handbook</ulink> are all marked up as books, for
- example.</para>
-
- <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 email 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 email address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
- &lt;/copyright>
-
- &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>
-
- &lt;abstract>
- &lt;para><replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para>
- &lt;/abstract>
- &lt;/bookinfo>
-
- &hellip;
-
-&lt;/book></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Starting an Article</title>
-
- <para>The content of the article is contained within the
- <sgmltag>article</sgmltag> element. As well as containing
- structural markup, this element can contain elements that
- include additional information about the article. This is
- either meta-information, used for reference purposes, or
- additional content used to produce a title page.</para>
-
- <para>This additional information should be contained within
- <sgmltag>articleinfo</sgmltag>.</para>
-
- <example>
- <title>Boilerplate <sgmltag>article</sgmltag> with
- <sgmltag>articleinfo</sgmltag></title>
-
- <!-- Can't put this in a marked section because of the
- replaceable elements -->
-
- <programlisting>&lt;article>
- &lt;articleinfo>
- &lt;title><replaceable>Your title here</replaceable>&lt;/title>
-
- &lt;author>
- &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
- &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
- &lt;affiliation>
- &lt;address>&lt;email><replaceable>Your email 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 email address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
- &lt;/copyright>
-
- &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>
-
- &lt;abstract>
- &lt;para><replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para>
- &lt;/abstract>
- &lt;/articleinfo>
-
- &hellip;
-
-&lt;/article></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Indicating Chapters</title>
-
- <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters.
- Each chapter has a mandatory <sgmltag>title</sgmltag>.
- Articles do not contain chapters, they are reserved for
- books.</para>
-
- <example>
- <title>A Simple Chapter</title>
-
- <programlisting><![CDATA[<chapter>
- <title>The Chapter's Title</title>
-
- ...
-</chapter>]]></programlisting>
- </example>
-
- <para>A chapter cannot be empty; it must contain elements in
- addition to <sgmltag>title</sgmltag>. If you need to
- include an empty chapter then just use an empty
- paragraph.</para>
-
- <example>
- <title>Empty Chapters</title>
-
- <programlisting><![CDATA[<chapter>
- <title>This is An Empty Chapter</title>
-
- <para></para>
-</chapter>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Sections Below Chapters</title>
-
- <para>In books, chapters may (but do not need to) be broken up
- into sections, subsections, and so on. In articles,
- sections are the main structural element, and each article
- must contain at least one section. Use the
- <sgmltag>sect<replaceable>n</replaceable></sgmltag> element.
- The <replaceable>n</replaceable> indicates the section
- number, which identifies the section level.</para>
-
- <para>The first
- <sgmltag>sect<replaceable>n</replaceable></sgmltag> is
- <sgmltag>sect1</sgmltag>. You can have one or more of these
- in a chapter. They can contain one or more
- <sgmltag>sect2</sgmltag> elements, and so on, down to
- <sgmltag>sect5</sgmltag>.</para>
-
- <example>
- <title>Sections in Chapters</title>
-
- <programlisting><![CDATA[<chapter>
- <title>A Sample Chapter</title>
-
- <para>Some text in the chapter.</para>
-
- <sect1>
- <title>First Section (1.1)</title>
-
- &hellip;
- </sect1>
-
- <sect1>
- <title>Second Section (1.2)</title>
-
- <sect2>
- <title>First Sub-Section (1.2.1)</title>
-
- <sect3>
- <title>First Sub-Sub-Section (1.2.1.1)</title>
-
- &hellip;
- </sect3>
- </sect2>
-
- <sect2>
- <title>Second Sub-Section (1.2.2)</title>
-
- &hellip;
- </sect2>
- </sect1>
-</chapter>]]></programlisting>
- </example>
-
- <note>
- <para>This example includes section numbers in the section
- titles. You should not do this in your documents. Adding
- the section numbers is carried out by the stylesheets (of
- which more later), and you do not need to manage them
- yourself.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Subdividing Using <sgmltag>part</sgmltag>
- Elements</title>
-
- <para>You can introduce another layer of organization between
- <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with
- one or more <sgmltag>part</sgmltag>s. This cannot be done
- in an <sgmltag>article</sgmltag>.</para>
-
- <programlisting><![CDATA[<part>
- <title>Introduction</title>
-
- <chapter>
- <title>Overview</title>
-
- ...
- </chapter>
-
- <chapter>
- <title>What is FreeBSD?</title>
-
- ...
- </chapter>
-
- <chapter>
- <title>History</title>
-
- ...
- </chapter>
-</part>]]></programlisting>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Block Elements</title>
-
- <sect3>
- <title>Paragraphs</title>
-
- <para>DocBook supports three types of paragraphs:
- <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
- <sgmltag>simpara</sgmltag>.</para>
-
- <para>Most of the time you will only need to use
- <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag>
- includes a <sgmltag>title</sgmltag> element, and
- <sgmltag>simpara</sgmltag> disallows some elements from
- within <sgmltag>para</sgmltag>. Stick with
- <sgmltag>para</sgmltag>.</para>
-
- <example>
- <title><sgmltag>para</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>This is a paragraph. It can contain just about any
- other element.</para> ]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>This is a paragraph. It can contain just about any
- other element.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Block Quotations</title>
-
- <para>A block quotation is an extended quotation from another
- document that should not appear within the current
- paragraph. You will probably only need it
- infrequently.</para>
-
- <para>Blockquotes can optionally contain a title and an
- attribution (or they can be left untitled and
- unattributed).</para>
-
- <example>
- <title><sgmltag>blockquote</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>A small excerpt from the US Constitution:</para>
-
-<blockquote>
- <title>Preamble to the Constitution of the United States</title>
-
- <attribution>Copied from a web site somewhere</attribution>
-
- <para>We the People of the United States, in Order to form a more perfect
- Union, establish Justice, insure domestic Tranquility, provide for the
- common defence, promote the general Welfare, and secure the Blessings
- of Liberty to ourselves and our Posterity, do ordain and establish this
- Constitution for the United States of America.</para>
-</blockquote>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>A small excerpt from the US Constitution:</para>
-
- <blockquote>
- <title>Preamble to the Constitution of the United
- States</title>
-
- <attribution>Copied from a web site
- somewhere</attribution>
-
- <para>We the People of the United States, in Order to form
- a more perfect Union, establish Justice, insure domestic
- Tranquility, provide for the common defence, promote the
- general Welfare, and secure the Blessings of Liberty to
- ourselves and our Posterity, do ordain and establish
- this Constitution for the United States of
- America.</para>
- </blockquote>
- </example>
- </sect3>
-
- <sect3>
- <title>Tips, Notes, Warnings, Cautions, Important Information
- and Sidebars</title>
-
- <para>You may need to include extra information separate from
- the main body of the text. Typically this is
- <quote>meta</quote> information that the user should be
- aware of.</para>
-
- <para>Depending on the nature of the information, one of
- <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
- <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
- <sgmltag>important</sgmltag> should be used. Alternatively,
- if the information is related to the main text but is not
- one of the above, use <sgmltag>sidebar</sgmltag>.</para>
-
- <para>The circumstances in which to choose one of these
- elements over another is unclear. The DocBook documentation
- suggests:</para>
-
- <itemizedlist>
- <listitem>
- <para>A Note is for information that should be heeded by
- all readers.</para>
- </listitem>
-
- <listitem>
- <para>An Important element is a variation on Note.</para>
- </listitem>
-
- <listitem>
- <para>A Caution is for information regarding possible data
- loss or software damage.</para>
- </listitem>
-
- <listitem>
- <para>A Warning is for information regarding possible
- hardware damage or injury to life or limb.</para>
- </listitem>
- </itemizedlist>
-
- <example>
- <title><sgmltag>warning</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<warning>
- <para>Installing FreeBSD may make you want to delete Windows from your
- hard disk.</para>
-</warning>]]></programlisting>
- </example>
-
- <para>Appearance:</para>
- <!-- Need to do this outside of the example -->
- <warning>
- <para>Installing FreeBSD may make you want to delete Windows
- from your hard disk.</para>
- </warning>
- </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 are not
- concerned with those at the
- moment.</para></footnote></para>
-
- <para><sgmltag>itemizedlist</sgmltag> and
- <sgmltag>orderedlist</sgmltag> are similar to their
- counterparts in HTML, <sgmltag>ul</sgmltag> and
- <sgmltag>ol</sgmltag>. Each one consists of one or more
- <sgmltag>listitem</sgmltag> elements, and each
- <sgmltag>listitem</sgmltag> contains one or more block
- elements. The <sgmltag>listitem</sgmltag> elements are
- analogous to HTML's <sgmltag>li</sgmltag> tags. However,
- unlike HTML, they are required.</para>
-
- <para><sgmltag>procedure</sgmltag> is slightly different. It
- consists of <sgmltag>step</sgmltag>s, which may in turn
- consists of more <sgmltag>step</sgmltag>s or
- <sgmltag>substep</sgmltag>s. Each <sgmltag>step</sgmltag>
- contains block elements.</para>
-
- <example>
- <title><sgmltag>itemizedlist</sgmltag>,
- <sgmltag>orderedlist</sgmltag>, and
- <sgmltag>procedure</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<itemizedlist>
- <listitem>
- <para>This is the first itemized item.</para>
- </listitem>
-
- <listitem>
- <para>This is the second itemized item.</para>
- </listitem>
-</itemizedlist>
-
-<orderedlist>
- <listitem>
- <para>This is the first ordered item.</para>
- </listitem>
-
- <listitem>
- <para>This is the second ordered item.</para>
- </listitem>
-</orderedlist>
-
-<procedure>
- <step>
- <para>Do this.</para>
- </step>
-
- <step>
- <para>Then do this.</para>
- </step>
-
- <step>
- <para>And now do this.</para>
- </step>
-</procedure>]]></programlisting>
-
- <para>Appearance:</para>
-
- <itemizedlist>
- <listitem>
- <para>This is the first itemized item.</para>
- </listitem>
-
- <listitem>
- <para>This is the second itemized item.</para>
- </listitem>
- </itemizedlist>
-
- <orderedlist>
- <listitem>
- <para>This is the first ordered item.</para>
- </listitem>
-
- <listitem>
- <para>This is the second ordered item.</para>
- </listitem>
- </orderedlist>
- </example>
-
- <!-- Can't have <procedure> inside <example>, so this is a cheat -->
-
- <procedure>
- <step>
- <para>Do this.</para>
- </step>
-
- <step>
- <para>Then do this.</para>
- </step>
-
- <step>
- <para>And now do this.</para>
- </step>
- </procedure>
- </sect3>
-
- <sect3>
- <title>Showing File Samples</title>
-
- <para>If you want to show a fragment of a file (or perhaps a
- complete file) to the user, wrap it in the
- <sgmltag>programlisting</sgmltag> element.</para>
-
- <para>White space and line breaks within
- <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
- significant. In particular, this means that the opening tag
- should appear on the same line as the first line of the
- output, and the closing tag should appear on the same line
- as the last line of the output, otherwise spurious blank
- lines may be included.</para>
-
- <example>
- <title><sgmltag>programlisting</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>When you have finished, your program should look like
- this:</para>
-
-<programlisting>#include &lt;stdio.h&gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}</programlisting>]]></programlisting>
-
- <para>Notice how the angle brackets in the
- <literal>#include</literal> line need to be referenced by
- their entities instead of being included literally.</para>
-
- <para>Appearance:</para>
-
- <para>When you have finished, your program should look like
- this:</para>
-
- <programlisting>#include &lt;stdio.h&gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}</programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Callouts</title>
-
- <para>A callout is a mechanism for referring back to an
- earlier piece of text or specific position within an earlier
- example without linking to it within the text.</para>
-
- <para>To do this, mark areas of interest in your example
- (<sgmltag>programlisting</sgmltag>,
- <sgmltag>literallayout</sgmltag>, or whatever) with the
- <sgmltag>co</sgmltag> element. Each element must have a
- unique <literal>id</literal> assigned to it. After the
- example include a <sgmltag>calloutlist</sgmltag> that refers
- back to the example and provides additional
- commentary.</para>
-
- <example>
- <title><sgmltag>co</sgmltag> and
- <sgmltag>calloutlist</sgmltag></title>
-
- <programlisting><![CDATA[<para>When you have finished, your program should look like
- this:</para>
-
-<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>
-
-int <co id="co-ex-return"/>
-main(void)
-{
- printf("hello, world\n"); <co id="co-ex-printf"/>
-}</programlisting>
-
-<calloutlist>
- <callout arearefs="co-ex-include">
- <para>Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para>Specifies that <function>main()</function> returns an
- int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para>The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard output.</para>
- </callout>
-</calloutlist>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>When you have finished, your program should look like
- this:</para>
-
- <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/>
-
-int <co id="co-ex-return"/>
-main(void)
-{
- printf("hello, world\n"); <co id="co-ex-printf"/>
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="co-ex-include">
- <para>Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para>Specifies that <function>main()</function> returns
- an int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para>The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard
- output.</para>
- </callout>
- </calloutlist>
- </example>
- </sect3>
-
- <sect3>
- <title>Tables</title>
-
- <para>Unlike HTML, you do not need to use tables for layout
- purposes, as the stylesheet handles those issues for you.
- Instead, just use tables for marking up tabular data.</para>
-
- <para>In general terms (and see the DocBook documentation for
- more detail) a table (which can be either formal or
- informal) consists of a <sgmltag>table</sgmltag> element.
- This contains at least one <sgmltag>tgroup</sgmltag>
- element, which specifies (as an attribute) the number of
- columns in this table group. Within the tablegroup you can
- then have one <sgmltag>thead</sgmltag> element, which
- contains elements for the table headings (column headings),
- and one <sgmltag>tbody</sgmltag> which contains the body of
- the table.</para>
-
- <para>Both <sgmltag>tgroup</sgmltag> and
- <sgmltag>thead</sgmltag> contain <sgmltag>row</sgmltag>
- elements, which in turn contain <sgmltag>entry</sgmltag>
- elements. Each <sgmltag>entry</sgmltag> element specifies
- one cell in the table.</para>
-
- <example>
- <title><sgmltag>informaltable</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<informaltable pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>This is Column Head 1</entry>
- <entry>This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Row 1, column 1</entry>
- <entry>Row 1, column 2</entry>
- </row>
-
- <row>
- <entry>Row 2, column 1</entry>
- <entry>Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>]]></programlisting>
-
- <para>Appearance:</para>
-
- <informaltable pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>This is Column Head 1</entry>
- <entry>This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Row 1, column 1</entry>
- <entry>Row 1, column 2</entry>
- </row>
-
- <row>
- <entry>Row 2, column 1</entry>
- <entry>Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </example>
-
- <para>Always use the <literal>pgwide</literal> attribute with
- a value of <literal>1</literal> with the
- <sgmltag>informaltable</sgmltag> element. A bug in Internet
- Explorer can cause the table to render incorrectly if this
- is omitted.</para>
-
- <para>If you do not 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" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>This is Column Head 1</entry>
- <entry>This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Row 1, column 1</entry>
- <entry>Row 1, column 2</entry>
- </row>
-
- <row>
- <entry>Row 2, column 1</entry>
- <entry>Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </example>
- </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 into
- play here.</para>
-
- <variablelist>
- <varlistentry>
- <term><sgmltag>screen</sgmltag></term>
-
- <listitem>
- <para>Everything the user sees in this example will be
- on the computer screen, so the next element is
- <sgmltag>screen</sgmltag>.</para>
-
- <para>Within <sgmltag>screen</sgmltag>, white space is
- significant.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><sgmltag>prompt</sgmltag>,
- <literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal></term>
-
- <listitem>
- <para>Some of the things the user will be seeing on the
- screen are prompts from the computer (either from the
- operating system, command shell, or application).
- These should be marked up using
- <sgmltag>prompt</sgmltag>.</para>
-
- <para>As a special case, the two shell prompts for the
- normal user and the root user have been provided as
- entities. Every time you want to indicate the user is
- at a shell prompt, use one of
- <literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> as necessary.
- They do not need to be inside
- <sgmltag>prompt</sgmltag>.</para>
-
- <note>
- <para><literal>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> are FreeBSD
- extensions to DocBook, and are not part of the
- original DTD.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><sgmltag>userinput</sgmltag></term>
-
- <listitem>
- <para>When displaying text that the user should type in,
- wrap it in <sgmltag>userinput</sgmltag> tags. It will
- probably be displayed differently to the user.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>,
- and <sgmltag>userinput</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput>
-foo1
-foo2
-foo3
-&prompt.user; <userinput>ls -1 | grep foo2</userinput>
-foo2
-&prompt.user; <userinput>su</userinput>
-<prompt>Password: </prompt>
-&prompt.root; <userinput>cat foo2</userinput>
-This is the file called 'foo2'</screen>]]></programlisting>
-
- <para>Appearance:</para>
-
- <screen>&prompt.user; <userinput>ls -1</userinput>
-foo1
-foo2
-foo3
-&prompt.user; <userinput>ls -1 | grep foo2</userinput>
-foo2
-&prompt.user; <userinput>su</userinput>
-<prompt>Password: </prompt>
-&prompt.root; <userinput>cat foo2</userinput>
-This is the file called 'foo2'</screen>
- </example>
-
- <note>
- <para>Even though we are displaying the contents of the file
- <filename>foo2</filename>, it is <emphasis>not</emphasis>
- marked up as <sgmltag>programlisting</sgmltag>. Reserve
- <sgmltag>programlisting</sgmltag> for showing fragments of
- files outside the context of user actions.</para>
- </note>
- </sect3>
- </sect2>
-
- <sect2>
- <title>In-line Elements</title>
-
- <sect3>
- <title>Emphasizing Information</title>
-
- <para>When you want to emphasize a particular word or phrase,
- use <sgmltag>emphasis</sgmltag>. This may be presented as
- italic, or bold, or might be spoken differently with a
- text-to-speech system.</para>
-
- <para>There is no way to change the presentation of the
- emphasis within 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>Quotations</title>
-
- <para>To quote text from another document or source, or to
- denote a phrase that is used figuratively, use
- <sgmltag>quote</sgmltag>. Within a <sgmltag>quote</sgmltag>
- tag, you may use most of the markup tags available for
- normal text.</para>
-
- <example>
- <title>Quotations</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the
- <quote>boundary between local and public administration</quote>,
- as RFC 1535 calls it.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>However, make sure that the search does not go beyond
- the <quote>boundary between local and public
- administration</quote>, as RFC 1535 calls it.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Keys, Mouse Buttons, and Combinations</title>
-
- <para>To refer to a specific key on the keyboard, use
- <sgmltag>keycap</sgmltag>. To refer to a mouse button, use
- <sgmltag>mousebutton</sgmltag>. And to refer to
- combinations of key presses or mouse clicks, wrap them all
- in <sgmltag>keycombo</sgmltag>.</para>
-
- <para><sgmltag>keycombo</sgmltag> has an attribute called
- <literal>action</literal>, which may be one of
- <literal>click</literal>, <literal>double-click</literal>,
- <literal>other</literal>, <literal>press</literal>,
- <literal>seq</literal>, or <literal>simul</literal>. The
- last two values denote whether the keys or buttons should be
- pressed in sequence, or simultaneously.</para>
-
- <para>The stylesheets automatically add any connecting
- symbols, such as <literal>+</literal>, between the key
- names, when wrapped in <sgmltag>keycombo</sgmltag>.</para>
-
- <example>
- <title>Keys, Mouse Buttons, and Combinations</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>To switch to the second virtual terminal, press
- <keycombo action="simul"><keycap>Alt</keycap>
- <keycap>F1</keycap></keycombo>.</para>
-
-<para>To exit <command>vi</command> without saving your work, type
- <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
- <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
-
-<para>My window manager is configured so that
- <keycombo action="simul"><keycap>Alt</keycap>
- <mousebutton>right</mousebutton>
- </keycombo> mouse button is used to move windows.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>To switch to the second virtual terminal, press
- <keycombo action="simul"><keycap>Alt</keycap>
- <keycap>F1</keycap></keycombo>.</para>
-
- <para>To exit <command>vi</command> without saving your
- work, type <keycombo action="seq">
- <keycap>Esc</keycap>
- <keycap>:</keycap>
- <keycap>q</keycap>
- <keycap>!</keycap></keycombo>.</para>
-
- <para>My window manager is configured so that
- <keycombo action="simul">
- <keycap>Alt</keycap>
- <mousebutton>right</mousebutton></keycombo> mouse button
- is used to move windows.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Applications, Commands, Options, and Cites</title>
-
- <para>You will frequently want to refer to both applications
- and commands when writing documentation. The distinction
- between them is simple: an application is the name for a
- suite (or possibly just 1) of programs that fulfill a
- particular task. A command is the name of a program that
- the user can run.</para>
-
- <para>In addition, you will occasionally need to list one or
- more of the options that a command might take.</para>
-
- <para>Finally, you will often want to list a command with its
- manual section number, in the <quote>command(number)</quote>
- format so common in Unix manuals.</para>
-
- <para>Mark up application names with
- <sgmltag>application</sgmltag>.</para>
-
- <para>When you want to list a command with its manual section
- number (which should be most of the time) the DocBook
- element is <sgmltag>citerefentry</sgmltag>. This will
- contain a further two elements,
- <sgmltag>refentrytitle</sgmltag> and
- <sgmltag>manvolnum</sgmltag>. The content of
- <sgmltag>refentrytitle</sgmltag> is the name of the command,
- and the content of <sgmltag>manvolnum</sgmltag> is the
- manual page section.</para>
-
- <para>This can be cumbersome to write, and so a series of
- <link linkend="xml-primer-general-entities">general
- entities</link> have been created to make this easier.
- Each entity takes the form
- <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
-
- <para>The file that contains these entities is in
- <filename>doc/share/xml/man-refs.ent</filename>, and can be
- referred to using this FPI:</para>
-
- <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
-
- <para>Therefore, the introduction to your documentation will
- probably look like this:</para>
-
- <programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
-
-&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
-%man;
-
-&hellip;
-
-]&gt;</programlisting>
-
- <para>Use <sgmltag>command</sgmltag> when you want to include
- a command name <quote>in-line</quote> but present it as
- something the user should type in.</para>
-
- <para>Use <sgmltag>option</sgmltag> to mark up the options
- which will be passed to a command.</para>
-
- <para>When referring to the same command multiple times in
- close proximity it is preferred to use the
- <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
- notation to markup the first reference and use
- <sgmltag>command</sgmltag> to markup subsequent references.
- This makes the generated output, especially HTML, appear
- visually better.</para>
-
- <para>This can be confusing, and sometimes the choice is not
- always clear. Hopefully this example makes it
- clearer.</para>
-
- <example>
- <title>Applications, Commands, and Options</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para><application>Sendmail</application> is the most
- widely used Unix mail application.</para>
-
-<para><application>Sendmail</application> includes the
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
- programs.</para>
-
-<para>One of the command line parameters to <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, <option>-bp</option>, will display the current
- status of messages in the mail queue. Check this on the command
- line by running <command>sendmail -bp</command>.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para><application>Sendmail</application> is the most widely
- used Unix mail application.</para>
-
- <para><application>Sendmail</application> includes the
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
- programs.</para>
-
- <para>One of the command line parameters to
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, <option>-bp</option>, will display the
- current status of messages in the mail queue. Check this
- on the command line by running
- <command>sendmail -bp</command>.</para>
- </example>
-
- <note>
- <para>Notice how the
- <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
- notation is easier to follow.</para>
- </note>
- </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 class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first
- file is called <filename>book.xml</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.xml</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>The Name of Ports</title>
-
- <note>
- <title>&os; 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 might need to include the name of a program from the
- FreeBSD Ports Collection in the documentation. Use the
- <sgmltag>filename</sgmltag> tag with the
- <literal>role</literal> attribute set to
- <literal>package</literal> to identify these. Since ports
- can be installed in any number of locations, only include
- the category and the port name; do not include
- <filename>/usr/ports</filename>.</para>
-
- <example>
- <title><sgmltag>filename</sgmltag> Tag with
- <literal>package</literal> Role</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>Install the <filename
- role="package">net/ethereal</filename> port to view
- network traffic.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Devices</title>
-
- <note>
- <title>&os; 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>
-
-<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>&os; 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 <literal>role</literal> attribute, or
- <literal>role="hostname"</literal></term>
-
- <listitem>
- <para>With no <literal>role</literal> attribute (i.e.,
- <sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>)
- the marked up information is the simple hostname, such
- as <literal>freefall</literal> or
- <literal>wcarchive</literal>. You can explicitly
- specify this with
- <literal>role="hostname"</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>role="domainname"</literal></term>
-
- <listitem>
- <para>The text is a domain name, such as
- <literal>FreeBSD.org</literal> or
- <literal>ngo.org.uk</literal>. There is no hostname
- component.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>role="fqdn"</literal></term>
-
- <listitem>
- <para>The text is a Fully Qualified Domain Name, with
- both hostname and domain name parts.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>role="ipaddr"</literal></term>
-
- <listitem>
- <para>The text is an IP address, probably expressed as a
- dotted quad.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>role="ip6addr"</literal></term>
-
- <listitem>
- <para>The text is an IPv6 address.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>role="netmask"</literal></term>
-
- <listitem>
- <para>The text is a network mask, which might be
- expressed as a dotted quad, a hexadecimal string, or
- as a <literal>/</literal> followed by a number.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>role="mac"</literal></term>
-
- <listitem>
- <para>The text is an Ethernet MAC address, expressed as
- a series of 2 digit hexadecimal numbers separated by
- colons.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title><sgmltag>hostid</sgmltag> and Roles</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>The local machine can always be referred to by the
- name <hostid>localhost</hostid>, which will have the IP address
- <hostid role="ipaddr">127.0.0.1</hostid>.</para>
-
-<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
- contains a number of different hosts, including
- <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
- <hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>
-
-<para>When adding an IP alias to an interface (using
- <command>ifconfig</command>) <emphasis>always</emphasis> use a
- netmask of <hostid role="netmask">255.255.255.255</hostid>
- (which can also be expressed as <hostid
- role="netmask">0xffffffff</hostid>).</para>
-
-<para>The MAC address uniquely identifies every network card
- in existence. A typical MAC address looks like <hostid
- role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>The local machine can always be referred to by the
- name <hostid>localhost</hostid>, which will have the IP
- address <hostid role="ipaddr">127.0.0.1</hostid>.</para>
-
- <para>The <hostid role="domainname">FreeBSD.org</hostid>
- domain contains a number of different hosts, including
- <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
- <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
-
- <para>When adding an IP alias to an interface (using
- <command>ifconfig</command>) <emphasis>always</emphasis>
- use a netmask of
- <hostid role="netmask">255.255.255.255</hostid>
- (which can also be expressed as <hostid
- role="netmask">0xffffffff</hostid>).</para>
-
- <para>The MAC address uniquely identifies every network card
- in existence. A typical MAC address looks like <hostid
- role="mac">08:00:20:87:ef:d0</hostid>.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Usernames</title>
-
- <note>
- <title>&os; 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>&os; Extension</title>
-
- <para>These elements are part of the FreeBSD extension to
- DocBook, and do not exist in the original DocBook
- DTD.</para>
- </note>
-
- <para>Two elements exist to describe parts of
- <filename>Makefile</filename>s,
- <sgmltag>maketarget</sgmltag> and
- <sgmltag>makevar</sgmltag>.</para>
-
- <para><sgmltag>maketarget</sgmltag> identifies a build target
- exported by a <filename>Makefile</filename> that can be
- given as a parameter to <command>make</command>.
- <sgmltag>makevar</sgmltag> identifies a variable that can be
- set (in the environment, on the <command>make</command>
- command line, or within the <filename>Makefile</filename>)
- to influence the process.</para>
-
- <example>
- <title><sgmltag>maketarget</sgmltag> and
- <sgmltag>makevar</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>Two common targets in a <filename>Makefile</filename>
- are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
-
-<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
- application, and invoking <maketarget>clean</maketarget> will remove
- the temporary files (<filename>.o</filename> for example) created by
- the build process.</para>
-
-<para><maketarget>clean</maketarget> may be controlled by a number of
- variables, including <makevar>CLOBBER</makevar> and
- <makevar>RECURSE</makevar>.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>Two common targets in a <filename>Makefile</filename>
- are <maketarget>all</maketarget> and
- <maketarget>clean</maketarget>.</para>
-
- <para>Typically, invoking <maketarget>all</maketarget> will
- rebuild the application, and invoking
- <maketarget>clean</maketarget> will remove the temporary
- files (<filename>.o</filename> for example) created by the
- build process.</para>
-
- <para><maketarget>clean</maketarget> may be controlled by a
- number of variables, including <makevar>CLOBBER</makevar>
- and <makevar>RECURSE</makevar>.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Literal Text</title>
-
- <para>You will often need to include <quote>literal</quote>
- text in the documentation. This is text that is excerpted
- from another file, or which should be copied from the
- documentation into another file verbatim.</para>
-
- <para>Some of the time, <sgmltag>programlisting</sgmltag> will
- be sufficient to denote this text.
- <sgmltag>programlisting</sgmltag> is not always appropriate,
- particularly when you want to include a portion of a file
- <quote>in-line</quote> with the rest of the
- paragraph.</para>
-
- <para>On these occasions, use
- <sgmltag>literal</sgmltag>.</para>
-
- <example>
- <title><sgmltag>literal</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>The <literal>maxusers 10</literal> line in the kernel
- configuration file determines the size of many system tables, and is
- a rough guide to how many simultaneous logins the system will
- support.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>The <literal>maxusers 10</literal> line in the kernel
- configuration file determines the size of many system
- tables, and is a rough guide to how many simultaneous
- logins the system will support.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Showing Items That the User <emphasis>Must</emphasis>
- Fill In</title>
-
- <para>There will often be times when you want to show the user
- what to do, or refer to a file, or command line, or similar,
- where the user cannot simply copy the examples that you
- provide, but must instead include some information
- themselves.</para>
-
- <para><sgmltag>replaceable</sgmltag> is designed for this
- eventuality. Use it <emphasis>inside</emphasis> other
- elements to indicate parts of that element's content that
- the user must replace.</para>
-
- <example>
- <title><sgmltag>replaceable</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></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>
-
- <sect3>
- <title>Quoting System Errors</title>
-
- <para>You might want to show errors generated by FreeBSD.
- Mark these with <sgmltag>errorname</sgmltag>. This
- indicates the exact error that appears.</para>
-
- <example>
- <title><sgmltag>errorname</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[
-<screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
-</programlisting>
-
-
- <para>Appearance:</para>
-
- <informalexample>
- <screen><errorname>Panic: cannot mount root</errorname></screen>
- </informalexample>
- </example>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Images</title>
-
- <important>
- <para>Image support in the documentation is currently
- extremely experimental. The mechanisms described here are
- unlikely to change, but that is not guaranteed.</para>
-
- <para>You will also need to install the
- <filename role="package">graphics/ImageMagick</filename>
- port, which is used to convert between the different image
- formats. This is a big port, and most of it is not
- required. However, while we are working on the
- <filename>Makefile</filename>s and other infrastructure it
- makes things easier. This port is <emphasis>not</emphasis>
- in the <filename role="package">textproc/docproj</filename>
- meta port, you must install it by hand.</para>
-
- <para>The best example of what follows in practice is the
- <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
- document. If you are unsure of the description that
- follows, take a look at the files in that directory to see
- how everything hangs together. Experiment with creating
- different formatted versions of the document to see how the
- image markup appears in the formatted output.</para>
- </important>
-
- <sect3>
- <title>Image Formats</title>
-
- <para>We currently support two formats for images. The format
- you should use will depend on the nature of your
- image.</para>
-
- <para>For images that are primarily vector based, such as
- network diagrams, time lines, and similar, use Encapsulated
- Postscript, and make sure that your images have the
- <filename>.eps</filename> extension.</para>
-
- <para>For bitmaps, such as screen captures, use the Portable
- Network Graphic format, and make sure that your images have
- the <filename>.png</filename> extension.</para>
-
- <para>These are the <emphasis>only</emphasis> formats in which
- images should be committed to the Subversion
- repository.</para>
-
- <para>Use the right format for the right image. It is to be
- expected that your documentation will have a mix of EPS and
- PNG images. The <filename>Makefile</filename>s ensure that
- the correct format image is chosen depending on the output
- format that you use for your documentation. <emphasis>Do
- not commit the same image to the repository in two different
- formats</emphasis>.</para>
-
- <important>
- <para>It is anticipated that the Documentation Project will
- switch to using the Scalable Vector Graphic (SVG) format
- for vector images. However, the current state of SVG
- capable editing tools makes this impractical.</para>
- </important>
- </sect3>
-
- <sect3>
- <title>Markup</title>
-
- <para>The markup for an image is relatively simple. First,
- markup a <sgmltag>mediaobject</sgmltag>. The
- <sgmltag>mediaobject</sgmltag> can contain other, more
- specific objects. We are concerned with two, the
- <sgmltag>imageobject</sgmltag> and the
- <sgmltag>textobject</sgmltag>.</para>
-
- <para>You should include one <sgmltag>imageobject</sgmltag>,
- and two <sgmltag>textobject</sgmltag> elements. The
- <sgmltag>imageobject</sgmltag> will point to the name of the
- image file that will be used (without the extension). The
- <sgmltag>textobject</sgmltag> elements contain information
- that will be presented to the user as well as, or instead
- of, the image.</para>
-
- <para>There are two circumstances where this can
- happen.</para>
-
- <itemizedlist>
- <listitem>
- <para>When the reader is viewing the documentation in
- HTML. In this case, each image will need to have
- associated alternate text to show the user, typically
- whilst the image is loading, or if they hover the mouse
- pointer over the image.</para>
- </listitem>
-
- <listitem>
- <para>When the reader is viewing the documentation in
- plain text. In this case, each image should have an
- ASCII art equivalent to show the user.</para>
- </listitem>
- </itemizedlist>
-
- <para>An example will probably make things easier to
- understand. Suppose you have an image, called
- <filename>fig1.png</filename>, that you want to include in the
- document. This image is of a rectangle with an A inside it.
- The markup for this would be as follows.</para>
-
- <programlisting>&lt;mediaobject>
- &lt;imageobject>
- &lt;imagedata fileref="fig1"> <co id="co-image-ext"/>
- &lt;/imageobject>
-
- &lt;textobject>
- &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal"/>
-| A |
-+---------------+&lt;/literallayout>
- &lt;/textobject>
-
- &lt;textobject>
- &lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase"/>
- &lt;/textobject>
-&lt;/mediaobject></programlisting>
-
- <calloutlist>
- <callout arearefs="co-image-ext">
- <para>Include an <sgmltag>imagedata</sgmltag> element
- inside the <sgmltag>imageobject</sgmltag> element. The
- <literal>fileref</literal> attribute should contain the
- filename of the image to include, without the extension.
- The stylesheets will work out which extension should be
- added to the filename automatically.</para>
- </callout>
-
- <callout arearefs="co-image-literal">
-
- <para>The first <sgmltag>textobject</sgmltag> should
- contain a <sgmltag>literallayout</sgmltag> element,
- where the <literal>class</literal> attribute is set to
- <literal>monospaced</literal>. This is your opportunity
- to demonstrate your ASCII art skills. This content will
- be used if the document is converted to plain
- text.</para>
-
- <para>Notice how the first and last lines of the content
- of the <sgmltag>literallayout</sgmltag> element butt up
- next to the element's tags. This ensures no extraneous
- white space is included.</para>
- </callout>
-
- <callout arearefs="co-image-phrase">
- <para>The second <sgmltag>textobject</sgmltag> should
- contain a single <sgmltag>phrase</sgmltag> element. The
- contents of this will become the <literal>alt</literal>
- attribute for the image when this document is converted
- to HTML.</para>
- </callout>
- </calloutlist>
- </sect3>
-
- <sect3>
- <title><filename>Makefile</filename> Entries</title>
-
- <para>Your images must be listed in the
- <filename>Makefile</filename> in the
- <makevar>IMAGES</makevar> variable. This variable should
- contain the name of all your <emphasis>source</emphasis>
- images. For example, if you have created three figures,
- <filename>fig1.eps</filename>,
- <filename>fig2.png</filename>,
- <filename>fig3.png</filename>, then your
- <filename>Makefile</filename> should have lines like this in
- it.</para>
-
- <programlisting>&hellip;
-IMAGES= fig1.eps fig2.png fig3.png
-&hellip;</programlisting>
-
- <para>or</para>
-
- <programlisting>&hellip;
-IMAGES= fig1.eps
-IMAGES+= fig2.png
-IMAGES+= fig3.png
-&hellip;</programlisting>
-
- <para>Again, the <filename>Makefile</filename> will work out
- the complete list of images it needs to build your source
- document, you only need to list the image files
- <emphasis>you</emphasis> provided.</para>
- </sect3>
-
- <sect3>
- <title>Images and Chapters in Subdirectories</title>
-
- <para>You must be careful when you separate your documentation
- into smaller files (see
- <xref linkend="xml-primer-include-using-gen-entities"/>) in
- different directories.</para>
-
- <para>Suppose you have a book with three chapters, and the
- chapters are stored in their own directories, called
- <filename>chapter1/chapter.xml</filename>,
- <filename>chapter2/chapter.xml</filename>, and
- <filename>chapter3/chapter.xml</filename>. If each chapter
- has images associated with it, it is suggested to place
- those images in each chapter's subdirectory
- (<filename>chapter1/</filename>,
- <filename>chapter2/</filename>, and
- <filename>chapter3/</filename>).</para>
-
- <para>However, if you do this you must include the directory
- names in the <makevar>IMAGES</makevar> variable in the
- <filename>Makefile</filename>, <emphasis>and</emphasis> you
- must include the directory name in the
- <sgmltag>imagedata</sgmltag> element in your
- document.</para>
-
- <para>For example, if you have
- <filename>chapter1/fig1.png</filename>, then
- <filename>chapter1/chapter.xml</filename> should
- contain:</para>
-
- <programlisting>&lt;mediaobject>
- &lt;imageobject>
- &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/>
- &lt;/imageobject>
-
- &hellip;
-
-&lt;/mediaobject></programlisting>
-
- <calloutlist>
- <callout arearefs="co-image-dir">
- <para>The directory name must be included in the
- <literal>fileref</literal> attribute.</para>
- </callout>
- </calloutlist>
-
- <para>The <filename>Makefile</filename> must contain:</para>
-
- <programlisting>&hellip;
-IMAGES= chapter1/fig1.png
-&hellip;</programlisting>
-
- <para>Then everything should just work.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Links</title>
-
- <note>
- <para>Links are also in-line elements.</para>
- </note>
-
- <sect3>
- <title>Linking to Other Parts of the Same Document</title>
-
- <para>Linking within the same document requires you to specify
- where you are linking from (i.e., the text the user will
- click, or otherwise indicate, as the source of the link) and
- where you are linking to (the link's destination).</para>
-
- <para>Each element within DocBook has an attribute called
- <literal>id</literal>. You can place text in this attribute
- to uniquely name the element it is attached to.</para>
-
- <para>This value will be used when you specify the link
- source.</para>
-
- <para>Normally, you will only be linking to chapters or
- sections, so you would add the <literal>id</literal>
- attribute to these elements.</para>
-
- <example>
- <title>Attribute <literal>id</literal> on Chapters and
- Sections</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 will not show up in
- the document.</para>]]></programlisting>
- </example>
-
- <para>When you want to provide the user with a link they can
- activate (probably by clicking) to go to a section of the
- document that has an <literal>id</literal> attribute, you
- can use either <sgmltag>xref</sgmltag> or
- <sgmltag>link</sgmltag>.</para>
-
- <para>Both of these elements have a <literal>linkend</literal>
- attribute. The value of this attribute should be the value
- that you have used in a <literal>id</literal> attribute (it
- does not matter if that value has not yet occurred in your
- document; this will work for forward links as well as
- backward links).</para>
-
- <para>If you use <sgmltag>xref</sgmltag> then you have no
- control over the text of the link. It will be generated for
- you.</para>
-
- <example>
- <title>Using <sgmltag>xref</sgmltag></title>
-
- <para>Assume that this fragment appears somewhere in a
- document that includes the <literal>id</literal>
- example:</para>
-
- <programlisting><![CDATA[<para>More information can be found
- in <xref linkend="chapter1"/>.</para>
-
-<para>More specific information can be found
- in <xref linkend="chapter1-sect1"/>.</para>]]></programlisting>
-
- <para>The text of the link will be generated automatically,
- and will look like (<emphasis>emphasized</emphasis> text
- indicates the text that will be the link):</para>
-
- <blockquote>
- <para>More information can be found in <emphasis>Chapter
- One</emphasis>.</para>
-
- <para>More specific information can be found in
- <emphasis>the section called Sub-Sect
- 1</emphasis>.</para>
- </blockquote>
- </example>
-
- <para>Notice how the text from the link is derived from the
- section title or the chapter number.</para>
-
- <note>
- <para>This means that you <emphasis>cannot</emphasis> use
- <sgmltag>xref</sgmltag> to link to an
- <literal>id</literal> attribute on an
- <sgmltag>anchor</sgmltag> element. The
- <sgmltag>anchor</sgmltag> has no content, so the
- <sgmltag>xref</sgmltag> cannot generate the text for the
- link.</para>
- </note>
-
- <para>If you want to control the text of the link then use
- <sgmltag>link</sgmltag>. This element wraps content, and
- the content will be used for the link.</para>
-
- <example>
- <title>Using <sgmltag>link</sgmltag></title>
-
- <para>Assume that this fragment appears somewhere in a
- document that includes the <literal>id</literal>
- example.</para>
-
- <programlisting><![CDATA[<para>More information can be found in
- <link linkend="chapter1">the first chapter</link>.</para>
-
-<para>More specific information can be found in
- <link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting>
-
- <para>This will generate the following
- (<emphasis>emphasized</emphasis> text indicates the text
- that will be the link):</para>
-
- <blockquote>
- <para>More information can be found in <emphasis>the first
- chapter</emphasis>.</para>
-
- <para>More specific information can be found in
- <emphasis>this</emphasis> section.</para>
- </blockquote>
- </example>
-
- <note>
- <para>That last one is a bad example. Never use words like
- <quote>this</quote> or <quote>here</quote> as the source
- for the link. The reader will need to hunt around the
- surrounding context to see where the link is actually
- taking them.</para>
- </note>
-
- <note>
- <para>You <emphasis>can</emphasis> use
- <sgmltag>link</sgmltag> to include a link to an
- <literal>id</literal> on an <sgmltag>anchor</sgmltag>
- element, since the <sgmltag>link</sgmltag> content defines
- the text that will be used for the link.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Linking to Documents on the WWW</title>
-
- <para>Linking to external documents is much simpler, as long
- as you know the URL of the document you want to link to.
- Use <sgmltag>ulink</sgmltag>. The <literal>url</literal>
- attribute is the URL of the page that the link points to,
- and the content of the element is the text that will be
- displayed for the user to activate.</para>
-
- <example>
- <title><sgmltag>ulink</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<para>Of course, you could stop reading this document and
- go to the <ulink url="&url.base;/index.html">FreeBSD
- home page</ulink> instead.</para>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>Of course, you could stop reading this document and go
- to the <ulink url="&url.base;/index.html">FreeBSD home
- page</ulink> instead.</para>
- </example>
- </sect3>
- </sect2>
- </sect1>
-</chapter>
diff --git a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
new file mode 100644
index 0000000000..43e0f8adbe
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
@@ -0,0 +1,613 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+
+ $FreeBSD$
+-->
+
+<chapter id="xhtml-markup">
+ <title><acronym>XHTML</acronym> Markup</title>
+
+ <sect1 id="xhtml-markup-introduction">
+ <title>Introduction</title>
+
+ <para>This chapter describes usage of the <acronym>XHTML</acronym>
+ markup language used for the &os; web site.</para>
+
+ <para><acronym>XHTML</acronym> is the <acronym>XML</acronym>
+ version of the HyperText Markup Language, the markup language of
+ choice on the World Wide Web. More information can be found at
+ <ulink url="http://www.w3.org/"></ulink>.</para>
+
+ <para><acronym>XHTML</acronym> is used to mark up pages on the
+ &os; web site. It is usually not used to mark up other
+ documentation, since DocBook offers a far richer set of elements
+ from which to choose. Consequently, <acronym>XHTML</acronym>
+ pages will normally only be encountered when writing for the web
+ site.</para>
+
+ <para><acronym>HTML</acronym> has gone through a number of
+ versions. The <acronym>XML</acronym>-compliant version
+ described here is called <acronym>XHTML</acronym>. The latest
+ widespread version is <acronym>XHTML</acronym> 1.0, available in
+ both <emphasis>strict</emphasis> and
+ <emphasis>transitional</emphasis> variants.</para>
+
+ <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
+ available from the Ports&nbsp;Collection in
+ <filename role="package">textproc/xhtml</filename>. They are
+ automatically installed as part of the <filename
+ role="package">textproc/docproj</filename> port.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> an exhaustive list of
+ elements, since that would just repeat the documentation for
+ <acronym>XHTML</acronym>. The aim is to list those elements
+ most commonly used. Please post questions about elements or
+ uses not covered here to the &a.doc;.</para>
+ </note>
+
+ <note>
+ <title>Inline Versus Block</title>
+
+ <para>In the remainder of this document, when describing
+ elements, <emphasis>inline</emphasis> means that the element
+ can occur within a block element, and does not cause a line
+ break. A <emphasis>block</emphasis> element, by comparison,
+ will cause a line break (and other processing) when it is
+ encountered.</para>
+ </note>
+ </sect1>
+
+ <sect1 id="xhtml-markup-fpi">
+ <title>Formal Public Identifier (<acronym>FPI</acronym>)</title>
+
+ <para>There are a number of <acronym>XHTML</acronym>
+ <acronym>FPI</acronym>s, depending upon the version, or
+ <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
+ a document conforms. Most XHTML documents on the FreeBSD web
+ site comply with the transitional version of
+ <acronym>XHTML</acronym> 1.0.</para>
+
+ <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
+ </sect1>
+
+ <sect1 id="xhtml-markup-sectional-elements">
+ <title>Sectional Elements</title>
+
+ <para>An <acronym>XHTML</acronym> document is normally split into
+ 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 <acronym>XHTML</acronym> Document
+ Structure</title>
+
+ <programlisting>&lt;html xmlns="http://www.w3.org/1999/xhtml">
+ &lt;head>
+ &lt;title><replaceable>The Document's Title</replaceable>&lt;/title>
+ &lt;/head>
+
+ &lt;body>
+
+ &hellip;
+
+ &lt;/body>
+&lt;/html></programlisting>
+ </example>
+ </sect1>
+
+ <sect1 id="xhtml-markup-block-elements">
+ <title>Block Elements</title>
+
+ <sect2 id="xhtml-markup-block-elements-headings">
+ <title>Headings</title>
+
+ <para><acronym>XHTML</acronym> has tags to denote headings in
+ the 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>,
+ and Other Header Tags</title>
+
+ <para>Usage:</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 <acronym>XHTML</acronym> 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, preceding it. Leaving gaps in the numbering is to
+ be avoided.</para>
+
+ <example>
+ <title>Bad Ordering of
+ <sgmltag>h<replaceable>n</replaceable></sgmltag>
+ Elements</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<h1>First section</h1>
+
+<!-- Document introduction -->
+
+<h3>Sub-section</h3>
+
+<!-- This is bad, <h2> has been left out -->]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-paragraphs">
+ <title>Paragraphs</title>
+
+ <para><acronym>XHTML</acronym> supports a single paragraph
+ element, <sgmltag>p</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>p</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any
+ other element.</p>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-block-quotations">
+ <title>Block Quotations</title>
+
+ <para>A block quotation is an extended quotation from another
+ document that should not appear within the current
+ paragraph.</para>
+
+ <example>
+ <title><sgmltag>blockquote</sgmltag></title>
+
+ <para>Usage:</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>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-lists">
+ <title>Lists</title>
+
+ <para><acronym>XHTML</acronym> can present the user with three
+ types of lists: ordered, unordered, and definition.</para>
+
+ <para>Typically, each entry in an ordered list will be
+ numbered, while each entry in an unordered list will be
+ preceded by a bullet point. Definition lists are composed of
+ two sections for each entry. The first section is the term
+ being defined, and the second section is the definition of the
+ term.</para>
+
+ <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
+ element, unordered lists by the <sgmltag>ul</sgmltag>
+ element, and definition lists by the <sgmltag>dl</sgmltag>
+ element.</para>
+
+ <para>Ordered and unordered lists contain listitems, indicated
+ by the <sgmltag>li</sgmltag> element. A listitem can
+ contain textual content, or it may be further wrapped in one
+ or more <sgmltag>p</sgmltag> elements.</para>
+
+ <para>Definition lists contain definition terms
+ (<sgmltag>dt</sgmltag>) and definition descriptions
+ (<sgmltag>dd</sgmltag>). A definition term can only contain
+ inline elements. A definition description can contain other
+ block elements.</para>
+
+ <example>
+ <title><sgmltag>ul</sgmltag> and
+ <sgmltag>ol</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>An unordered list. Listitems will probably be
+ preceded by bullets.</p>
+
+<ul>
+ <li>First item</li>
+
+ <li>Second item</li>
+
+ <li>Third item</li>
+</ul>
+
+<p>An ordered list, with list items consisting of multiple
+ paragraphs. Each item (note: not each paragraph) will be
+ numbered.</p>
+
+<ol>
+ <li><p>This is the first item. It only has one paragraph.</p></li>
+
+ <li><p>This is the first paragraph of the second item.</p>
+
+ <p>This is the second paragraph of the second item.</p></li>
+
+ <li><p>This is the first and only paragraph of the third
+ item.</p></li>
+</ol>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Definition Lists with <sgmltag>dl</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<dl>
+ <dt>Term 1</dt>
+
+ <dd><p>Paragraph 1 of definition 1.</p>
+
+ <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><p>Paragraph 1 of definition 3.</p></dd>
+</dl>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-preformatted-text">
+ <title>Pre-formatted Text</title>
+
+ <para>Pre-formatted text can 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 into 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>For example, the <sgmltag>pre</sgmltag> tags could be
+ used to mark up an email message:</para>
+
+ <programlisting><![CDATA[<pre> From: nik@FreeBSD.org
+ To: freebsd-doc@FreeBSD.org
+ Subject: New documentation available
+
+ There is a new copy of my primer for contributors to the FreeBSD
+ Documentation Project available at
+
+ &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;
+
+ Comments appreciated.
+
+ N</pre>]]></programlisting>
+
+ <para>Keep in mind that <literal>&lt;</literal> and
+ <literal>&amp;</literal> still are recognized as special
+ characters in pre-formatted text. This is why the example
+ shown had to use <literal>&amp;lt;</literal> instead of
+ <literal>&lt;</literal>. For consistency,
+ <literal>&amp;gt;</literal> was used in place of
+ <literal>&gt;</literal>, too. Watch out for the special
+ characters that may appear in text copied from a plain-text
+ source, like an email message or program code.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-tables">
+ <title>Tables</title>
+
+ <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 the <sgmltag>p</sgmltag>element is not needed.</para>
+
+ <example>
+ <title>Simple Use of <sgmltag>table</sgmltag></title>
+
+ <para>Usage:</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 or columns that should be spanned.</para>
+
+ <example>
+ <title>Using <literal>rowspan</literal></title>
+
+ <para>Usage:</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>Usage:</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>Usage:</para>
+
+ <programlisting><![CDATA[<p>On a 3x3 grid, the top left block is a 2x2 set of
+ cells merged into 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 into
+ 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>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xhtml-markup-inline-elements">
+ <title>In-line Elements</title>
+
+ <sect2 id="xhtml-markup-inline-elements-emphasizing-information">
+ <title>Emphasizing Information</title>
+
+ <para>Two levels of emphasis are available in
+ <acronym>XHTML</acronym>, <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 should not be relied upon.
+ According to best practices, webpages only hold structural and
+ semantical information and stylesheets are later applied to
+ them. Think of semantics, not formatting, when using these
+ tags.</para>
+
+ <example>
+ <title><sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p><em>This</em> has been emphasized, while
+ <strong>this</strong> has been strongly emphasized.</p>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-inline-elements-fixed-pitch-text">
+ <title>Indicating Fixed-Pitch Text</title>
+
+ <para>Content that should be rendered in a fixed pitch
+ (typewriter) typeface is tagged with <sgmltag>tt</sgmltag>
+ (for <quote>teletype</quote>).</para>
+
+ <example>
+ <title><sgmltag>tt</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>This document was originally written by
+ Nik Clayton, who can be reached by email as
+ <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-inline-elements-links">
+ <title>Links</title>
+
+ <note>
+ <para>Links are also inline elements.</para>
+ </note>
+
+ <sect3 id="xhtml-markup-inline-elements-linking">
+ <title>Linking to Other Documents on the Web</title>
+
+ <para>A link points to the <acronym>URL</acronym> of another
+ document on the web. The link is indicated with
+ <sgmltag>a</sgmltag>, and the <literal>href</literal>
+ attribute contains the <acronym>URL</acronym> of the target
+ document. The content of the element becomes the link, and
+ is normally indicated to the user in some way,
+ typically by a different color or underlining.</para>
+
+ <example>
+ <title>Using <literal>&lt;a href="..."&gt;</literal></title>
+
+ <para>Usage:</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 id="xhtml-markup-inline-elements-other-parts">
+ <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
+ <emphasis>anchors</emphasis>. Anchors are indicated with
+ <sgmltag>a</sgmltag> and the <literal>id</literal> attribute
+ instead of <literal>href</literal>.</para>
+
+ <example>
+ <title>Using <literal>&lt;a id="..."&gt;</literal></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p><a id="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 <acronym>ID</acronym>
+ 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 preceding
+ <literal>#</literal>).</para>
+
+ <example>
+ <title>Linking to a Named Part of the Same Document</title>
+
+ <para>Assume that the <literal>para1</literal> example
+ resides in this document:</para>
+
+ <programlisting><![CDATA[<p>More information can be found in the
+ <a href="#para1">first paragraph</a> of this
+ document.</p>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>