aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-09-03 17:16:06 +0000
committerNik Clayton <nik@FreeBSD.org>1999-09-03 17:16:06 +0000
commit97fe3901a977c8a3195862a2c2b6b5053632d0b0 (patch)
tree19cd1691b2910b6cce1baef2912fa7b6021901b4 /en_US.ISO_8859-1/books
parentf4ca19b7a8ce1f5557db03c4ac0f795712692109 (diff)
downloaddoc-97fe3901a977c8a3195862a2c2b6b5053632d0b0.tar.gz
doc-97fe3901a977c8a3195862a2c2b6b5053632d0b0.zip
Miscellaneous small changes. Includes reformatting white space in some
of the example HTML and DocBook fragments, which are significant. Explain where to find the FreeBSD DTD that extends DocBook. Add a section explaining about books and articles, and the differences between them. Added an example of <procedure>. Be consistent with the white space inside <programlisting>. Make sure that content starts immediately after the opening tag. Shouldn't make a great deal of difference, but we should practice what we preach. Remove the information about <informalexample>, as it seems to be redundant, and we don't use it anymore. Correct an error ("]]", should be "]") in the example of including the manual page reference entities.
Notes
Notes: svn path=/head/; revision=5508
Diffstat (limited to 'en_US.ISO_8859-1/books')
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml344
1 files changed, 195 insertions, 149 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 2d74c89f07..71959ba6a4 100644
--- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- $Id: chapter.sgml,v 1.7 1999-08-30 11:53:03 jhb Exp $
+ $Id: chapter.sgml,v 1.8 1999-09-03 17:16:06 nik Exp $
-->
<chapter id="sgml-markup">
@@ -93,8 +93,7 @@
<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>
+ <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</sect2>
<sect2>
@@ -114,8 +113,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<example>
<title>Normal HTML document structure</title>
- <programlisting>
-&lt;html>
+ <programlisting>&lt;html>
&lt;head>
&lt;title><replaceable>The document's title</replaceable>&lt;/title>
&lt;/head>
@@ -149,8 +147,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<h1>First section</h1>
+ <programlisting><![ CDATA [<h1>First section</h1>
<!-- Document introduction goes here -->
@@ -181,8 +178,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<h1>First section</h1>
+ <programlisting><![ CDATA [<h1>First section</h1>
<!-- Document introduction -->
@@ -203,8 +199,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>This is a paragraph. It can contain just about any
+ <programlisting><![ CDATA [<p>This is a paragraph. It can contain just about any
other element.</p>]]></programlisting>
</example>
</sect3>
@@ -220,8 +215,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>A small excerpt from the US Constitution;</p>
+ <programlisting><![ CDATA [<p>A small excerpt from the US Constitution;</p>
<blockquote>We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic
@@ -264,8 +258,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>An unordered list. Listitems will probably be
+ <programlisting><![ CDATA [<p>An unordered list. Listitems will probably be
preceeded by bullets.</p>
<ul>
@@ -297,8 +290,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<dl>
+ <programlisting><![ CDATA [<dl>
<dt>Term 1</dt>
<dd><p>Paragraph 1 of definition 1.</p></dd>
@@ -334,9 +326,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
message;</para>
- <programlisting>
-<![ CDATA [<pre>
- From: nik@FreeBSD.org
+ <programlisting><![ CDATA [<pre> From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
Subject: New documentation available
@@ -347,8 +337,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
Comments appreciated.
- N
-</pre>]]></programlisting>
+ N</pre>]]></programlisting>
</example>
</sect3>
@@ -376,8 +365,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>This is a simple 2x2 table.</p>
+ <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p>
<table>
<tr>
@@ -403,8 +391,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>One tall thin cell on the left, two short cells next to
+ <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to
it on the right.</p>
<table>
@@ -425,8 +412,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>One long cell on top, two short cells below it.</p>
+ <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p>
<table>
<tr>
@@ -447,8 +433,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
+ <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
cells merged in to one. The other cells are normal.</p>
<table>
@@ -461,7 +446,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<tr>
<!-- Because the large cell on the left merges in to
this row, the first <td> will occur on its
- right -->
+ right -->
<td>Middle right cell</td>
</tr>
@@ -498,8 +483,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p><em>This</em> has been emphasised, while
+ <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while
<strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
</example>
</sect3>
@@ -515,8 +499,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<example>
<title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
- <programlisting>
-<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
+ <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
in italics.</p>]]></programlisting>
</example>
</sect3>
@@ -533,8 +516,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>This document was originally written by
+ <programlisting><![ CDATA [<p>This document was originally written by
Nik Clayton, who can be reached by e-mail as
<tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
</example>
@@ -575,8 +557,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>The following fragments all do the same thing.</para>
- <programlisting>
-<![ CDATA [<p>This text is <small>slightly smaller</small>. But
+ <programlisting><![ CDATA [<p>This text is <small>slightly smaller</small>. But
this text is <big>slightly bigger</big>.</p>
<p>This text is <font size="-1">slightly smaller</font>. But
@@ -613,8 +594,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p>More information is available at the
+ <programlisting><![ CDATA [<p>More information is available at the
<a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
</example>
@@ -638,8 +618,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
+ <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
in other links with the name <tt>para1</tt>.</p>]]></programlisting>
</example>
@@ -653,8 +632,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<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
+ <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>
@@ -669,8 +647,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Assume that the <literal>para1</literal> example resides in
this document</para>
- <programlisting>
-<![ CDATA [<p>More information can be found in the
+ <programlisting><![ CDATA [<p>More information can be found in the
<a href="#para1">first paragraph</a> of this
document.</p>]]></programlisting>
</example>
@@ -725,6 +702,11 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
collaborating on a standard DocBook extension set, please get in
touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para>
</note>
+
+ <para>The FreeBSD extensions are not (currently) in the ports
+ collection. It is a part of the Documentation Project source
+ repository, and can be found in
+ <filename>doc/share/sgml/freebsd.dtd</filename>.</para>
</sect2>
<sect2>
@@ -734,18 +716,15 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
is;</para>
- <programlisting>
-PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
+ <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
</sect2>
-
- <sect2>
- <title>Sectional elements</title>
- <para>DocBook contains a number of elements for marking up the structure
- of a book.</para>
+ <sect2>
+ <title>Document structure</title>
- <para>Generally, the top level (first) element will be
- <sgmltag>book</sgmltag>.</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 organised into <sgmltag>chapter</sgmltag>s. This is a
mandatory requirement. There may be <sgmltag>part</sgmltag>s between
@@ -759,6 +738,27 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<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 organised 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 in to 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 in to several
+ chapters, possibly with appendices and similar content as well.</para>
+
+ <para>The <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD
+ tutorials</ulink> are all marked up as articles, while this
+ document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD
+ FAQ</ulink>, and the <ulink
+ url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are
+ all marked up as books.</para>
+
<sect3>
<title>Starting a book</title>
@@ -778,8 +778,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<!-- Can't put this in a marked section because of the
replaceable elements -->
- <programlisting>
-&lt;book>
+ <programlisting>&lt;book>
&lt;bookinfo>
&lt;title><replaceable>Your title here</replaceable>&lt;/title>
@@ -812,16 +811,66 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
</sect3>
<sect3>
+ <title>Starting an article</title>
+
+ <para>The content of the article is contained within the
+ <sgmltag>article</sgmltag> element. As well as containing
+ structural markup, this element can contain elements that include
+ additional information about the article. This is either
+ meta-information, used for reference purposes, or additional content
+ used to produce a title page.</para>
+
+ <para>This additional information should be contained within
+ <sgmltag>artheader</sgmltag>.</para>
+
+ <example>
+ <title>Boilerplate <sgmltag>article</sgmltag> with
+ <sgmltag>artheader</sgmltag></title>
+
+ <!-- Can't put this in a marked section because of the
+ replaceable elements -->
+ <programlisting>&lt;article>
+ &lt;artheader>
+ &lt;title><replaceable>Your title here</replaceable>&lt;/title>
+
+ &lt;author>
+ &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
+ &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
+ &lt;affiliation>
+ &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
+ &lt;/affiliation>
+ &lt;/author>
+
+ &lt;copyright>
+ &lt;year><replaceable>1998</replaceable>&lt;/year>
+ &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
+ &lt;/copyright>
+
+ &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
+
+ &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
+
+ &lt;abstract>
+ &lt;para><replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para>
+ &lt;/abstract>
+ &lt;/bookinfo>
+
+ &hellip;
+
+&lt;/article></programlisting>
+ </example>
+ </sect3>
+ <sect3>
<title>Indicating chapters</title>
<para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each
- chapter has a mandatory <sgmltag>title</sgmltag>.</para>
+ chapter has a mandatory <sgmltag>title</sgmltag>. Articles do not
+ contain chapters, they are reserved for books.</para>
<example>
<title>A simple chapter</title>
- <programlisting>
-<![ CDATA [<chapter>
+ <programlisting><![ CDATA [<chapter>
<title>The chapter's title</title>
...
@@ -835,8 +884,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<example>
<title>Empty chapters</title>
- <programlisting>
-<![ CDATA [<chapter>
+ <programlisting><![ CDATA [<chapter>
<title>This is an empty chapter</title>
<para></para>
@@ -847,10 +895,13 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<sect3>
<title>Sections below chapters</title>
- <para>Chapters can be broken up into sections, subsections, and so
- on. 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
@@ -860,8 +911,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<example>
<title>Sections in chapters</title>
- <programlisting>
-<![ CDATA [<chapter>
+ <programlisting><![ RCDATA [<chapter>
<title>A sample chapter</title>
<para>Some text in the chapter.</para>
@@ -869,7 +919,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<sect1>
<title>First section (1.1)</title>
- ...
+ &hellip;
</sect1>
<sect1>
@@ -881,18 +931,25 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<sect3>
<title>First sub-sub-section (1.2.1.1)</title>
- ...
+ &hellip;
</sect3>
</sect2>
<sect2>
<title>Second sub-section (1.2.2)</title>
- ...
+ &hellip;
</sect2>
</sect1>
</chapter>]]></programlisting>
</example>
+
+ <note>
+ <para>This example includes section numbers in the section titles.
+ You should not do this in your documents. Adding the section
+ numbers is carried out the by the stylesheets (of which more
+ later), and you do not need to manage them yourself.</para>
+ </note>
</sect3>
<sect3>
@@ -900,10 +957,10 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>You can introduce another layer of organisation between
<sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
- more <sgmltag>part</sgmltag>s.</para>
+ more <sgmltag>part</sgmltag>s. This can not be done in an
+ <sgmltag>article</sgmltag>.</para>
- <programlisting>
-<![ CDATA [<part>
+ <programlisting><![ CDATA [<part>
<title>Introduction</title>
<chapter>
@@ -948,8 +1005,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>This is a paragraph. It can contain just about any
+ <programlisting><![ CDATA [<para>This is a paragraph. It can contain just about any
other element.</para> ]]></programlisting>
<para>Appearance:</para>
@@ -974,8 +1030,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>A small excerpt from the US Constitution;</para>
+ <programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para>
<blockquote>
<title>Preamble to the Constitution of the United States</title>
@@ -1050,8 +1105,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<warning>
+ <programlisting><![ CDATA [<warning>
<para>Installing FreeBSD may make you want to delete Windows from your
harddisk.</para>
</warning>]]></programlisting>
@@ -1100,8 +1154,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<itemizedlist>
+ <programlisting><![ CDATA [<itemizedlist>
<listitem>
<para>This is the first itemized item.</para>
</listitem>
@@ -1119,7 +1172,21 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<listitem>
<para>This is the second ordered item.</para>
</listitem>
-</orderedlist>]]></programlisting>
+</orderedlist>
+
+<procedure>
+ <step>
+ <para>Do this.</para>
+ </step>
+
+ <step>
+ <para>Then do this.</para>
+ </step>
+
+ <step>
+ <para>And now do this.</para>
+ </step>
+</procedure>]]></programlisting>
<para>Appearance:</para>
@@ -1143,6 +1210,22 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
</listitem>
</orderedlist>
</example>
+
+ <!-- Can't have <procedure> inside <example>, so this is a cheat -->
+
+ <procedure>
+ <step>
+ <para>Do this.</para>
+ </step>
+
+ <step>
+ <para>Then do this.</para>
+ </step>
+
+ <step>
+ <para>And now do this.</para>
+ </step>
+ </procedure>
</sect3>
<sect3>
@@ -1154,21 +1237,20 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>White space and line breaks within
<sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
- significant. In particular, this means that the closing tag should
- appear on the same line as the last line of the output, otherwise a
- spurious blank line will 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
+ <programlisting><![ CDATA[<para>When you have finished, your program should look like
this;</para>
-<programlisting>
-#include &lt;stdio.h&gt;
+<programlisting>#include &lt;stdio.h&gt;
int
main(void)
@@ -1185,8 +1267,7 @@ main(void)
<para>When you have finished, your program should look like
this;</para>
- <programlisting>
-#include &lt;stdio.h&gt;
+ <programlisting>#include &lt;stdio.h&gt;
int
main(void)
@@ -1234,8 +1315,7 @@ main(void)
<para>Use:</para>
- <programlisting>
-<![ CDATA [<informaltable>
+ <programlisting><![ CDATA [<informaltable>
<tgroup cols="2">
<thead>
<row>
@@ -1333,19 +1413,6 @@ main(void)
<variablelist>
<varlistentry>
- <term><sgmltag>informalexample</sgmltag></term>
-
- <listitem>
- <para>Most of the time these examples will occur
- &ldquo;mid-flow&rdquo; as it were, and you won't need to put a
- title on them. So, most of the time, the outermost element
- will be <sgmltag>informalexample</sgmltag>. For those times
- when you do need to include a title on the example, use
- <sgmltag>example</sgmltag>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><sgmltag>screen</sgmltag></term>
<listitem>
@@ -1397,15 +1464,12 @@ main(void)
</variablelist>
<example>
- <title><sgmltag>informalexample</sgmltag>,
- <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
+ <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
<sgmltag>userinput</sgmltag></title>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<informalexample>
- <screen>&prompt.user; <userinput>ls -1</userinput>
+ <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
@@ -1414,12 +1478,10 @@ foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
-This is the file called 'foo2'</screen>
-</informalexample>]]></programlisting>
+This is the file called 'foo2'</screen>]]></programlisting>
- <para>Appearance:</para>
+ <para>Appearance:</para>
- <informalexample>
<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
@@ -1430,7 +1492,6 @@ foo2
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>
- </informalexample>
</example>
<note>
@@ -1466,8 +1527,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
+ <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
<para>Appearance:</para>
@@ -1526,7 +1586,7 @@ This is the file called 'foo2'</screen>
&hellip;
-]]&gt;</programlisting>
+]&gt;</programlisting>
<para>Use <sgmltag>command</sgmltag> when you want to include a
command name &ldquo;in-line&rdquo; but present it as something the
@@ -1543,8 +1603,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para><application>Sendmail</application> is the most
+ <programlisting><![ CDATA [<para><application>Sendmail</application> is the most
widely used Unix mail application.</para>
<para><application>Sendmail</application> includes the
@@ -1603,8 +1662,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>The SGML source for the Handbook in English can be
+ <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
found in <filename>/usr/doc/en/handbook/</filename>. The first
file is called <filename>handbook.sgml</filename> in that
directory. You should also see a <filename>Makefile</filename>
@@ -1645,8 +1703,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para><devicename>sio</devicename> is used for serial
+ <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial
communication in FreeBSD. <devicename>sio</devicename> manifests
through a number of entries in <filename>/dev</filename>, including
<filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
@@ -1761,8 +1818,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>The local machine can always be referred to by the
+ <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>
@@ -1823,8 +1879,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>To carry out most system administration functions you
+ <programlisting><![ CDATA [<para>To carry out most system administration functions you
will need to be <username>root</username>.</para>]]></programlisting>
<para>Appearance:</para>
@@ -1861,8 +1916,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>Two common targets in a <filename>Makefile</filename>
+ <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename>
are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
@@ -1912,8 +1966,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel
+ <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>
@@ -1945,8 +1998,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<informalexample>
+ <programlisting><![ CDATA [<informalexample>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>]]></programlisting>
@@ -1964,8 +2016,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal>
+ <programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal>
line in the kernel configuration file determines the size of many system
tables, and is a rough guide to how many simultaneous logins the system will
support.</para>
@@ -2015,8 +2066,7 @@ This is the file called 'foo2'</screen>
<example>
<title><literal>id on chapters and sections</literal></title>
- <programlisting>
-<![ CDATA [<chapter id="chapter1">
+ <programlisting><![ CDATA [<chapter id="chapter1">
<title>Introduction</title>
<para>This is the introduction. It contains a subsection,
@@ -2045,8 +2095,7 @@ This is the file called 'foo2'</screen>
<example>
<title><sgmltag>anchor</sgmltag></title>
- <programlisting>
-<![ CDATA [<para>This paragraph has an embedded
+ <programlisting><![ CDATA [<para>This paragraph has an embedded
<anchor id="para1">link target in it. It won't show up in
the document.</para>]]></programlisting>
</example>
@@ -2071,8 +2120,7 @@ This is the file called 'foo2'</screen>
<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
+ <programlisting><![ CDATA [<para>More information can be found
in <xref linkend="chapter1">.</para>
<para>More specific information can be found
@@ -2113,8 +2161,7 @@ This is the file called 'foo2'</screen>
<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
+ <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
@@ -2164,8 +2211,7 @@ This is the file called 'foo2'</screen>
<para>Use:</para>
- <programlisting>
-<![ CDATA [<para>Of course, you could stop reading this document and
+ <programlisting><![ CDATA [<para>Of course, you could stop reading this document and
go to the <ulink url="http://www.FreeBSD.org/">FreeBSD
home page</ulink> instead.</para>]]></programlisting>