<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter id="sgml-markup">
<title>SGML Markup</title>
<para>This chapter describes the two markup languages you will encounter
when you contribute to the FreeBSD documentation project. Each section
describes the markup language, and details the markup that you are likely
to want to use, or that is already in use.</para>
<para>These markup languages contain a large number of elements, and it can
be confusing sometimes to know which element to use for a particular
situation. This section goes through the elements you are most likely to
need, and gives examples of how you would use them.</para>
<para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
that would just reiterate the documentation for each language. The aim of
this section is to list those elements more likely to be useful to you.
If you have a question about how best to markup a particular piece of
content, please post it to the &a.doc;.</para>
<note>
<title>Inline vs. block</title>
<para>In the remainder of this document, when describing elements,
<emphasis>inline</emphasis> means that the element can occur within a
block element, and does not cause a line break. A
<emphasis>block</emphasis> element, by comparison, will cause a line
break (and other processing) when it is encountered.</para>
</note>
<sect1 id="sgml-markup-html">
<title>HTML</title>
<para>HTML, the HyperText Markup Language, is the markup language of
choice on the World Wide Web. More information can be found at
<URL:<ulink url="http://www.w3.org/"></ulink>>.</para>
<para>HTML is used to markup pages on the FreeBSD web site. It should not
(generally) be used to mark up other documentation,
since DocBook offers a
far richer set of elements to choose from. Consequently, you will
normally only encounter HTML pages if you are writing for the web
site.</para>
<para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
latest, 4.0 (available in both <emphasis>strict</emphasis> and
<emphasis>loose</emphasis> variants).</para>
<para>The HTML DTDs are available from the ports collection in the
<filename role="package">textproc/html</filename> port. They are automatically
installed as part of the <filename role="package">textproc/docproj</filename>
port.</para>
<sect2>
<title>Formal Public Identifier (FPI)</title>
<para>There are a number of HTML FPIs, depending upon the version (also
known as the level) of HTML that you want to declare your document to
be compliant with.</para>
<para>The majority of HTML documents on the FreeBSD web site comply with
the loose version of HTML 4.0.</para>
<programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</sect2>
<sect2>
<title>Sectional elements</title>
<para>An HTML document is normally split into two sections. The first
section, called the <emphasis>head</emphasis>, contains
meta-information about the document, such as its title, the name of
the author, the parent document, and so on. The second section, the
<emphasis>body</emphasis>, contains the content that will be displayed
to the user.</para>
<para>These sections are indicated with <sgmltag>head</sgmltag> and
<sgmltag>body</sgmltag> elements respectively. These elements are
contained within the top-level <sgmltag>html</sgmltag> element.</para>
<example>
<title>Normal HTML document structure</title>
<programlisting><html>
<head>
<title><replaceable>The document's title</replaceable></title>
</head>
<body>
…
</body>
</html></programlisting>
</example>
</sect2>
<sect2>
<title>Block elements</title>
<sect3>
<title>Headings</title>
<para>HTML allows you to denote headings in your document, at up to
six different levels.</para>
<para>The largest and most prominent heading is <sgmltag>h1</sgmltag>,
then <sgmltag>h2</sgmltag>, continuing down to
<sgmltag>h6</sgmltag>.</para>
<para>The element's content is the text of the heading.</para>
<example>
<title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title>
<para>Use:</para>
<programlisting><![ CDATA [<h1>First section</h1>
<!-- Document introduction goes here -->
<h2>This is the heading for the first section</h2>
<!-- Content for the first section goes here -->
<h3>This is the heading for the first sub-section</h3>
<!-- Content for the first sub-section goes here -->
<h2>This is the heading for the second section</h2>
<!-- Content for the second section goes here -->]]></programlisting>
</example>
<para>Generally, an HTML page should have one first level heading
(<sgmltag>h1</sgmltag>). This can contain many second level
headings (<sgmltag>h2</sgmltag>), which can in turn contain many
third level headings. Each
<sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
the same element, but one further up the hierarchy, preceding it.
Leaving gaps in the numbering is to be avoided.</para>
<example>
<title>Bad ordering of
<sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title>
<para>Use:</para>
<programlisting><![ CDATA [<h1>First section</h1>
<!-- Document introduction -->
<h3>Sub-section</h3>
<!-- This is bad, <h2> has been left out -->]]></programlisting>
</example>
</sect3>
<sect3>
<title>Paragraphs</title>
<para>HTML supports a single paragraph element,
<sgmltag>p</sgmltag>.</para>
<example>
<title><sgmltag>p</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>This is a paragraph. It can contain just about any
other element.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Block quotations</title>
<para>A block quotation is an extended quotation from another document
that should not appear within the current paragraph.</para>
<example>
<title><sgmltag>blockquote</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>A small excerpt from the US Constitution:</p>
<blockquote>We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic
Tranquility, provide for the common defence, promote the general
Welfare, and secure the Blessings of Liberty to ourselves and our
Posterity, do ordain and establish this Constitution for the
United States of America.</blockquote>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Lists</title>
<para>You can present the user with three types of lists, ordered,
unordered, and definition.</para>
<para>Typically, each entry in an ordered list will be numbered, while
each entry in an unordered list will be preceded by a bullet point.
Definition lists are composed of two sections for each entry. The
first section is the term being defined, and the second section is
the definition of the term.</para>
<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
element, unordered lists by the <sgmltag>ul</sgmltag> element, and
definition lists by the <sgmltag>dl</sgmltag> element.</para>
<para>Ordered and unordered lists contain listitems, indicated by the
<sgmltag>li</sgmltag> element. A listitem can contain textual
content, or it may be further wrapped in one or more
<sgmltag>p</sgmltag> elements.</para>
<para>Definition lists contain definition terms
(<sgmltag>dt</sgmltag>) and definition descriptions
(<sgmltag>dd</sgmltag>). A definition term can only contain inline
elements. A definition description can contain other block
elements.</para>
<example>
<title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>An unordered list. Listitems will probably be
preceded by bullets.</p>
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>
<p>An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be
numbered.</p>
<ol>
<li><p>This is the first item. It only has one paragraph.</p></li>
<li><p>This is the first paragraph of the second item.</p>
<p>This is the second paragraph of the second item.</p></li>
<li><p>This is the first and only paragraph of the third
item.</p></li>
</ol>]]></programlisting>
</example>
<example>
<title>Definition lists with <sgmltag>dl</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<dl>
<dt>Term 1</dt>
<dd><p>Paragraph 1 of definition 1.</p>
<p>Paragraph 2 of definition 1.</p></dd>
<dt>Term 2</dt>
<dd><p>Paragraph 1 of definition 2.</p></dd>
<dt>Term 3</dt>
<dd>Paragraph 1 of definition 3. Note that the <p>
element is not required in the single paragraph case.</dd>
</dl>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Pre-formatted text</title>
<para>You can indicate that text should be shown to the user exactly
as it is in the file. Typically, this means that the text is shown
in a fixed font, multiple spaces are not merged into one, and line
breaks in the text are significant.</para>
<para>In order to do this, wrap the content in the
<sgmltag>pre</sgmltag> element.</para>
<example>
<title><sgmltag>pre</sgmltag></title>
<para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
message;</para>
<programlisting><![ CDATA [<pre> From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
Subject: New documentation available
There is a new copy of my primer for contributors to the FreeBSD
Documentation Project available at
<URL:http://people.FreeBSD.org/~nik/primer/index.html>
Comments appreciated.
N</pre>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Tables</title>
<note>
<para>Most text-mode browsers (such as Lynx) do not render tables
particularly effectively. If you are relying on the tabular
display of your content, you should consider using alternative
markup to prevent confusion.</para>
</note>
<para>Mark up tabular information using the <sgmltag>table</sgmltag>
element. A table consists of one or more table rows
(<sgmltag>tr</sgmltag>), each containing one or more cells of table
data (<sgmltag>td</sgmltag>). Each cell can contain other block
elements, such as paragraphs or lists. It can also contain another
table (this nesting can repeat indefinitely). If the cell only
contains one paragraph then you do not need to include the
<sgmltag>p</sgmltag> element.</para>
<example>
<title>Simple use of <sgmltag>table</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>This is a simple 2x2 table.</p>
<table>
<tr>
<td>Top left cell</td>
<td>Top right cell</td>
</tr>
<tr>
<td>Bottom left cell</td>
<td>Bottom right cell</td>
</tr>
</table>]]></programlisting></example>
<para>A cell can span multiple rows and columns. To indicate this,
add the <literal>rowspan</literal> and/or <literal>colspan</literal>
attributes, with values indicating the number of rows of columns
that should be spanned.</para>
<example>
<title>Using <literal>rowspan</literal></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to
it on the right.</p>
<table>
<tr>
<td rowspan="2">Long and thin</td>
</tr>
<tr>
<td>Top cell</td>
<td>Bottom cell</td>
</tr>
</table>]]></programlisting>
</example>
<example>
<title>Using <literal>colspan</literal></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p>
<table>
<tr>
<td colspan="2">Top cell</td>
</tr>
<tr>
<td>Bottom left cell</td>
<td>Bottom right cell</td>
</tr>
</table>]]></programlisting>
</example>
<example>
<title>Using <literal>rowspan</literal> and
<literal>colspan</literal> together</title>
<para>Use:</para>
<programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
cells merged into one. The other cells are normal.</p>
<table>
<tr>
<td colspan="2" rowspan="2">Top left large cell</td>
<td>Top right cell</td>
</tr>
<tr>
<!-- Because the large cell on the left merges into
this row, the first <td> will occur on its
right -->
<td>Middle right cell</td>
</tr>
<tr>
<td>Bottom left cell</td>
<td>Bottom middle cell</td>
<td>Bottom right cell</td>
</tr>
</table>]]></programlisting>
</example>
</sect3>
</sect2>
<sect2>
<title>In-line elements</title>
<sect3>
<title>Emphasising information</title>
<para>You have two levels of emphasis available in HTML,
<sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
<sgmltag>em</sgmltag> is for a normal level of emphasis and
<sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
<para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
<sgmltag>strong</sgmltag> is rendered in bold. This is not always
the case, however, and you should not rely on it.</para>
<example>
<title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<p><em>This</em> has been emphasised, while
<strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Bold and italics</title>
<para>Because HTML includes presentational markup, you can also
indicate that particular content should be rendered in bold or
italic. The elements are <sgmltag>b</sgmltag> and
<sgmltag>i</sgmltag> respectively.</para>
<example>
<title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
<programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
in italics.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Indicating fixed pitch text</title>
<para>If you have content that should be rendered in a fixed pitch
(typewriter) typeface, use <sgmltag>tt</sgmltag> (for
<quote>teletype</quote>).</para>
<example>
<title><sgmltag>tt</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>This document was originally written by
Nik Clayton, who can be reached by e-mail as
<tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Content size</title>
<para>You can indicate that content should be shown in a larger or
smaller font. There are three ways of doing this.</para>
<orderedlist>
<listitem>
<para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag>
around the content you wish to change size. These tags can be
nested, so <literal><big><big>This is much
bigger</big></big></literal> is possible.</para>
</listitem>
<listitem>
<para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
attribute set to <literal>+1</literal> or <literal>-1</literal>
respectively. This has the same effect as using
<sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However,
the use of this approach is deprecated.</para>
</listitem>
<listitem>
<para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
attribute set to a number between 1 and 7. The default font size
is <literal>3</literal>. This approach is deprecated.</para>
</listitem>
</orderedlist>
<example>
<title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
<sgmltag>font</sgmltag></title>
<para>The following fragments all do the same thing.</para>
<programlisting><![ CDATA [<p>This text is <small>slightly smaller</small>. But
this text is <big>slightly bigger</big>.</p>
<p>This text is <font size="-1">slightly smaller</font>. But
this text is <font size="+1">slightly bigger</font.</p>
<p>This text is <font size="2">slightly smaller</font>. But
this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
</example>
</sect3>
</sect2>
<sect2>
<title>Links</title>
<note>
<para>Links are also in-line elements.</para>
</note>
<sect3>
<title>Linking to other documents on the WWW</title>
<para>In order to include a link to another document on the WWW you
must know the URL of the document you want to link to.</para>
<para>The link is indicated with <sgmltag>a</sgmltag>, and the
<literal>href</literal> attribute contains the URL of the target
document. The content of the element becomes the link, and is
normally indicated to the user in some way (underlining, change of
color, different mouse cursor when over the link, and so
on).</para>
<example>
<title>Using <literal><a href="..."></literal></title>
<para>Use:</para>
<programlisting><![ CDATA [<p>More information is available at the
<a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
</example>
<para>These links will take the user to the top of the chosen
document.</para>
</sect3>
<sect3>
<title>Linking to other parts of documents</title>
<para>Linking to a point within another document (or within the same
document) requires that the document author include anchors that you
can link to.</para>
<para>Anchors are indicated with <sgmltag>a</sgmltag> and the
<literal>name</literal> attribute instead of
<literal>href</literal>.</para>
<example>
<title>Using <literal><a name="..."></literal></title>
<para>Use:</para>
<programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
in other links with the name <tt>para1</tt>.</p>]]></programlisting>
</example>
<para>To link to a named part of a document, write a normal link to
that document, but include the name of the anchor after a
<literal>#</literal> symbol.</para>
<example>
<title>Linking to a named part of another document</title>
<para>Assume that the <literal>para1</literal> example resides in a
document called <filename>foo.html</filename>.</para>
<programlisting><![ CDATA [<p>More information can be found in the
<a href="foo.html#para1">first paragraph</a> of
<tt>foo.html</tt>.</p>]]></programlisting>
</example>
<para>If you are linking to a named anchor within the same document
then you can omit the document's URL, and just include the name of
the anchor (with the preceding <literal>#</literal>).</para>
<example>
<title>Linking to a named part of the same document</title>
<para>Assume that the <literal>para1</literal> example resides in
this document</para>
<programlisting><![ CDATA [<p>More information can be found in the
<a href="#para1">first paragraph</a> of this
document.</p>]]></programlisting>
</example>
</sect3>
</sect2>
</sect1>
<sect1 id="sgml-markup-docbook">
<title>DocBook</title>
<para>DocBook was originally developed by HaL Computer Systems and O'Reilly
& Associates to be a DTD for writing technical documentation
<footnote><para>A short history can be found under <ulink
url="http://www.oasis-open.org/committees/docbook/intro.shtml">
http://www.oasis-open.org/committees/docbook/intro.shtml</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 HTML, DocBook is very heavily oriented towards markup that
describes <emphasis>what</emphasis> something is, rather than describing
<emphasis>how</emphasis> it should be presented.</para>
<note>
<title><literal>formal</literal> vs. <literal>informal</literal></title>
<para>Some elements may exist in two forms, <emphasis>formal</emphasis>
and <emphasis>informal</emphasis>. Typically, the formal version of
the element will consist of a title followed by the informal
version of the element. The informal version will not have a
title.</para>
</note>
<para>The DocBook DTD is available from the ports collection in the
<filename role="package">textproc/docbook</filename> port. It is automatically
installed as part of the <filename role="package">textproc/docproj</filename>
port.</para>
<sect2>
<title>FreeBSD extensions</title>
<para>The FreeBSD Documentation Project has extended the DocBook DTD by
adding some new elements. These elements serve to make some of the
markup more precise.</para>
<para>Where a FreeBSD specific element is listed below it is clearly
marked.</para>
<para>Throughout the rest of this document, the term
<quote>DocBook</quote> is used to mean the FreeBSD extended DocBook
DTD.</para>
<note>
<para>There is nothing about these extensions that is FreeBSD
specific, it was just felt that they were useful enhancements for
this particular project. Should anyone from any of the other *nix
camps (NetBSD, OpenBSD, Linux, …) be interested in
collaborating on a standard DocBook extension set, please get in
touch with &a.nik;.</para>
</note>
<para>The FreeBSD extensions are not (currently) in the ports
collection. They are stored in the FreeBSD CVS tree, as <ulink
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
</sect2>
<sect2>
<title>Formal Public Identifier (FPI)</title>
<para>In compliance with the DocBook guidelines for writing FPIs for
DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
is;</para>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
</sect2>
<sect2>
<title>Document structure</title>
<para>DocBook allows you to structure your documentation in several
ways. In the FreeBSD Documentation Project we are using two primary
types of DocBook document: the book and the article.</para>
<para>A book is 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 organisation.
The Handbook is arranged in this way.</para>
<para>A chapter may (or may not) contain one or more sections. These
are indicated with the <sgmltag>sect1</sgmltag> element. If a section
contains another section then use the <sgmltag>sect2</sgmltag>
element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
<para>Chapters and sections contain the remainder of the content.</para>
<para>An article is simpler than a book, and does not use chapters.
Instead, the content of an article is organized into one or more
sections, using the same <sgmltag>sect1</sgmltag> (and
<sgmltag>sect2</sgmltag> and so on) elements that are used in
books.</para>
<para>Obviously, you should consider the nature of the documentation you
are writing in order to decide whether it is best marked up as a book
or an article. Articles are well suited to information that does not
need to be broken down into several chapters, and that is, relatively
speaking, quite short, at up to 20-25 pages of content. Books are
best suited to information that can be broken up into several
chapters, possibly with appendices and similar content as well.</para>
<para>The <ulink url="../../../../docs.html">FreeBSD
tutorials</ulink> are all marked up as articles, while this
document, the <ulink url="../faq/index.html">FreeBSD
FAQ</ulink>, and the <ulink
url="../handbook/index.html">FreeBSD Handbook</ulink> are
all marked up as books.</para>
<sect3>
<title>Starting a book</title>
<para>The content of the book is contained within the
<sgmltag>book</sgmltag> element. As well as containing structural
markup, this element can contain elements that include additional
information about the book. This is either meta-information, used
for reference purposes, or additional content used to produce a
title page.</para>
<para>This additional information should be contained within
<sgmltag>bookinfo</sgmltag>.</para>
<example>
<title>Boilerplate <sgmltag>book</sgmltag> with
<sgmltag>bookinfo</sgmltag></title>
<!-- Can't put this in a marked section because of the
replaceable elements -->
<programlisting><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 e-mail address</replaceable></email></address>
</affiliation>
</author>
<copyright>
<year><replaceable>1998</replaceable></year>
<holder role="mailto:<replaceable>your e-mail 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>
</sect3>
<sect3>
<title>Starting an article</title>
<para>The content of the article is contained within the
<sgmltag>article</sgmltag> element. As well as containing
structural markup, this element can contain elements that include
additional information about the article. This is either
meta-information, used for reference purposes, or additional content
used to produce a title page.</para>
<para>This additional information should be contained within
<sgmltag>articleinfo</sgmltag>.</para>
<example>
<title>Boilerplate <sgmltag>article</sgmltag> with
<sgmltag>articleinfo</sgmltag></title>
<!-- Can't put this in a marked section because of the
replaceable elements -->
<programlisting><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 e-mail address</replaceable></email></address>
</affiliation>
</author>
<copyright>
<year><replaceable>1998</replaceable></year>
<holder role="mailto:<replaceable>your e-mail 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>
</sect3>
<sect3>
<title>Indicating chapters</title>
<para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each
chapter has a mandatory <sgmltag>title</sgmltag>. Articles do not
contain chapters, they are reserved for books.</para>
<example>
<title>A simple chapter</title>
<programlisting><![ CDATA [<chapter>
<title>The chapter's title</title>
...
</chapter>]]></programlisting>
</example>
<para>A chapter cannot be empty; it must contain elements in addition
to <sgmltag>title</sgmltag>. If you need to include an empty
chapter then just use an empty paragraph.</para>
<example>
<title>Empty chapters</title>
<programlisting><![ CDATA [<chapter>
<title>This is an empty chapter</title>
<para></para>
</chapter>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Sections below chapters</title>
<para>In books, chapters may (but do not need to) be broken up into
sections, subsections, and so on. In articles, sections are the
main structural element, and each article must contain at least one
section. Use the
<sgmltag>sect<replaceable>n</replaceable></sgmltag> element. The
<replaceable>n</replaceable> indicates the section number, which
identifies the section level.</para>
<para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is
<sgmltag>sect1</sgmltag>. You can have one or more of these in a
chapter. They can contain one or more <sgmltag>sect2</sgmltag>
elements, and so on, down to <sgmltag>sect5</sgmltag>.</para>
<example>
<title>Sections in chapters</title>
<programlisting><![ RCDATA [<chapter>
<title>A sample chapter</title>
<para>Some text in the chapter.</para>
<sect1>
<title>First section (1.1)</title>
…
</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>
</sect3>
<sect3>
<title>Subdividing using <sgmltag>part</sgmltag>s</title>
<para>You can introduce another layer of organisation between
<sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
more <sgmltag>part</sgmltag>s. This cannot be done in an
<sgmltag>article</sgmltag>.</para>
<programlisting><![ CDATA [<part>
<title>Introduction</title>
<chapter>
<title>Overview</title>
...
</chapter>
<chapter>
<title>What is FreeBSD?</title>
...
</chapter>
<chapter>
<title>History</title>
...
</chapter>
</part>]]></programlisting>
</sect3>
</sect2>
<sect2>
<title>Block elements</title>
<sect3>
<title>Paragraphs</title>
<para>DocBook supports three types of paragraphs:
<sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
<sgmltag>simpara</sgmltag>.</para>
<para>Most of the time you will only need to use
<sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a
<sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag>
disallows some elements from within <sgmltag>para</sgmltag>. Stick
with <sgmltag>para</sgmltag>.</para>
<example>
<title><sgmltag>para</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>This is a paragraph. It can contain just about any
other element.</para> ]]></programlisting>
<para>Appearance:</para>
<para>This is a paragraph. It can contain just about any other
element.</para>
</example>
</sect3>
<sect3>
<title>Block quotations</title>
<para>A block quotation is an extended quotation from another document
that should not appear within the current paragraph. You will
probably only need it infrequently.</para>
<para>Blockquotes can optionally contain a title and an attribution
(or they can be left untitled and unattributed).</para>
<example>
<title><sgmltag>blockquote</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para>
<blockquote>
<title>Preamble to the Constitution of the United States</title>
<attribution>Copied from a web site somewhere</attribution>
<para>We the People of the United States, in Order to form a more perfect
Union, establish Justice, insure domestic Tranquility, provide for the
common defence, promote the general Welfare, and secure the Blessings
of Liberty to ourselves and our Posterity, do ordain and establish this
Constitution for the United States of America.</para>
</blockquote>]]></programlisting>
<para>Appearance:</para>
<blockquote>
<title>Preamble to the Constitution of the United States</title>
<attribution>Copied from a web site somewhere</attribution>
<para>We the People of the United States, in Order to form a more
perfect Union, establish Justice, insure domestic Tranquility,
provide for the common defence, promote the general Welfare, and
secure the Blessings of Liberty to ourselves and our Posterity,
do ordain and establish this Constitution for the United States
of America.</para>
</blockquote>
</example>
</sect3>
<sect3>
<title>Tips, notes, warnings, cautions, important information and
sidebars.</title>
<para>You may need to include extra information separate from the
main body of the text. Typically this is <quote>meta</quote>
information that the user should be aware of.</para>
<para>Depending on the nature of the information, one of
<sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
<sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
<sgmltag>important</sgmltag> should be used. Alternatively, if the
information is related to the main text but is not one of the above,
use <sgmltag>sidebar</sgmltag>.</para>
<para>The circumstances in which to choose one of these elements over
another is unclear. The DocBook documentation suggests;</para>
<itemizedlist>
<listitem>
<para>A Note is for information that should be heeded by all
readers.</para>
</listitem>
<listitem>
<para>An Important element is a variation on Note.</para>
</listitem>
<listitem>
<para>A Caution is for information regarding possible data loss
or software damage.</para>
</listitem>
<listitem>
<para>A Warning is for information regarding possible hardware
damage or injury to life or limb.</para>
</listitem>
</itemizedlist>
<example>
<title><sgmltag>warning</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<warning>
<para>Installing FreeBSD may make you want to delete Windows from your
hard disk.</para>
</warning>]]></programlisting>
</example>
<!-- Need to do this outside of the example -->
<warning>
<para>Installing FreeBSD may make you want to delete Windows from
your hard disk.</para>
</warning>
</sect3>
<sect3>
<title>Lists and procedures</title>
<para>You will often need to list pieces of information to the user,
or present them with a number of steps that must be carried out in
order to accomplish a particular goal.</para>
<para>In order to do this, use <sgmltag>itemizedlist</sgmltag>,
<sgmltag>orderedlist</sgmltag>, or
<sgmltag>procedure</sgmltag><footnote><para>There are other types of
list element in DocBook, but we are not concerned with those at
the moment.</para>
</footnote>
</para>
<para><sgmltag>itemizedlist</sgmltag> and
<sgmltag>orderedlist</sgmltag> are similar to their counterparts in
HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one
consists of one or more <sgmltag>listitem</sgmltag> elements, and
each <sgmltag>listitem</sgmltag> contains one or more block
elements. The <sgmltag>listitem</sgmltag> elements are analogous to
HTML's <sgmltag>li</sgmltag> tags. However, unlike HTML, they are
required.</para>
<para><sgmltag>procedure</sgmltag> is slightly different. It consists
of <sgmltag>step</sgmltag>s, which may in turn consists of more
<sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each
<sgmltag>step</sgmltag> contains block elements.</para>
<example>
<title><sgmltag>itemizedlist</sgmltag>,
<sgmltag>orderedlist</sgmltag>, and
<sgmltag>procedure</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<itemizedlist>
<listitem>
<para>This is the first itemized item.</para>
</listitem>
<listitem>
<para>This is the second itemized item.</para>
</listitem>
</itemizedlist>
<orderedlist>
<listitem>
<para>This is the first ordered item.</para>
</listitem>
<listitem>
<para>This is the second ordered item.</para>
</listitem>
</orderedlist>
<procedure>
<step>
<para>Do this.</para>
</step>
<step>
<para>Then do this.</para>
</step>
<step>
<para>And now do this.</para>
</step>
</procedure>]]></programlisting>
<para>Appearance:</para>
<itemizedlist>
<listitem>
<para>This is the first itemized item.</para>
</listitem>
<listitem>
<para>This is the second itemized item.</para>
</listitem>
</itemizedlist>
<orderedlist>
<listitem>
<para>This is the first ordered item.</para>
</listitem>
<listitem>
<para>This is the second ordered item.</para>
</listitem>
</orderedlist>
</example>
<!-- Can't have <procedure> inside <example>, so this is a cheat -->
<procedure>
<step>
<para>Do this.</para>
</step>
<step>
<para>Then do this.</para>
</step>
<step>
<para>And now do this.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Showing file samples</title>
<para>If you want to show a fragment of a file (or perhaps a complete
file) to the user, wrap it in the <sgmltag>programlisting</sgmltag>
element.</para>
<para>White space and line breaks within
<sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
significant. In particular, this means that the opening tag should
appear on the same line as the first line of the output, and the
closing tag should appear on the same line as the last line of the
output, otherwise spurious blank lines may be included.</para>
<example>
<title><sgmltag>programlisting</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA[<para>When you have finished, your program should look like
this;</para>
<programlisting>#include <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 you have finished, your program should look like
this;</para>
<programlisting>#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}</programlisting>
</example>
</sect3>
<sect3>
<title>Callouts</title>
<para>A callout is a mechanism for referring back to an earlier piece
of text or specific position within an earlier example without
linking to it within the text.</para>
<para>To do this, mark areas of interest in your example
(<sgmltag>programlisting</sgmltag>,
<sgmltag>literallayout</sgmltag>, or whatever) with the
<sgmltag>co</sgmltag> element. Each element must have a unique
<literal>id</literal> assigned to it. After the example include a
<sgmltag>calloutlist</sgmltag> that refers back to the example and
provides additional commentary.</para>
<example>
<title><sgmltag>co</sgmltag> and
<sgmltag>calloutlist</sgmltag></title>
<programlisting><![ CDATA[<para>When you have finished, your program should look like
this;</para>
<programlisting>#include <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 you have finished, your program should 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>
</sect3>
<sect3>
<title>Tables</title>
<para>Unlike HTML, you do not need to use tables for layout purposes,
as the stylesheet handles those issues for you. Instead, just use
tables for marking up tabular data.</para>
<para>In general terms (and see the DocBook documentation for more
detail) a table (which can be either formal or informal) consists of
a <sgmltag>table</sgmltag> element. This contains at least one
<sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
the number of columns in this table group. Within the tablegroup
you can then have one <sgmltag>thead</sgmltag> element, which
contains elements for the table headings (column headings), and one
<sgmltag>tbody</sgmltag> which contains the body of the
table.</para>
<para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag>
contain <sgmltag>row</sgmltag> elements, which in turn contain
<sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag>
element specifies one cell in the table.</para>
<example>
<title><sgmltag>informaltable</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>This is column head 1</entry>
<entry>This is column head 2</entry>
</row>
</thead>
<tbody>
<row>
<entry>Row 1, column 1</entry>
<entry>Row 1, column 2</entry>
</row>
<row>
<entry>Row 2, column 1</entry>
<entry>Row 2, column 2</entry>
</row>
</tbody>
</tgroup>
</informaltable>]]></programlisting>
<para>Appearance:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>This is column head 1</entry>
<entry>This is column head 2</entry>
</row>
</thead>
<tbody>
<row>
<entry>Row 1, column 1</entry>
<entry>Row 1, column 2</entry>
</row>
<row>
<entry>Row 2, column 1</entry>
<entry>Row 2, column 2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</example>
<para>If you do not want a border around the table the
<literal>frame</literal> attribute can be added to the
<sgmltag>informaltable</sgmltag> element with a value of
<literal>none</literal> (i.e., <literal><informaltable
frame="none"></literal>).</para>
<example>
<title>Tables where <literal>frame="none"</literal></title>
<para>Appearance:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>This is column head 1</entry>
<entry>This is column head 2</entry>
</row>
</thead>
<tbody>
<row>
<entry>Row 1, column 1</entry>
<entry>Row 1, column 2</entry>
</row>
<row>
<entry>Row 2, column 1</entry>
<entry>Row 2, column 2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</example>
</sect3>
<sect3>
<title>Examples for the user to follow</title>
<para>A lot of the time you need to show examples for the user to
follow. Typically, these will consist of dialogs with the computer;
the user types in a command, the user gets a response back, they
type in another command, and so on.</para>
<para>A number of distinct elements and entities come 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. Every
time you want 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 FreeBSD
extensions to DocBook, and are not part of the original
DTD.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>userinput</sgmltag></term>
<listitem>
<para>When displaying text that the user should type in, wrap it
in <sgmltag>userinput</sgmltag> tags. It will probably be
displayed differently to the user.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
<sgmltag>userinput</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>]]></programlisting>
<para>Appearance:</para>
<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>
</example>
<note>
<para>Even though we are displaying the contents of the file
<filename>foo2</filename>, it is <emphasis>not</emphasis> marked
up as <sgmltag>programlisting</sgmltag>. Reserve
<sgmltag>programlisting</sgmltag> for showing fragments of files
outside the context of user actions.</para>
</note>
</sect3>
</sect2>
<sect2>
<title>In-line elements</title>
<sect3>
<title>Emphasising information</title>
<para>When you want to emphasise a particular word or phrase, use
<sgmltag>emphasis</sgmltag>. This may be presented as italic, or
bold, or might be spoken differently with a text-to-speech
system.</para>
<para>There is no way to change the presentation of the emphasis
within your document, no equivalent of HTML's <sgmltag>b</sgmltag>
and <sgmltag>i</sgmltag>. If the information you are presenting is
important then consider presenting it in
<sgmltag>important</sgmltag> rather than
<sgmltag>emphasis</sgmltag>.</para>
<example>
<title><sgmltag>emphasis</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
<para>Appearance:</para>
<para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix
like operating system for the Intel architecture.</para>
</example>
</sect3>
<sect3>
<title>Quotations</title>
<para>To quote text from another document or source, or to denote
a phrase that is used figuratively, use <sgmltag>quote</sgmltag>.
Within a <sgmltag>quote</sgmltag> tag, you may use most of the
markup tags available for normal text.</para>
<example>
<title>Quotations</title>
<para>Use:</para>
<programlisting><![ CDATA [<para>However, make sure that the search does not go beyond the
<quote>boundary between local and public administration</quote>,
as RFC 1535 calls it.</para>]]></programlisting>
<para>Appearance:</para>
<para>However, make sure that the search does not go beyond the
<quote>boundary between local and public administration</quote>,
as RFC 1535 calls it.</para>
</example>
</sect3>
<sect3>
<title>Keys, mouse buttons, and combinations</title>
<para>To refer to a specific key on the keyboard, use
<sgmltag>keycap</sgmltag>. To refer to a mouse button, use
<sgmltag>mousebutton</sgmltag>. And to refer to combinations of key
presses or mouse clicks, wrap them all in
<sgmltag>keycombo</sgmltag>.</para>
<para><sgmltag>keycombo</sgmltag> has an attribute called
<literal>action</literal>, which may be one of
<literal>click</literal>, <literal>double-click</literal>,
<literal>other</literal>, <literal>press</literal>,
<literal>seq</literal>, or <literal>simul</literal>. The last two
values denote whether the keys or buttons should be pressed in
sequence, or simultaneously.</para>
<para>The stylesheets automatically add any connecting symbols, such
as <literal>+</literal>, between the key names, when wrapped in
<sgmltag>keycombo</sgmltag>.</para>
<example>
<title>Keys, mouse buttons, and combinations</title>
<para>Use:</para>
<programlisting><![ CDATA [<para>To switch to the second virtual terminal, press
<keycombo action="simul"><keycap>Alt</keycap>
<keycap>F1</keycap></keycombo>.</para>
<para>To exit <command>vi</command> without saving your work, type
<keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
<keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
<para>My window manager is configured so that
<keycombo action="simul"><keycap>Alt</keycap>
<mousebutton>right</mousebutton>
</keycombo> mouse button is used to move windows.</para>]]></programlisting>
<para>Appearance:</para>
<para>To switch to the second virtual terminal, press
<keycombo action="simul"><keycap>Alt</keycap>
<keycap>F1</keycap></keycombo>.</para>
<para>To exit <command>vi</command> without saving your work, type
<keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
<keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
<para>My window manager is configured so that
<keycombo action="simul"><keycap>Alt</keycap>
<mousebutton>right</mousebutton>
</keycombo> mouse button is used to move windows.</para>
</example>
</sect3>
<sect3>
<title>Applications, commands, options, and cites</title>
<para>You will frequently want to refer to both applications and
commands when writing for the Handbook. The distinction between
them is simple: an application is the name for a suite (or possibly
just 1) of programs that fulfil a particular task. A command is the
name of a program that the user can run.</para>
<para>In addition, you will occasionally need to list one or more of
the options that a command might take.</para>
<para>Finally, you will often want to list a command with its manual
section number, in the <quote>command(number)</quote> format so
common in Unix manuals.</para>
<para>Mark up application names with
<sgmltag>application</sgmltag>.</para>
<para>When you want to list a command with its manual section number
(which should be most of the time) the DocBook element is
<sgmltag>citerefentry</sgmltag>. This will contain a further two
elements, <sgmltag>refentrytitle</sgmltag> and
<sgmltag>manvolnum</sgmltag>. The content of
<sgmltag>refentrytitle</sgmltag> is the name of the command, and the
content of <sgmltag>manvolnum</sgmltag> is the manual page
section.</para>
<para>This can be cumbersome to write, and so a series of <link
linkend="sgml-primer-general-entities">general entities</link>
have been created to make this easier. Each entity takes the form
<literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
<para>The file that contains these entities is in
<filename>doc/share/sgml/man-refs.ent</filename>, and can be
referred to using this FPI:</para>
<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
<para>Therefore, the introduction to your documentation will probably
look like this:</para>
<programlisting><!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 you want to include a
command name <quote>in-line</quote> but present it as something the
user should type in.</para>
<para>Use <sgmltag>option</sgmltag> to mark up a command's
options.</para>
<para>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 HTML, appear
visually better.</para>
<para>This can be confusing, and sometimes the choice is not always
clear. Hopefully this example makes it clearer.</para>
<example>
<title>Applications, commands, and options.</title>
<para>Use:</para>
<programlisting><![ CDATA [<para><application>Sendmail</application> is the most
widely used Unix mail application.</para>
<para><application>Sendmail</application> includes the
<citerefentry>
<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, &man.mailq.8;, and &man.newaliases.8;
programs.</para>
<para>One of the command line parameters to <citerefentry>
<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, <option>-bp</option>, will display the current
status of messages in the mail queue. Check this on the command
line by running <command>sendmail -bp</command>.</para>]]></programlisting>
<para>Appearance:</para>
<para><application>Sendmail</application> is the most widely used
Unix mail application.</para>
<para><application>Sendmail</application> includes the
<citerefentry>
<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>mailq</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, and <citerefentry>
<refentrytitle>newaliases</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> programs.</para>
<para>One of the command line parameters to <citerefentry>
<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, <option>-bp</option>, will display the current
status of messages in the mail queue. Check this on the command
line by running <command>sendmail -bp</command>.</para>
</example>
<note>
<para>Notice how the
<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para>
</note>
</sect3>
<sect3>
<title>Files, directories, extensions</title>
<para>Whenever you wish to refer to the name of a file, a directory,
or a file extension, use <sgmltag>filename</sgmltag>.</para>
<example>
<title><sgmltag>filename</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
found in <filename>/usr/doc/en/handbook/</filename>. The first
file is called <filename>handbook.sgml</filename> in that
directory. You should also see a <filename>Makefile</filename>
and a number of files with a <filename>.ent</filename>
extension.</para>]]></programlisting>
<para>Appearance:</para>
<para>The SGML source for the Handbook in English can be found in
<filename>/usr/doc/en/handbook/</filename>. The first file is
called <filename>handbook.sgml</filename> in that directory. You
should also see a <filename>Makefile</filename> and a number of
files with a <filename>.ent</filename> extension.</para>
</example>
</sect3>
<sect3>
<title>The name of ports</title>
<note>
<title>FreeBSD extension</title>
<para>These elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.</para>
</note>
<para>You might need to include the name of a program from the
FreeBSD Ports Collection in the documentation. Use the
<sgmltag>filename</sgmltag> tag with the <literal>role</literal>
attribute set to <literal>package</literal> to identify these.
Since ports
can be installed in any number of locations, only include
the category and the port name; do not include
<filename>/usr/ports</filename>.</para>
<example>
<title><sgmltag>filename</sgmltag> tag with
<literal>package</literal> role</title>
<para>Use:</para>
<programlisting><![ CDATA [<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting>
<para>Appearance:</para>
<para>Install the <filename role="package">net/ethereal</filename>
port to view network traffic.</para>
</example>
</sect3>
<sect3>
<title>Devices</title>
<note>
<title>FreeBSD extension</title>
<para>These elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.</para>
</note>
<para>When referring to devices you have two choices. You can either
refer to the device as it appears in <filename>/dev</filename>, or
you can use the name of the device as it appears in the kernel. For
this latter course, use <sgmltag>devicename</sgmltag>.</para>
<para>Sometimes you will not have a choice. Some devices, such as
networking cards, do not have entries in <filename>/dev</filename>,
or the entries are markedly different from those entries.</para>
<example>
<title><sgmltag>devicename</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial
communication in FreeBSD. <devicename>sio</devicename> manifests
through a number of entries in <filename>/dev</filename>, including
<filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
<para>By contrast, the networking devices, such as
<devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>
<para>In MS-DOS, the first floppy drive is referred to as
<devicename>a:</devicename>. In FreeBSD it is
<filename>/dev/fd0</filename>.</para>]]></programlisting>
<para>Appearance:</para>
<para><devicename>sio</devicename> is used for serial communication
in FreeBSD. <devicename>sio</devicename> manifests through a
number of entries in <filename>/dev</filename>, including
<filename>/dev/ttyd0</filename> and
<filename>/dev/cuaa0</filename>.</para>
<para>By contrast, the networking devices, such as
<devicename>ed0</devicename> do not appear in
<filename>/dev</filename>.</para>
<para>In MS-DOS, the first floppy drive is referred to as
<devicename>a:</devicename>. In FreeBSD it is
<filename>/dev/fd0</filename>.</para>
</example>
</sect3>
<sect3>
<title>Hosts, domains, IP addresses, and so forth</title>
<note>
<title>FreeBSD extension</title>
<para>These elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.</para>
</note>
<para>You can markup identification information for networked
computers (hosts) in several ways, depending on the nature of the
information. All of them use <sgmltag>hostid</sgmltag> as the
element, with the <literal>role</literal> attribute selecting the
type of the marked up information.</para>
<variablelist>
<varlistentry>
<term>No role attribute, or
<literal>role="hostname"</literal></term>
<listitem>
<para>With no role attribute (i.e.,
<sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>) the
marked up information is the simple hostname, such as
<literal>freefall</literal> or <literal>wcarchive</literal>.
You can explicitly specify this with
<literal>role="hostname"</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="domainname"</literal></term>
<listitem>
<para>The text is a domain name, such as
<literal>FreeBSD.org</literal> or
<literal>ngo.org.uk</literal>. There is no hostname
component.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="fqdn"</literal></term>
<listitem>
<para>The text is a Fully Qualified Domain Name, with both
hostname and domain name parts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="ipaddr"</literal></term>
<listitem>
<para>The text is an IP address, probably expressed as a dotted
quad.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="ip6addr"</literal></term>
<listitem>
<para>The text is an IPv6 address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="netmask"</literal></term>
<listitem>
<para>The text is a network mask, which might be expressed as a
dotted quad, a hexadecimal string, or as a
<literal>/</literal> followed by a number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="mac"</literal></term>
<listitem>
<para>The text is an Ethernet MAC address, expressed as a series
of 2 digit hexadecimal numbers separated by colons.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><sgmltag>hostid</sgmltag> and roles</title>
<para>Use:</para>
<programlisting><![ CDATA [<para>The local machine can always be referred to by the
name <hostid>localhost</hostid>, which will have the IP address
<hostid role="ipaddr">127.0.0.1</hostid>.</para>
<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
contains a number of different hosts, including
<hostid role="fqdn">freefall.FreeBSD.org</hostid> and
<hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
<para>When adding an IP alias to an interface (using
<command>ifconfig</command>) <emphasis>always</emphasis> use a
netmask of <hostid role="netmask">255.255.255.255</hostid>
(which can also be expressed as <hostid
role="netmask">0xffffffff</hostid>.</para>
<para>The MAC address uniquely identifies every network card
in existence. A typical MAC address looks like <hostid
role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
<para>Appearance:</para>
<para>The local machine can always be referred to by the name
<hostid>localhost</hostid>, which will have the IP address <hostid
role="ipaddr">127.0.0.1</hostid>.</para>
<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
contains a number of different hosts, including <hostid
role="fqdn">freefall.FreeBSD.org</hostid> and <hostid
role="fqdn">bento.FreeBSD.org</hostid>.</para>
<para>When adding an IP alias to an interface (using
<command>ifconfig</command>) <emphasis>always</emphasis> use a
netmask of <hostid role="netmask">255.255.255.255</hostid> (which
can also be expressed as <hostid
role="netmask">0xffffffff</hostid>.</para>
<para>The MAC address uniquely identifies every network card in
existence. A typical MAC address looks like <hostid
role="mac">08:00:20:87:ef:d0</hostid>.</para>
</example>
</sect3>
<sect3>
<title>Usernames</title>
<note>
<title>FreeBSD extension</title>
<para>These elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.</para>
</note>
<para>When you need to refer to a specific username, such as
<literal>root</literal> or <literal>bin</literal>, use
<sgmltag>username</sgmltag>.</para>
<example>
<title><sgmltag>username</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>To carry out most system administration functions you
will need to be <username>root</username>.</para>]]></programlisting>
<para>Appearance:</para>
<para>To carry out most system administration functions you will
need to be <username>root</username>.</para>
</example>
</sect3>
<sect3>
<title>Describing <filename>Makefile</filename>s</title>
<note>
<title>FreeBSD extension</title>
<para>These elements are part of the FreeBSD extension to DocBook,
and do not exist in the original DocBook DTD.</para>
</note>
<para>Two elements exist to describe parts of
<filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and
<sgmltag>makevar</sgmltag>.</para>
<para><sgmltag>maketarget</sgmltag> identifies a build target exported
by a <filename>Makefile</filename> that can be given as a parameter
to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a
variable that can be set (in the environment, on the
<command>make</command> command line, or within the
<filename>Makefile</filename>) to influence the process.</para>
<example>
<title><sgmltag>maketarget</sgmltag> and
<sgmltag>makevar</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename>
are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
application, and invoking <maketarget>clean</maketarget> will remove
the temporary files (<filename>.o</filename> for example) created by
the build process.</para>
<para><maketarget>clean</maketarget> may be controlled by a number of
variables, including <makevar>CLOBBER</makevar> and
<makevar>RECURSE</makevar>.</para>]]></programlisting>
<para>Appearance:</para>
<para>Two common targets in a <filename>Makefile</filename> are
<maketarget>all</maketarget> and
<maketarget>clean</maketarget>.</para>
<para>Typically, invoking <maketarget>all</maketarget> will rebuild
the application, and invoking <maketarget>clean</maketarget> will
remove the temporary files (<filename>.o</filename> for example)
created by the build process.</para>
<para><maketarget>clean</maketarget> may be controlled by a number
of variables, including <makevar>CLOBBER</makevar> and
<makevar>RECURSE</makevar>.</para>
</example>
</sect3>
<sect3>
<title>Literal text</title>
<para>You will often need to include <quote>literal</quote> text in the
Handbook. This is text that is excerpted from another file, or
which should be copied from the Handbook into another file
verbatim.</para>
<para>Some of the time, <sgmltag>programlisting</sgmltag> will be
sufficient to denote this text. <sgmltag>programlisting</sgmltag>
is not always appropriate, particularly when you want to include a
portion of a file <quote>in-line</quote> with the rest of the
paragraph.</para>
<para>On these occasions, use <sgmltag>literal</sgmltag>.</para>
<example>
<title><sgmltag>literal</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel
configuration file determines the size of many system tables, and is
a rough guide to how many simultaneous logins the system will
support.</para>]]></programlisting>
<para>Appearance:</para>
<para>The <literal>maxusers 10</literal> line in the kernel
configuration file determines the size of many system tables, and
is a rough guide to how many simultaneous logins the system will
support.</para>
</example>
</sect3>
<sect3>
<title>Showing items that the user <emphasis>must</emphasis> fill
in</title>
<para>There will often be times when you want to show the user what to
do, or refer to a file, or command line, or similar, where the user
cannot simply copy the examples that you provide, but must instead
include some information themselves.</para>
<para><sgmltag>replaceable</sgmltag> is designed for this eventuality.
Use it <emphasis>inside</emphasis> other elements to indicate parts
of that element's content that the user must replace.</para>
<example>
<title><sgmltag>replaceable</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<informalexample>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>]]></programlisting>
<para>Appearance:</para>
<informalexample>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>
<para><sgmltag>replaceable</sgmltag> can be used in many different
elements, including <sgmltag>literal</sgmltag>. This example also
shows that <sgmltag>replaceable</sgmltag> should only be wrapped
around the content that the user <emphasis>is</emphasis> meant to
provide. The other content should be left alone.</para>
<para>Use:</para>
<programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal>
line in the kernel configuration file determines the size of many system
tables, and is a rough guide to how many simultaneous logins the system will
support.</para>
<para>For a desktop workstation, <literal>32</literal> is a good value
for <replaceable>n</replaceable>.</para>]]></programlisting>
<para>Appearance:</para>
<para>The <literal>maxusers <replaceable>n</replaceable></literal>
line in the kernel configuration file determines the size of many
system tables, and is a rough guide to how many simultaneous
logins the system will support.</para>
<para>For a desktop workstation, <literal>32</literal> is a good
value for <replaceable>n</replaceable>.</para>
</example>
</sect3>
<sect3>
<title>Quoting system errors</title>
<para>You might want to show errors generated by FreeBSD.
Mark these with <sgmltag>errorname</sgmltag>. This
indicates the exact error that appears.</para>
<example>
<title><sgmltag>errorname</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [
<screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
</programlisting>
<para>Appearance:</para>
<informalexample>
<screen><errorname>Panic: cannot mount root</errorname></screen>
</informalexample>
</example>
</sect3>
</sect2>
<sect2>
<title>Images</title>
<important>
<para>Image support in the documentation is currently extremely
experimental. I think the mechanisms described here are unlikely to
change, but that is not guaranteed.</para>
<para>You will also need to install the
<filename role="package">graphics/ImageMagick</filename> port, which is used to
convert between the different image formats. This is a big port,
and most of it is not required. However, while we are working on the
<filename>Makefile</filename>s and other infrastructure it makes
things easier. This port is <emphasis>not</emphasis> in the
<filename role="package">textproc/docproj</filename> meta port, you must install it
by hand.</para>
<para>The best example of what follows in practice is the
<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document.
If you are unsure of the description that follows, take a look at the
files in that directory to see how everything hangs together.
Experiment with creating different formatted versions of the
document to see how the image markup appears in the formatted
output.</para>
</important>
<sect3>
<title>Image formats</title>
<para>We currently support two formats for images. The format you
should use will depend on the nature of your image.</para>
<para>For images that are primarily vector based, such as network
diagrams, time lines, and similar, use Encapsulated Postscript, and
make sure that your images have the <filename>.eps</filename>
extension.</para>
<para>For bitmaps, such as screen captures, use the Portable Network
Graphic format, and make sure that your images have the
<filename>.png</filename> extension.</para>
<para>These are the <emphasis>only</emphasis> formats in which images
should be committed to the CVS repository.</para>
<para>Use the right format for the right image. It is to be expected
that your documentation will have a mix of EPS and PNG images. The
<filename>Makefile</filename>s ensure that the correct format image
is chosen depending on the output format that you use for your
documentation. <emphasis>Do not commit the same image to the
repository in two different formats</emphasis>.</para>
<important>
<para>It is anticipated that the Documentation Project will switch to
using the Scalable Vector Graphic (SVG) format for vector images.
However, the current state of SVG capable editing tools makes this
impractical.</para>
</important>
</sect3>
<sect3>
<title>Markup</title>
<para>The markup for an image is relatively simple. First, markup a
<sgmltag>mediaobject</sgmltag>. The <sgmltag>mediaobject</sgmltag>
can contain other, more specific objects. We are concerned with
two, the <sgmltag>imageobject</sgmltag> and the
<sgmltag>textobject</sgmltag>.</para>
<para>You should include one <sgmltag>imageobject</sgmltag>, and two
<sgmltag>textobject</sgmltag> elements. The
<sgmltag>imageobject</sgmltag> will point to the name of the image
file that will be used (without the extension). The
<sgmltag>textobject</sgmltag> elements contain information that will
be presented to the user as well as, or instead of, the
image.</para>
<para>There are two circumstances where this can happen.</para>
<itemizedlist>
<listitem>
<para>When the reader is viewing the documentation in HTML. In
this case, each image will need to have associated alternate
text to show the user, typically whilst the image is loading, or
if they hover the mouse pointer over the image.</para>
</listitem>
<listitem>
<para>When the reader is viewing the documentation in plain text.
In this case, each image should have an ASCII art equivalent to
show the user.</para>
</listitem>
</itemizedlist>
<para>An example will probably make things easier to understand.
Suppose you have an image, called <filename>fig1</filename>, that
you want to include in the document. This image is of a rectangle
with an A inside it. The markup for this would be as
follows.</para>
<programlisting><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> should contain a
<sgmltag>literallayout</sgmltag> element, where the
<literal>class</literal> attribute is set to
<literal>monospaced</literal>. This is your opportunity to
demonstrate your ASCII art skills. This content will be used if
the document is converted to plain text.</para>
<para>Notice how the first and last lines of the content of the
<sgmltag>literallayout</sgmltag> element butt up next to the
element's tags. This ensures no extraneous white space is
included.</para>
</callout>
<callout arearefs="co-image-phrase">
<para>The second <sgmltag>textobject</sgmltag> should contain a
single <sgmltag>phrase</sgmltag> element. The contents of this
will become the <literal>alt</literal> attribute for the image
when this document is converted to HTML.</para>
</callout>
</calloutlist>
</sect3>
<sect3>
<title><filename>Makefile</filename> entries</title>
<para>Your images must be listed in the
<filename>Makefile</filename> in the <makevar>IMAGES</makevar>
variable. This variable should contain the name of all your
<emphasis>source</emphasis> images. For example, if you have
created three figures, <filename>fig1.eps</filename>,
<filename>fig2.png</filename>, <filename>fig3.png</filename>, then
your <filename>Makefile</filename> should have lines like this in
it.</para>
<programlisting>…
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 your source document, you
only need to list the image files <emphasis>you</emphasis>
provided.</para>
</sect3>
<sect3>
<title>Images and chapters in subdirectories</title>
<para>You must be careful when you separate your documentation into
smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in
different directories.</para>
<para>Suppose you have a book with three chapters, and the chapters
are stored in their own directories, called
<filename>chapter1/chapter.sgml</filename>,
<filename>chapter2/chapter.sgml</filename>, and
<filename>chapter3/chapter.sgml</filename>. If each chapter has
images associated with it, I suggest you place those images in each
chapter's subdirectory (<filename>chapter1/</filename>,
<filename>chapter2/</filename>, and
<filename>chapter3/</filename>).</para>
<para>However, if you do this you must include the directory names in
the <makevar>IMAGES</makevar> variable in the
<filename>Makefile</filename>, <emphasis>and</emphasis> you must
include the directory name in the <sgmltag>imagedata</sgmltag>
element in your document.</para>
<para>For example, if you have <filename>chapter1/fig1.png</filename>,
then <filename>chapter1/chapter.sgml</filename> should
contain</para>
<programlisting><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 should just work.</para>
</sect3>
</sect2>
<sect2>
<title>Links</title>
<note>
<para>Links are also in-line elements.</para>
</note>
<sect3>
<title>Linking to other parts of the same document</title>
<para>Linking within the same document requires you to specify
where you are linking from (i.e., the text the user will click, or
otherwise indicate, as the source of the link) and where you are
linking to (the link's destination).</para>
<para>Each element within DocBook has an attribute called
<literal>id</literal>. You can place text in this attribute to
uniquely name the element it is attached to.</para>
<para>This value will be used when you specify the link
source.</para>
<para>Normally, you will only be linking to chapters or sections, so
you would add the <literal>id</literal> attribute to these
elements.</para>
<example>
<title><literal>id on chapters and sections</literal></title>
<programlisting><![ CDATA [<chapter id="chapter1">
<title>Introduction</title>
<para>This is the introduction. It contains a subsection,
which is identified as well.</para>
<sect1 id="chapter1-sect1">
<title>Sub-sect 1</title>
<para>This is the subsection.</para>
</sect1>
</chapter>]]></programlisting>
</example>
<para>Obviously, you should use more descriptive values. The values
must be unique within the document (i.e., not just the file, but the
document the file might be included in as well). Notice how the
<literal>id</literal> for the subsection is constructed by appending
text to the <literal>id</literal> of the chapter. This helps to
ensure that they are unique.</para>
<para>If you want to allow the user to jump into a specific portion of
the document (possibly in the middle of a paragraph or an example),
use <sgmltag>anchor</sgmltag>. This element has no content, but
takes an <literal>id</literal> attribute.</para>
<example>
<title><sgmltag>anchor</sgmltag></title>
<programlisting><![ CDATA [<para>This paragraph has an embedded
<anchor id="para1">link target in it. It will not show up in
the document.</para>]]></programlisting>
</example>
<para>When you want to provide the user with a link they can activate
(probably by clicking) to go to a section of the document that has
an <literal>id</literal> attribute, you can use either
<sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para>
<para>Both of these elements have a <literal>linkend</literal>
attribute. The value of this attribute should be the value that you
have used in a <literal>id</literal> attribute (it does not matter
if that value has not yet occurred in your document; this will work
for forward links as well as backward links).</para>
<para>If you use <sgmltag>xref</sgmltag> then you have no control over
the text of the link. It will be generated for you.</para>
<example>
<title>Using <sgmltag>xref</sgmltag></title>
<para>Assume that this fragment appears somewhere in a document that
includes the <literal>id</literal> example;</para>
<programlisting><![ CDATA [<para>More information can be found
in <xref linkend="chapter1">.</para>
<para>More specific information can be found
in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
<para>The text of the link will be generated automatically, and will
look like (<emphasis>emphasised</emphasis> text indicates the text
that will be the link);</para>
<blockquote>
<para>More information can be found in <emphasis>Chapter
One</emphasis>.</para>
<para>More specific information can be found in <emphasis>the
section called Sub-sect 1</emphasis>.</para>
</blockquote>
</example>
<para>Notice how the text from the link is derived from the section
title or the chapter number.</para>
<note>
<para>This means that you <emphasis>cannot</emphasis> use
<sgmltag>xref</sgmltag> to link to an <literal>id</literal>
attribute on an <sgmltag>anchor</sgmltag> element. The
<sgmltag>anchor</sgmltag> has no content, so the
<sgmltag>xref</sgmltag> cannot generate the text for the
link.</para>
</note>
<para>If you want to control the text of the link then use
<sgmltag>link</sgmltag>. This element wraps content, and the
content will be used for the link.</para>
<example>
<title>Using <sgmltag>link</sgmltag></title>
<para>Assume that this fragment appears somewhere in a document that
includes the <literal>id</literal> example.</para>
<programlisting><![ CDATA [<para>More information can be found in
<link linkend="chapter1">the first chapter</link>.</para>
<para>More specific information can be found in
<link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting>
<para>This will generate the following
(<emphasis>emphasised</emphasis> text indicates the text that will
be the link);</para>
<blockquote>
<para>More information can be found in <emphasis>the first
chapter</emphasis>.</para>
<para>More specific information can be found in
<emphasis>this</emphasis> section.</para>
</blockquote>
</example>
<note>
<para>That last one is a bad example. Never use words like
<quote>this</quote> or <quote>here</quote> as the source for the
link. The reader will need to hunt around the surrounding context
to see where the link is actually taking them.</para>
</note>
<note>
<para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to
include a link to an <literal>id</literal> on an
<sgmltag>anchor</sgmltag> element, since the
<sgmltag>link</sgmltag> content defines the text that will be used
for the link.</para>
</note>
</sect3>
<sect3>
<title>Linking to documents on the WWW</title>
<para>Linking to external documents is much simpler, as long as you
know the URL of the document you want to link to. Use
<sgmltag>ulink</sgmltag>. The <literal>url</literal> attribute is
the URL of the page that the link points to, and the content of the
element is the text that will be displayed for the user to
activate.</para>
<example>
<title><sgmltag>ulink</sgmltag></title>
<para>Use:</para>
<programlisting><![ CDATA [<para>Of course, you could stop reading this document and
go to the <ulink url="../../../../index.html">FreeBSD
home page</ulink> instead.</para>]]></programlisting>
<para>Appearance:</para>
<para>Of course, you could stop reading this document and go to the
<ulink url="../../../../index.html">FreeBSD home page</ulink>
instead.</para>
</example>
</sect3>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
