aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml344
1 files changed, 195 insertions, 149 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 2d74c89f07..71959ba6a4 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
@@ -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>