From f54c6e3eda631db955e45dae0a9392c367d10d5b Mon Sep 17 00:00:00 2001
From: Warren Block <wblock@FreeBSD.org>
Date: Sat, 21 Apr 2012 04:52:03 +0000
Subject: [PATCH] Whitespace-only cleanup.
---
.../books/fdp-primer/sgml-markup/chapter.sgml | 2067 +++++++++--------
1 file changed, 1097 insertions(+), 970 deletions(-)
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 060d67e819..e27354d7b1 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -33,64 +33,67 @@
<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>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>
+ <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>
+ <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
- <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, the HyperText Markup Language, is the markup language
+ of choice on the World Wide Web. More information can be found
+ at <ulink url="http://www.w3.org/"></ulink>.</para>
- <para>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>
+ <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>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>
+ <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>
@@ -98,16 +101,17 @@
<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>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>
+ <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>
@@ -125,24 +129,25 @@
</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>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 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>
+ <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>,
+ etc.</title>
<para>Use:</para>
@@ -160,20 +165,22 @@
<h2>This is the heading for the second section</h2>
-<!-- Content for the second section goes here -->]]></programlisting>
+<!-- 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>
+
+ <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>
+ <sgmltag>h<replaceable>n</replaceable></sgmltag>
+ Elements</title>
<para>Use:</para>
@@ -186,7 +193,7 @@
<!-- This is bad, <h2> has been left out -->]]></programlisting>
</example>
</sect3>
-
+
<sect3>
<title>Paragraphs</title>
@@ -206,8 +213,9 @@
<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>
+ <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>
@@ -228,32 +236,35 @@
<sect3>
<title>Lists</title>
- <para>You can present the user with three types of lists, ordered,
- unordered, and definition.</para>
+ <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>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>
+ 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>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>
+ (<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>
+ <title><sgmltag>ul</sgmltag> and
+ <sgmltag>ol</sgmltag></title>
<para>Use:</para>
@@ -310,10 +321,11 @@
<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>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>
@@ -321,8 +333,8 @@
<example>
<title><sgmltag>pre</sgmltag></title>
- <para>You could use <sgmltag>pre</sgmltag> to mark up an email
- message:</para>
+ <para>You could use <sgmltag>pre</sgmltag> to mark up an
+ email message:</para>
<programlisting><![ CDATA [<pre> From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
@@ -343,10 +355,10 @@
shown had to use <literal>&lt;</literal> instead of
<literal><</literal>. For consistency,
<literal>&gt;</literal> was used in place of
- <literal>></literal>, too. Watch out for the special characters
- that may appear in text copied from a plain-text source,
- e.g., an email message or program code.</para>
-
+ <literal>></literal>, too. Watch out for the special
+ characters that may appear in text copied from a
+ plain-text source, e.g., an email message or program
+ code.</para>
</example>
</sect3>
@@ -354,18 +366,19 @@
<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>
+ <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
+ <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>
@@ -390,10 +403,11 @@
</tr>
</table>]]></programlisting></example>
- <para>A cell can span multiple rows and columns. To indicate this,
- add the <literal>rowspan</literal> and/or <literal>colspan</literal>
- attributes, with values indicating the number of rows or columns
- that should be spanned.</para>
+ <para>A cell can span multiple rows and columns. To indicate
+ this, add the <literal>rowspan</literal> and/or
+ <literal>colspan</literal> attributes, with values
+ indicating the number of rows or columns that should be
+ spanned.</para>
<example>
<title>Using <literal>rowspan</literal></title>
@@ -481,14 +495,17 @@
<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>
+ <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>
+ <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>
+ <title><sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag></title>
<para>Use:</para>
@@ -500,9 +517,9 @@
<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
+ <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>
@@ -516,8 +533,8 @@
<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
+ <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>
@@ -534,29 +551,35 @@
<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>
+ <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>
+ <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>
+ <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>
+ <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 <literal>1</literal> and <literal>7</literal>. The default font size
- is <literal>3</literal>. This approach is deprecated.</para>
+ <para>Use <sgmltag>font</sgmltag> with the
+ <literal>size</literal> attribute set to a number
+ between <literal>1</literal> and <literal>7</literal>.
+ The default font size is <literal>3</literal>. This
+ approach is deprecated.</para>
</listitem>
</orderedlist>
@@ -588,15 +611,16 @@
<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>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>
+ <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>
@@ -610,13 +634,13 @@
<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>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
@@ -631,30 +655,32 @@
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>
+ <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>
+ <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>
+ <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>
+ <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
@@ -663,71 +689,75 @@
</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/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 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>
+ <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/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 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>Formal vs. 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>
+ <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>
-
+
+ <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>&os; Extensions</title>
- <para>The FreeBSD Documentation Project has extended the DocBook DTD by
- adding some new elements. These elements serve to make some of the
- markup more precise.</para>
+ <para>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>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>
-
+ <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.doceng;.</para>
+ 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; CVS tree, as <ulink
- url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
+ <para>The &os; extensions are not (currently) in the
+ Ports Collection. They are stored in the &os; 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 customizations, the FPI for the FreeBSD extended DocBook DTD
- is:</para>
+ <para>In compliance with the DocBook guidelines for writing FPIs
+ for DocBook customizations, the FPI for the FreeBSD extended
+ DocBook DTD is:</para>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
</sect2>
@@ -735,52 +765,58 @@
<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>DocBook allows you to structure your documentation in
+ several ways. In the FreeBSD Documentation Project we are
+ using two primary types of DocBook document: the book and the
+ article.</para>
- <para>A book is organized into <sgmltag>chapter</sgmltag>s. This is a
- mandatory requirement. There may be <sgmltag>part</sgmltag>s between
- the book and the chapter to provide another layer of organization.
- For example, the Handbook is arranged in this way.</para>
+ <para>A book is organized into <sgmltag>chapter</sgmltag>s.
+ This is a mandatory requirement. There may be
+ <sgmltag>part</sgmltag>s between the book and the chapter to
+ provide another layer of organization. For example, the
+ Handbook is arranged in this way.</para>
- <para>A chapter may (or may not) contain one or more sections. These
- are indicated with the <sgmltag>sect1</sgmltag> element. If a section
- contains another section then use the <sgmltag>sect2</sgmltag>
- element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
+ <para>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>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>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>Obviously, you should consider the nature of the
+ documentation you are writing in order to decide whether it is
+ best marked up as a book or an article. Articles are well
+ suited to information that does not need to be broken down
+ into several chapters, and that is, relatively speaking, quite
+ short, at up to 20-25 pages of content. Books are best suited
+ to information that can be broken up into several chapters,
+ possibly with appendices and similar content as well.</para>
<para>The <ulink url="&url.base;/docs.html">FreeBSD
tutorials</ulink> are all marked up as articles, while this
- document, the <ulink url="&url.books.faq;/index.html">FreeBSD
- FAQ</ulink>, and the <ulink
- url="&url.books.handbook;/index.html">FreeBSD Handbook</ulink> are
- all marked up as books, for example.</para>
+ document, the
+ <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
+ and the <ulink url="&url.books.handbook;/index.html">FreeBSD
+ Handbook</ulink> are all marked up as books, for
+ example.</para>
<sect3>
<title>Starting a Book</title>
<para>The content of the book is contained within the
- <sgmltag>book</sgmltag> element. As well as containing structural
- markup, this element can contain elements that include additional
- information about the book. This is either meta-information, used
- for reference purposes, or additional content used to produce a
- title page.</para>
+ <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>
@@ -826,10 +862,10 @@
<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>
+ 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>
@@ -867,14 +903,16 @@
…
</article></programlisting>
- </example>
+ </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>
+ <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>
@@ -886,9 +924,10 @@
</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>
+ <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>
@@ -897,25 +936,27 @@
<title>This is An Empty Chapter</title>
<para></para>
-</chapter>]]></programlisting>
+</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>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>
+ <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>
@@ -952,22 +993,24 @@
</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>
+ <para>This example includes section numbers in the section
+ titles. You should not do this in your documents. Adding
+ the section numbers is carried out by the stylesheets (of
+ which more later), and you do not need to manage them
+ yourself.</para>
</note>
</sect3>
-
+
<sect3>
- <title>Subdividing Using <sgmltag>part</sgmltag> Elements</title>
+ <title>Subdividing Using <sgmltag>part</sgmltag>
+ Elements</title>
<para>You can introduce another layer of organization between
- <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
- more <sgmltag>part</sgmltag>s. This cannot be done in an
- <sgmltag>article</sgmltag>.</para>
+ <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>
@@ -992,53 +1035,56 @@
</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>
-
+ <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>
+
+ <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>
+
+ <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>
@@ -1054,118 +1100,125 @@
</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>
+ <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>
-
+ <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>
+ <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>
- <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>
+ <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>
+ <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>
+ <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>
-
+ </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>
+ <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>,
+
+ <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>
-
+ <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>
+ <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>
@@ -1199,24 +1252,24 @@
<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>
@@ -1224,41 +1277,42 @@
</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>
+ </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>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>
-
+ 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>
@@ -1271,39 +1325,40 @@ main(void)
}</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>
-
+ <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>
+}</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>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>
-
+ <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>
@@ -1352,47 +1407,50 @@ main(void)
<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>
+ <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>
+ <literal>hello, world</literal> to standard
+ output.</para>
</callout>
- </calloutlist>
+ </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>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>
- <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag>
- contain <sgmltag>row</sgmltag> elements, which in turn contain
- <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag>
- element specifies one cell in the table.</para>
-
<example>
<title><sgmltag>informaltable</sgmltag></title>
-
+
<para>Use:</para>
-
+
<programlisting><![ CDATA [<informaltable pgwide="1">
<tgroup cols="2">
<thead>
@@ -1415,9 +1473,9 @@ main(void)
</tbody>
</tgroup>
</informaltable>]]></programlisting>
-
+
<para>Appearance:</para>
-
+
<informaltable pgwide="1">
<tgroup cols="2">
<thead>
@@ -1426,13 +1484,13 @@ main(void)
<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>
@@ -1441,7 +1499,7 @@ main(void)
</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
@@ -1456,9 +1514,9 @@ main(void)
<example>
<title>Tables Where <literal>frame="none"</literal></title>
-
+
<para>Appearance:</para>
-
+
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
<thead>
@@ -1467,13 +1525,13 @@ main(void)
<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>
@@ -1483,76 +1541,80 @@ main(void)
</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>
-
+
+ <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
+ <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
+ <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>
+ <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>
+ 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>
+ <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>
-
+ <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
@@ -1563,9 +1625,9 @@ foo2
<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
@@ -1577,57 +1639,59 @@ foo2
&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>
+ <filename>foo2</filename>, it is <emphasis>not</emphasis>
+ marked up as <sgmltag>programlisting</sgmltag>. Reserve
+ <sgmltag>programlisting</sgmltag> for showing fragments of
+ files outside the context of user actions.</para>
</note>
</sect3>
</sect2>
-
+
<sect2>
<title>In-line Elements</title>
-
+
<sect3>
<title>Emphasizing Information</title>
-
- <para>When you want to emphasize a particular word or phrase, use
- <sgmltag>emphasis</sgmltag>. This may be presented as italic, or
- bold, or might be spoken differently with a text-to-speech
- system.</para>
-
- <para>There is no way to change the presentation of the emphasis
- within your document, no equivalent of HTML's <sgmltag>b</sgmltag>
- and <sgmltag>i</sgmltag>. If the information you are presenting is
- important then consider presenting it in
- <sgmltag>important</sgmltag> rather than
+
+ <para>When you want to emphasize a particular word or phrase,
+ use <sgmltag>emphasis</sgmltag>. This may be presented as
+ italic, or bold, or might be spoken differently with a
+ text-to-speech system.</para>
+
+ <para>There is no way to change the presentation of the
+ emphasis within your document, no equivalent of HTML's
+ <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag>. If the
+ information you are presenting is important then consider
+ presenting it in <sgmltag>important</sgmltag> rather than
<sgmltag>emphasis</sgmltag>.</para>
-
+
<example>
<title><sgmltag>emphasis</sgmltag></title>
-
+
<para>Use:</para>
-
+
<programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
-
+
<para>Appearance:</para>
-
- <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix
- like operating system for the Intel architecture.</para>
+
+ <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>
+ <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>
@@ -1640,38 +1704,38 @@ This is the file called 'foo2'</screen>
<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>
+ <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>
+ <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>
+ <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>
- <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>
@@ -1686,53 +1750,60 @@ This is the file called 'foo2'</screen>
</keycombo> mouse button is used to move windows.</para>]]></programlisting>
<para>Appearance:</para>
-
- <para>To switch to the second virtual terminal, press
+
+ <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>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>
+ <keycombo action="simul">
+ <keycap>Alt</keycap>
+ <mousebutton>right</mousebutton></keycombo> mouse button
+ is used to move windows.</para>
</example>
</sect3>
-
+
<sect3>
<title>Applications, Commands, Options, and Cites</title>
-
- <para>You will frequently want to refer to both applications and
- commands when writing documentation. The distinction between
- them is simple: an application is the name for a suite (or possibly
- just 1) of programs that fulfill a particular task. A command is the
- name of a program that the user can run.</para>
- <para>In addition, you will occasionally need to list one or more of
- the options that a command might take.</para>
-
- <para>Finally, you will often want to list a command with its manual
- section number, in the <quote>command(number)</quote> format so
- common in Unix manuals.</para>
-
+ <para>You will frequently want to refer to both applications
+ and commands when writing documentation. The distinction
+ between them is simple: an application is the name for a
+ suite (or possibly just 1) of programs that fulfill a
+ particular task. A command is the name of a program that
+ the user can run.</para>
+
+ <para>In addition, you will occasionally need to list one or
+ more of the options that a command might take.</para>
+
+ <para>Finally, you will often want to list a command with its
+ manual section number, in the <quote>command(number)</quote>
+ format so common in Unix manuals.</para>
+
<para>Mark up application names with
<sgmltag>application</sgmltag>.</para>
-
- <para>When you want to list a command with its manual section number
- (which should be most of the time) the DocBook element is
- <sgmltag>citerefentry</sgmltag>. This will contain a further two
- elements, <sgmltag>refentrytitle</sgmltag> and
- <sgmltag>manvolnum</sgmltag>. The content of
- <sgmltag>refentrytitle</sgmltag> is the name of the command, and the
- content of <sgmltag>manvolnum</sgmltag> is the manual page
- section.</para>
- <para>This can be cumbersome to write, and so a series of <link
- linkend="sgml-primer-general-entities">general entities</link>
- have been created to make this easier. Each entity takes the form
+ <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
@@ -1741,8 +1812,8 @@ This is the file called 'foo2'</screen>
<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
- <para>Therefore, the introduction to your documentation will probably
- look like this:</para>
+ <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" [
@@ -1753,9 +1824,9 @@ This is the file called 'foo2'</screen>
]></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>command</sgmltag> when you want to include
+ a command name <quote>in-line</quote> but present it as
+ something the user should type in.</para>
<para>Use <sgmltag>option</sgmltag> to mark up the options
which will be passed to a command.</para>
@@ -1768,14 +1839,15 @@ This is the file called 'foo2'</screen>
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>
+ <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>
@@ -1794,41 +1866,46 @@ This is the file called 'foo2'</screen>
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> 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>
+ </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>
+ </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>
+ <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>
-
+
+ <para>Whenever you wish to refer to the name of a file, a
+ directory, or a file extension, use
+ <sgmltag>filename</sgmltag>.</para>
+
<example>
<title><sgmltag>filename</sgmltag></title>
-
+
<para>Use:</para>
-
+
<programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first
file is called <filename>book.sgml</filename> in that
@@ -1837,73 +1914,79 @@ This is the file called 'foo2'</screen>
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>
+
+ <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>
-
+ <title>The Name of Ports</title>
+
<note>
<title>&os; Extension</title>
-
- <para>These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.</para>
+
+ <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>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>
- <para>Use:</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>
+ <para>Appearance:</para>
+
+ <para>Install the <filename
+ role="package">net/ethereal</filename> port to view
+ network traffic.</para>
+ </example>
</sect3>
<sect3>
<title>Devices</title>
-
+
<note>
<title>&os; Extension</title>
-
- <para>These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.</para>
+
+ <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>
-
+
+ <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
@@ -1917,57 +2000,61 @@ This is the file called 'foo2'</screen>
<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
+
+ <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>
+ <filename>/dev/fd0</filename>.</para>
</example>
</sect3>
-
+
<sect3>
<title>Hosts, Domains, IP Addresses, and So Forth</title>
-
+
<note>
<title>&os; Extension</title>
-
- <para>These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.</para>
+
+ <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>
-
+ computers (hosts) in several ways, depending on the nature
+ of the information. All of them use
+ <sgmltag>hostid</sgmltag> as the element, with the
+ <literal>role</literal> attribute selecting the type of the
+ marked up information.</para>
+
<variablelist>
<varlistentry>
<term>No <literal>role</literal> attribute, or
<literal>role="hostname"</literal></term>
-
+
<listitem>
<para>With no <literal>role</literal> attribute (i.e.,
- <sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>) the
- marked up information is the simple hostname, such as
- <literal>freefall</literal> or <literal>wcarchive</literal>.
- You can explicitly specify this with
+ <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
@@ -1975,58 +2062,59 @@ This is the file called 'foo2'</screen>
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>
+ <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>
+ <para>The text is an IP address, probably expressed as a
+ dotted quad.</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>role="ip6addr"</literal></term>
+ <varlistentry>
+ <term><literal>role="ip6addr"</literal></term>
+
+ <listitem>
+ <para>The text is an IPv6 address.</para>
+ </listitem>
+ </varlistentry>
- <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>
+ <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>
+ <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>
@@ -2047,84 +2135,89 @@ This is the file called 'foo2'</screen>
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>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
+ <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>
+ <para>The MAC address uniquely identifies every network card
+ in existence. A typical MAC address looks like <hostid
+ role="mac">08:00:20:87:ef:d0</hostid>.</para>
</example>
</sect3>
-
+
<sect3>
<title>Usernames</title>
-
+
<note>
<title>&os; Extension</title>
-
- <para>These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.</para>
+
+ <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>
+
+ <para>To carry out most system administration functions you
+ will need to be <username>root</username>.</para>
</example>
</sect3>
-
+
<sect3>
<title>Describing <filename>Makefile</filename>s</title>
-
+
<note>
<title>&os; Extension</title>
-
- <para>These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.</para>
+
+ <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
+ <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>
+
+ <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>
@@ -2138,91 +2231,98 @@ This is the file called 'foo2'</screen>
<makevar>RECURSE</makevar>.</para>]]></programlisting>
<para>Appearance:</para>
-
- <para>Two common targets in a <filename>Makefile</filename> are
- <maketarget>all</maketarget> and
+
+ <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>
+
+ <para>Typically, invoking <maketarget>all</maketarget> will
+ rebuild the application, and invoking
+ <maketarget>clean</maketarget> will remove the temporary
+ files (<filename>.o</filename> for example) created by the
+ build process.</para>
+
+ <para><maketarget>clean</maketarget> may be controlled by a
+ number of variables, including <makevar>CLOBBER</makevar>
+ and <makevar>RECURSE</makevar>.</para>
</example>
</sect3>
-
+
<sect3>
<title>Literal Text</title>
-
- <para>You will often need to include <quote>literal</quote> text in the
- documentation. This is text that is excerpted from another file, or
- which should be copied from the documentation into another file
- verbatim.</para>
- <para>Some of the time, <sgmltag>programlisting</sgmltag> will be
- sufficient to denote this text. <sgmltag>programlisting</sgmltag>
- is not always appropriate, particularly when you want to include a
- portion of a file <quote>in-line</quote> with the rest of the
+ <para>You will often need to include <quote>literal</quote>
+ text in the documentation. This is text that is excerpted
+ from another file, or which should be copied from the
+ documentation into another file verbatim.</para>
+
+ <para>Some of the time, <sgmltag>programlisting</sgmltag> will
+ be sufficient to denote this text.
+ <sgmltag>programlisting</sgmltag> is not always appropriate,
+ particularly when you want to include a portion of a file
+ <quote>in-line</quote> with the rest of the
paragraph.</para>
- <para>On these occasions, use <sgmltag>literal</sgmltag>.</para>
-
+ <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>
+ 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>
-
+ <title>Showing Items That the User <emphasis>Must</emphasis>
+ Fill In</title>
+
+ <para>There will often be times when you want to show the user
+ what to do, or refer to a file, or command line, or similar,
+ where the user cannot simply copy the examples that you
+ provide, but must instead include some information
+ themselves.</para>
+
+ <para><sgmltag>replaceable</sgmltag> is designed for this
+ eventuality. Use it <emphasis>inside</emphasis> other
+ elements to indicate parts of that element's content that
+ the user must replace.</para>
+
<example>
<title><sgmltag>replaceable</sgmltag></title>
-
+
<para>Use:</para>
-
+
<programlisting><![ CDATA [<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
<para>Appearance:</para>
-
+
<informalexample>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>
-
- <para><sgmltag>replaceable</sgmltag> can be used in many different
- elements, including <sgmltag>literal</sgmltag>. This example also
- shows that <sgmltag>replaceable</sgmltag> should only be wrapped
- around the content that the user <emphasis>is</emphasis> meant to
- provide. The other content should be left alone.</para>
-
+
+ <para><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
@@ -2232,40 +2332,41 @@ This is the file called 'foo2'</screen>
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>
+ <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>
+ <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>
+ <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>
+ <example>
+ <title><sgmltag>errorname</sgmltag></title>
- <para>Use:</para>
+ <para>Use:</para>
<programlisting><![ CDATA [
<screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
</programlisting>
- <para>Appearance:</para>
+ <para>Appearance:</para>
- <informalexample>
- <screen><errorname>Panic: cannot mount root</errorname></screen>
- </informalexample>
- </example>
+ <informalexample>
+ <screen><errorname>Panic: cannot mount root</errorname></screen>
+ </informalexample>
+ </example>
</sect3>
</sect2>
@@ -2273,100 +2374,106 @@ This is the file called 'foo2'</screen>
<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>Image support in the documentation is currently
+ extremely experimental. The mechanisms described here are
+ unlikely to change, but that is not guaranteed.</para>
<para>You will also need to install the
- <filename role="package">graphics/ImageMagick</filename> port, which is used to
- convert between the different image formats. This is a big port,
- and most of it is not required. However, while we are working on the
- <filename>Makefile</filename>s and other infrastructure it makes
- things easier. This port is <emphasis>not</emphasis> in the
- <filename role="package">textproc/docproj</filename> meta port, you must install it
- by hand.</para>
+ <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>
+ <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>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 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>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>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>
+ <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>
+ <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
+ <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>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>
+ <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>
+ <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>
+ <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>
+ <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>
@@ -2386,33 +2493,36 @@ This is the file called 'foo2'</screen>
<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>
+ <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>
+ <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>
+ <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>
@@ -2421,12 +2531,14 @@ This is the file called 'foo2'</screen>
<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
+ <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>…
@@ -2441,37 +2553,41 @@ 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>
+ <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
+ <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
+
+ <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, it is suggested to place those images in each
- chapter's subdirectory (<filename>chapter1/</filename>,
+ <filename>chapter3/chapter.sgml</filename>. If each chapter
+ has images associated with it, it is suggested to place
+ those images in each chapter's subdirectory
+ (<filename>chapter1/</filename>,
<filename>chapter2/</filename>, and
<filename>chapter3/</filename>).</para>
- <para>However, if you do this you must include the directory names in
- the <makevar>IMAGES</makevar> variable in the
- <filename>Makefile</filename>, <emphasis>and</emphasis> you must
- include the directory name in the <sgmltag>imagedata</sgmltag>
- element in your document.</para>
+ <para>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
+ <para>For example, if you have
+ <filename>chapter1/fig1.png</filename>, then
+ <filename>chapter1/chapter.sgml</filename> should
contain:</para>
<programlisting><mediaobject>
@@ -2482,7 +2598,7 @@ IMAGES+= fig3.png
…
</mediaobject></programlisting>
-
+
<calloutlist>
<callout arearefs="co-image-dir">
<para>The directory name must be included in the
@@ -2499,7 +2615,7 @@ IMAGES= chapter1/fig1.png
<para>Then everything should just work.</para>
</sect3>
</sect2>
-
+
<sect2>
<title>Links</title>
@@ -2511,23 +2627,24 @@ IMAGES= chapter1/fig1.png
<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>
+ 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>
+ <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
+ <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>
+ <para>Normally, you will only be linking to chapters or
+ sections, so you would add the <literal>id</literal>
+ attribute to these elements.</para>
<example>
- <title>Attribute <literal>id</literal> on Chapters and Sections</title>
+ <title>Attribute <literal>id</literal> on Chapters and
+ Sections</title>
<programlisting><![ CDATA [<chapter id="chapter1">
<title>Introduction</title>
@@ -2542,18 +2659,20 @@ IMAGES= chapter1/fig1.png
</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>
+ <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>
@@ -2562,112 +2681,120 @@ IMAGES= chapter1/fig1.png
<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>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>
-
+ 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>
-
+ <para>Assume that this fragment appears somewhere in a
+ document that includes the <literal>id</literal>
+ example:</para>
+
<programlisting><![ CDATA [<para>More information can be found
in <xref linkend="chapter1">.</para>
<para>More specific information can be found
in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
- <para>The text of the link will be generated automatically, and will
- look like (<emphasis>emphasized</emphasis> text indicates the text
- that will be the link):</para>
+ <para>The text of the link will be generated automatically,
+ and will look like (<emphasis>emphasized</emphasis> text
+ indicates the text that will be the link):</para>
<blockquote>
<para>More information can be found in <emphasis>Chapter
One</emphasis>.</para>
- <para>More specific information can be found in <emphasis>the
- section called Sub-Sect 1</emphasis>.</para>
+ <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>
+
+ <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>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>
+ <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>
+ <para>Assume that this fragment appears somewhere in a
+ document that includes the <literal>id</literal>
+ example.</para>
<programlisting><![ CDATA [<para>More information can be found in
<link linkend="chapter1">the first chapter</link>.</para>
<para>More specific information can be found in
<link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting>
-
+
<para>This will generate the following
- (<emphasis>emphasized</emphasis> text indicates the text that will
- be the link):</para>
-
+ (<emphasis>emphasized</emphasis> text indicates the text
+ that will be the link):</para>
+
<blockquote>
<para>More information can be found in <emphasis>the first
chapter</emphasis>.</para>
-
+
<para>More specific information can be found in
<emphasis>this</emphasis> section.</para>
</blockquote>
</example>
-
+
<note>
<para>That last one is a bad example. Never use words like
- <quote>this</quote> or <quote>here</quote> as the source for the
- link. The reader will need to hunt around the surrounding context
- to see where the link is actually taking them.</para>
+ <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>
+ <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>
+ <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>
@@ -2680,9 +2807,9 @@ IMAGES= chapter1/fig1.png
<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>
+ <para>Of course, you could stop reading this document and go
+ to the <ulink url="&url.base;/index.html">FreeBSD home
+ page</ulink> instead.</para>
</example>
</sect3>
</sect2>