aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml2248
1 files changed, 2248 insertions, 0 deletions
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>