2250 lines
74 KiB
XML
2250 lines
74 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
|
|
|
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
|
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
1. Redistributions of source code (SGML DocBook) must retain the above
|
|
copyright notice, this list of conditions and the following
|
|
disclaimer as the first lines of this file unmodified.
|
|
|
|
2. Redistributions in compiled form (transformed to other DTDs,
|
|
converted to PDF, PostScript, RTF and other formats) must reproduce
|
|
the above copyright notice, this list of conditions and the
|
|
following disclaimer in the documentation and/or other materials
|
|
provided with the distribution.
|
|
|
|
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
|
|
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
|
|
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
|
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
$FreeBSD$
|
|
-->
|
|
|
|
<chapter id="docbook-markup">
|
|
<title>DocBook Markup</title>
|
|
|
|
<sect1 id="docbook-markup-introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>This chapter is an introduction to DocBook as it is used for
|
|
&os; documentation. DocBook is a large and complex markup
|
|
system, but the subset described here covers the parts that are
|
|
most widely used for &os; documentation. While a moderate
|
|
subset is covered, it is impossible to anticipate every
|
|
situation. Please post questions that this document does
|
|
not answer to the &a.doc;.</para>
|
|
|
|
<para>DocBook was originally developed by HaL Computer Systems and
|
|
O'Reilly & 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 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,
|
|
…) 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 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><book>
|
|
<bookinfo>
|
|
<title><replaceable>Your Title Here</replaceable></title>
|
|
|
|
<author>
|
|
<firstname><replaceable>Your first name</replaceable></firstname>
|
|
<surname><replaceable>Your surname</replaceable></surname>
|
|
<affiliation>
|
|
<address><email><replaceable>Your email address</replaceable></email></address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<copyright>
|
|
<year><replaceable>1998</replaceable></year>
|
|
<holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
|
|
</copyright>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
|
|
<abstract>
|
|
<para><replaceable>Include an abstract of the book's contents here.</replaceable></para>
|
|
</abstract>
|
|
</bookinfo>
|
|
|
|
…
|
|
|
|
</book></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><article>
|
|
<articleinfo>
|
|
<title><replaceable>Your title here</replaceable></title>
|
|
|
|
<author>
|
|
<firstname><replaceable>Your first name</replaceable></firstname>
|
|
<surname><replaceable>Your surname</replaceable></surname>
|
|
<affiliation>
|
|
<address><email><replaceable>Your email address</replaceable></email></address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<copyright>
|
|
<year><replaceable>1998</replaceable></year>
|
|
<holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
|
|
</copyright>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
|
|
<abstract>
|
|
<para><replaceable>Include an abstract of the article's contents here.</replaceable></para>
|
|
</abstract>
|
|
</articleinfo>
|
|
|
|
…
|
|
|
|
</article></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>
|
|
|
|
…
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Second Section (1.2)</title>
|
|
|
|
<sect2>
|
|
<title>First Sub-Section (1.2.1)</title>
|
|
|
|
<sect3>
|
|
<title>First Sub-Sub-Section (1.2.1.1)</title>
|
|
|
|
…
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Second Sub-Section (1.2.2)</title>
|
|
|
|
…
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>]]></programlisting>
|
|
</example>
|
|
|
|
<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 <stdio.h>
|
|
|
|
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 <stdio.h>
|
|
|
|
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 <stdio.h> <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 <stdio.h> <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><informaltable frame="none"></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>&prompt.root;</literal> and
|
|
<literal>&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>&prompt.root;</literal> and
|
|
<literal>&prompt.user;</literal> as necessary. They
|
|
do not need to be inside
|
|
<sgmltag>prompt</sgmltag>.</para>
|
|
|
|
<note>
|
|
<para><literal>&prompt.root;</literal> and
|
|
<literal>&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>&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><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
|
|
|
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
|
|
%man;
|
|
|
|
…
|
|
|
|
]></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>&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>&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 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><mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="fig1"> <co id="co-image-ext"/>
|
|
</imageobject>
|
|
|
|
<textobject>
|
|
<literallayout class="monospaced">+---------------+ <co id="co-image-literal"/>
|
|
| A |
|
|
+---------------+</literallayout>
|
|
</textobject>
|
|
|
|
<textobject>
|
|
<phrase>A picture</phrase> <co id="co-image-phrase"/>
|
|
</textobject>
|
|
</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>…
|
|
IMAGES= fig1.eps fig2.png fig3.png
|
|
…</programlisting>
|
|
|
|
<para>or</para>
|
|
|
|
<programlisting>…
|
|
IMAGES= fig1.eps
|
|
IMAGES+= fig2.png
|
|
IMAGES+= fig3.png
|
|
…</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><mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/>
|
|
</imageobject>
|
|
|
|
…
|
|
|
|
</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>…
|
|
IMAGES= chapter1/fig1.png
|
|
…</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="introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>This is the introduction. It contains a subsection,
|
|
which is identified as well.</para>
|
|
|
|
<sect1 id="introduction-moredetails">
|
|
<title>More Details</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 shown above:</para>
|
|
|
|
<programlisting><![CDATA[<para>More information can be found
|
|
in <xref linkend="introduction"/>.</para>
|
|
|
|
<para>More specific information can be found
|
|
in <xref linkend="introduction-moredetails"/>.</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, Introduction</emphasis>.</para>
|
|
|
|
<para>More specific information can be found in
|
|
<emphasis>Section 1.1,
|
|
<quote>More Details</quote></emphasis>.</para>
|
|
</blockquote>
|
|
</example>
|
|
|
|
<para>The link text is generated automatically from the chapter
|
|
and section number and <literal>title</literal>
|
|
elements.</para>
|
|
|
|
<note>
|
|
<para><sgmltag>xref</sgmltag> cannot link to an
|
|
<literal>id</literal> attribute on an
|
|
<sgmltag>anchor</sgmltag> element. The
|
|
<sgmltag>anchor</sgmltag> has no content, so the
|
|
<sgmltag>xref</sgmltag> cannot generate the link
|
|
text.</para>
|
|
</note>
|
|
</sect2>
|
|
|
|
<sect2 id="docbook-markup-links-to-same-or-web-documents">
|
|
<title>Linking to the Same Document or Other Documents on the
|
|
Web</title>
|
|
|
|
<para>The link elements described here allow the writer to
|
|
define the link text. It is very important to use descriptive
|
|
link text to give the reader an idea of where the link will
|
|
take them. Remember that DocBook can be rendered to multiple
|
|
types of media. The reader may be looking at a printed book
|
|
or other form of media where there are no links. If the link
|
|
text is not descriptive enough, the reader may not be able to
|
|
locate the linked section.</para>
|
|
|
|
<sect3 id="docbook-markup-links-to-same-document">
|
|
<title>Links to the Same Document</title>
|
|
|
|
<para><sgmltag>link</sgmltag> is used to create a link
|
|
within the same document. The target <literal>id</literal>
|
|
is specified in the <literal>linkend</literal> attribute.
|
|
This element wraps content, which is used for the link
|
|
text.</para>
|
|
|
|
<example>
|
|
<title>Using <sgmltag>link</sgmltag></title>
|
|
|
|
<para>Assume that this fragment appears somewhere in a
|
|
document that includes the <literal>id</literal>
|
|
example.</para>
|
|
|
|
<programlisting><![CDATA[<para>More information can be found in the
|
|
<link linkend="introduction">sample introduction</link>.</para>
|
|
|
|
<para>More specific information can be found in the
|
|
<link linkend="introduction-moredetails">sample introduction with more details</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 introduction</emphasis>.</para>
|
|
|
|
<para>More specific information can be found in the
|
|
<emphasis>sample introduction with more details</emphasis> section.</para>
|
|
</blockquote>
|
|
</example>
|
|
|
|
<note>
|
|
<para><sgmltag>link</sgmltag> can be used to include links
|
|
to the <literal>id</literal> of an
|
|
<sgmltag>anchor</sgmltag> element, since the
|
|
<sgmltag>link</sgmltag> content defines the link
|
|
text.</para>
|
|
</note>
|
|
</sect3>
|
|
|
|
<sect3 id="docbook-markup-links-to-web-documents">
|
|
<title>Linking to Other Documents on the Web</title>
|
|
|
|
<para>The <sgmltag>ulink</sgmltag> is used to link to
|
|
external documents on the web. The <literal>url</literal>
|
|
attribute is the <acronym>URL</acronym> of the page that the
|
|
link points to, and the content of the element is the text
|
|
that will be displayed for the user to activate.</para>
|
|
|
|
<example>
|
|
<title><sgmltag>ulink</sgmltag> to a &os; Documentation Web
|
|
Page</title>
|
|
|
|
<para>Link to the book or article <acronym>URL</acronym>
|
|
entity. To link to a specific chapter in a book, add a
|
|
slash and the chapter file name, followed by an optional
|
|
anchor within the chapter. For articles, link to the
|
|
article <acronym>URL</acronym> entity, followed by an
|
|
optional anchor within the article.
|
|
<acronym>URL</acronym> entities can be found in
|
|
<filename>doc/share/xml/urls.ent</filename>.</para>
|
|
|
|
<para>Usage for book links:</para>
|
|
|
|
<programlisting><![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>Appearance:</para>
|
|
|
|
<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>
|