svn commit: r42199 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup
Warren Block
wblock at FreeBSD.org
Tue Jul 9 05:34:53 UTC 2013
Author: wblock
Date: Tue Jul 9 05:34:52 2013
New Revision: 42199
URL: http://svnweb.freebsd.org/changeset/doc/42199
Log:
Clarity improvements, convert the rest of examples using CDATA to
<sgmltag>.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Jul 9 00:53:36 2013 (r42198)
+++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Jul 9 05:34:52 2013 (r42199)
@@ -195,33 +195,33 @@
<!-- Cannot put this in a marked section because of the
replaceable elements -->
- <programlisting><book>
- <bookinfo>
- <title><replaceable>Your Title Here</replaceable></title>
-
- <author>
- <firstname><replaceable>Your first name</replaceable></firstname>
- <surname><replaceable>Your surname</replaceable></surname>
- <affiliation>
- <address><email><replaceable>Your email address</replaceable></email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year><replaceable>1998</replaceable></year>
- <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
- </copyright>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <abstract>
- <para><replaceable>Include an abstract of the book's contents here.</replaceable></para>
- </abstract>
- </bookinfo>
+ <programlisting><sgmltag class="starttag">book</sgmltag>
+ <sgmltag class="starttag">bookinfo</sgmltag>
+ <sgmltag class="starttag">title</sgmltag><replaceable>Your Title Here</replaceable><sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">author</sgmltag>
+ <sgmltag class="starttag">firstname</sgmltag><replaceable>Your first name</replaceable><sgmltag class="endtag">firstname</sgmltag>
+ <sgmltag class="starttag">surname</sgmltag><replaceable>Your surname</replaceable><sgmltag class="endtag">surname</sgmltag>
+ <sgmltag class="starttag">affiliation</sgmltag>
+ <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag><replaceable>Your email address</replaceable><sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag>
+ <sgmltag class="endtag">affiliation</sgmltag>
+ <sgmltag class="endtag">author</sgmltag>
+
+ <sgmltag class="starttag">copyright</sgmltag>
+ <sgmltag class="starttag">year</sgmltag><replaceable>1998</replaceable><sgmltag class="endtag">year</sgmltag>
+ <sgmltag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</sgmltag><replaceable>Your name</replaceable><sgmltag class="endtag">holder</sgmltag>
+ <sgmltag class="endtag">copyright</sgmltag>
+
+ <sgmltag class="starttag">releaseinfo</sgmltag>$&os;$<sgmltag class="endtag">releaseinfo</sgmltag>
+
+ <sgmltag class="starttag">abstract</sgmltag>
+ <sgmltag class="starttag">para</sgmltag><replaceable>Include an abstract of the book's contents here.</replaceable><sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">abstract</sgmltag>
+ <sgmltag class="endtag">bookinfo</sgmltag>
…
-</book></programlisting>
+<sgmltag class="endtag">book</sgmltag></programlisting>
</example>
</sect2>
@@ -245,33 +245,33 @@
<!-- Cannot put this in a marked section because of the
replaceable elements -->
- <programlisting><article>
- <articleinfo>
- <title><replaceable>Your title here</replaceable></title>
-
- <author>
- <firstname><replaceable>Your first name</replaceable></firstname>
- <surname><replaceable>Your surname</replaceable></surname>
- <affiliation>
- <address><email><replaceable>Your email address</replaceable></email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year><replaceable>1998</replaceable></year>
- <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
- </copyright>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <abstract>
- <para><replaceable>Include an abstract of the article's contents here.</replaceable></para>
- </abstract>
- </articleinfo>
+ <programlisting><sgmltag class="starttag">article</sgmltag>
+ <sgmltag class="starttag">articleinfo</sgmltag>
+ <sgmltag class="starttag">title</sgmltag><replaceable>Your title here</replaceable><sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">author</sgmltag>
+ <sgmltag class="starttag">firstname</sgmltag><replaceable>Your first name</replaceable><sgmltag class="endtag">firstname</sgmltag>
+ <sgmltag class="starttag">surname</sgmltag><replaceable>Your surname</replaceable><sgmltag class="endtag">surname</sgmltag>
+ <sgmltag class="starttag">affiliation</sgmltag>
+ <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag><replaceable>Your email address</replaceable><sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag>
+ <sgmltag class="endtag">affiliation</sgmltag>
+ <sgmltag class="endtag">author</sgmltag>
+
+ <sgmltag class="starttag">copyright</sgmltag>
+ <sgmltag class="starttag">year</sgmltag><replaceable>1998</replaceable><sgmltag class="endtag">year</sgmltag>
+ <sgmltag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</sgmltag><replaceable>Your name</replaceable><sgmltag class="endtag">holder</sgmltag>
+ <sgmltag class="endtag">copyright</sgmltag>
+
+ <sgmltag class="starttag">releaseinfo</sgmltag>$&os;$<sgmltag class="endtag">releaseinfo</sgmltag>
+
+ <sgmltag class="starttag">abstract</sgmltag>
+ <sgmltag class="starttag">para</sgmltag><replaceable>Include an abstract of the article's contents here.</replaceable><sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">abstract</sgmltag>
+ <sgmltag class="endtag">articleinfo</sgmltag>
…
-</article></programlisting>
+<sgmltag class="endtag">article</sgmltag></programlisting>
</example>
</sect2>
@@ -286,11 +286,11 @@
<example>
<title>A Simple Chapter</title>
- <programlisting><![CDATA[<chapter>
- <title>The Chapter's Title</title>
+ <programlisting><sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>The Chapter's Title<sgmltag class="endtag">title</sgmltag>
...
-</chapter>]]></programlisting>
+<sgmltag class="endtag">chapter</sgmltag></programlisting>
</example>
<para>A chapter cannot be empty; it must contain elements in
@@ -301,11 +301,11 @@
<example>
<title>Empty Chapters</title>
- <programlisting><![CDATA[<chapter>
- <title>This is An Empty Chapter</title>
+ <programlisting><sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>This is An Empty Chapter<sgmltag class="endtag">title</sgmltag>
- <para></para>
-</chapter>]]></programlisting>
+ <sgmltag class="starttag">para</sgmltag><sgmltag class="endtag">para</sgmltag>
+<sgmltag class="endtag">chapter</sgmltag></programlisting>
</example>
</sect2>
@@ -330,45 +330,66 @@
<example>
<title>Sections in Chapters</title>
- <programlisting><![CDATA[<chapter>
- <title>A Sample Chapter</title>
+ <programlisting><sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>A Sample Chapter<sgmltag class="endtag">title</sgmltag>
- <para>Some text in the chapter.</para>
+ <sgmltag class="starttag">para</sgmltag>Some text in the chapter.<sgmltag class="endtag">para</sgmltag>
- <sect1>
- <title>First Section (1.1)</title>
+ <sgmltag class="starttag">sect1</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>First Section<sgmltag class="endtag">title</sgmltag>
…
- </sect1>
+ <sgmltag class="endtag">sect1</sgmltag>
- <sect1>
- <title>Second Section (1.2)</title>
+ <sgmltag class="starttag">sect1</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>Second Section<sgmltag class="endtag">title</sgmltag>
- <sect2>
- <title>First Sub-Section (1.2.1)</title>
+ <sgmltag class="starttag">sect2</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>First Sub-Section<sgmltag class="endtag">title</sgmltag>
- <sect3>
- <title>First Sub-Sub-Section (1.2.1.1)</title>
+ <sgmltag class="starttag">sect3</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>First Sub-Sub-Section<sgmltag class="endtag">title</sgmltag>
- …
- </sect3>
- </sect2>
+ …
+ <sgmltag class="endtag">sect3</sgmltag>
+ <sgmltag class="endtag">sect2</sgmltag>
- <sect2>
- <title>Second Sub-Section (1.2.2)</title>
+ <sgmltag class="starttag">sect2</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>Second Sub-Section (1.2.2)<sgmltag class="endtag">title</sgmltag>
…
- </sect2>
- </sect1>
-</chapter>]]></programlisting>
+ <sgmltag class="endtag">sect2</sgmltag>
+ <sgmltag class="endtag">sect1</sgmltag>
+<sgmltag class="endtag">chapter</sgmltag></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>Section numbers are automatically generated and
+ prepended to titles when the document is rendered to an
+ output format. The generated section numbers and titles
+ from the example above will be:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>1.1. First Section</para>
+ </listitem>
+
+ <listitem>
+ <para>1.2. Second Section</para>
+ </listitem>
+
+ <listitem>
+ <para>1.2.1. First Sub-Section</para>
+ </listitem>
+
+ <listitem>
+ <para>1.2.1.1. First Sub-Sub-Section</para>
+ </listitem>
+
+ <listitem>
+ <para>1.2.2. Second Sub-Section</para>
+ </listitem>
+ </itemizedlist>
</note>
</sect2>
@@ -382,27 +403,27 @@
<sgmltag>part</sgmltag>s. This cannot be done in an
<sgmltag>article</sgmltag>.</para>
- <programlisting><![CDATA[<part>
- <title>Introduction</title>
+ <programlisting><sgmltag class="starttag">part</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag>
- <chapter>
- <title>Overview</title>
+ <sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>Overview<sgmltag class="endtag">title</sgmltag>
...
- </chapter>
+ <sgmltag class="endtag">chapter</sgmltag>
- <chapter>
- <title>What is FreeBSD?</title>
+ <sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>What is FreeBSD?<sgmltag class="endtag">title</sgmltag>
...
- </chapter>
+ <sgmltag class="endtag">chapter</sgmltag>
- <chapter>
- <title>History</title>
+ <sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>History<sgmltag class="endtag">title</sgmltag>
...
- </chapter>
-</part>]]></programlisting>
+ <sgmltag class="endtag">chapter</sgmltag>
+<sgmltag class="endtag">part</sgmltag></programlisting>
</sect2>
</sect1>
@@ -428,8 +449,8 @@
<para>Usage:</para>
- <programlisting><![CDATA[<para>This is a paragraph. It can contain just about any
- other element.</para> ]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>This is a paragraph. It can contain just about any
+ other element.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -454,20 +475,20 @@
<para>Usage:</para>
- <programlisting><![CDATA[<para>A small excerpt from the US Constitution:</para>
+ <programlisting><sgmltag class="starttag">para</sgmltag>A small excerpt from the US Constitution:<sgmltag class="endtag">para</sgmltag>
-<blockquote>
- <title>Preamble to the Constitution of the United States</title>
+<sgmltag class="starttag">blockquote</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>Preamble to the Constitution of the United States<sgmltag class="endtag">title</sgmltag>
- <attribution>Copied from a web site somewhere</attribution>
+ <sgmltag class="starttag">attribution</sgmltag>Copied from a web site somewhere<sgmltag class="endtag">attribution</sgmltag>
- <para>We the People of the United States, in Order to form a more
+ <sgmltag class="starttag">para</sgmltag>We the People of the United States, in Order to form a more
perfect Union, establish Justice, insure domestic Tranquility,
provide for the common defence, promote the general Welfare, and
secure the Blessings of Liberty to ourselves and our Posterity, do
ordain and establish this Constitution for the United States of
- America.</para>
-</blockquote>]]></programlisting>
+ America.<sgmltag class="endtag">para</sgmltag>
+<sgmltag class="endtag">blockquote</sgmltag></programlisting>
<para>Appearance:</para>
@@ -537,10 +558,10 @@
<para>Usage:</para>
- <programlisting><![CDATA[<warning>
- <para>Installing FreeBSD may make you want to delete Windows from your
- hard disk.</para>
-</warning>]]></programlisting>
+ <programlisting><sgmltag class="starttag">warning</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>Installing FreeBSD may make you want to delete Windows from your
+ hard disk.<sgmltag class="endtag">para</sgmltag>
+<sgmltag class="endtag">warning</sgmltag></programlisting>
</example>
<para>Appearance:</para>
@@ -588,39 +609,39 @@
<para>Usage:</para>
- <programlisting><![CDATA[<itemizedlist>
- <listitem>
- <para>This is the first itemized item.</para>
- </listitem>
-
- <listitem>
- <para>This is the second itemized item.</para>
- </listitem>
-</itemizedlist>
-
-<orderedlist>
- <listitem>
- <para>This is the first ordered item.</para>
- </listitem>
-
- <listitem>
- <para>This is the second ordered item.</para>
- </listitem>
-</orderedlist>
-
-<procedure>
- <step>
- <para>Do this.</para>
- </step>
-
- <step>
- <para>Then do this.</para>
- </step>
-
- <step>
- <para>And now do this.</para>
- </step>
-</procedure>]]></programlisting>
+ <programlisting><sgmltag class="starttag">itemizedlist</sgmltag>
+ <sgmltag class="starttag">listitem</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>This is the first itemized item.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">listitem</sgmltag>
+
+ <sgmltag class="starttag">listitem</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>This is the second itemized item.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">listitem</sgmltag>
+<sgmltag class="endtag">itemizedlist</sgmltag>
+
+<sgmltag class="starttag">orderedlist</sgmltag>
+ <sgmltag class="starttag">listitem</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>This is the first ordered item.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">listitem</sgmltag>
+
+ <sgmltag class="starttag">listitem</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>This is the second ordered item.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">listitem</sgmltag>
+<sgmltag class="endtag">orderedlist</sgmltag>
+
+<sgmltag class="starttag">procedure</sgmltag>
+ <sgmltag class="starttag">step</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>Do this.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">step</sgmltag>
+
+ <sgmltag class="starttag">step</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>Then do this.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">step</sgmltag>
+
+ <sgmltag class="starttag">step</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>And now do this.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">step</sgmltag>
+<sgmltag class="endtag">procedure</sgmltag></programlisting>
<para>Appearance:</para>
@@ -683,16 +704,16 @@
<para>Usage:</para>
- <programlisting><![CDATA[<para>When finished, the program will look like
- this:</para>
+ <programlisting><sgmltag class="starttag">para</sgmltag>When finished, the program will look like
+ this:<sgmltag class="endtag">para</sgmltag>
-<programlisting>#include <stdio.h>
+<sgmltag class="starttag">programlisting</sgmltag>#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
-}</programlisting>]]></programlisting>
+}<sgmltag class="endtag">programlisting</sgmltag></programlisting>
<para>Notice how the angle brackets in the
<literal>#include</literal> line need to be referenced by
@@ -715,49 +736,46 @@ main(void)
<sect2 id="docbook-markup-callouts">
<title>Callouts</title>
- <para>A callout is a mechanism for referring back to an
- earlier piece of text or specific position within an earlier
- example without linking to it within the text.</para>
-
- <para>To do this, mark areas of interest in the example
- (<sgmltag>programlisting</sgmltag>,
- <sgmltag>literallayout</sgmltag>, or whatever) with the
+ <para>A callout is a visual marker for referring to a
+ piece of text or specific position within an
+ example.</para>
+
+ <para>Callouts are marked with the
<sgmltag>co</sgmltag> element. Each element must have a
unique <literal>id</literal> assigned to it. After the
- example include a <sgmltag>calloutlist</sgmltag> that refers
- back to the example and provides additional
- commentary.</para>
+ example, include a <sgmltag>calloutlist</sgmltag> that describes
+ each callout.</para>
<example>
<title><sgmltag>co</sgmltag> and
<sgmltag>calloutlist</sgmltag></title>
- <programlisting><![CDATA[<para>When finished, the program will look like
- this:</para>
+ <programlisting><sgmltag class="starttag">para</sgmltag>When finished, the program will look like
+ this:<sgmltag class="endtag">para</sgmltag>
-<programlisting>#include <stdio.h> <co id="co-ex-include"/>
+<sgmltag class="starttag">programlisting</sgmltag>#include <stdio.h> <sgmltag class="emptytag">co id="co-ex-include"</sgmltag>
-int <co id="co-ex-return"/>
+int <sgmltag class="emptytag">co id="co-ex-return"</sgmltag>
main(void)
{
- printf("hello, world\n"); <co id="co-ex-printf"/>
-}</programlisting>
+ printf("hello, world\n"); <sgmltag class="emptytag">co id="co-ex-printf"</sgmltag>
+}<sgmltag class="endtag">programlisting</sgmltag>
-<calloutlist>
- <callout arearefs="co-ex-include">
- <para>Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para>Specifies that <function>main()</function> returns an
- int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para>The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard output.</para>
- </callout>
-</calloutlist>]]></programlisting>
+<sgmltag class="starttag">calloutlist</sgmltag>
+ <sgmltag class="starttag">callout arearefs="co-ex-include"</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>Includes the standard IO header file.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">callout</sgmltag>
+
+ <sgmltag class="starttag">callout arearefs="co-ex-return"</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>Specifies that <sgmltag class="starttag">function</sgmltag>main()<sgmltag class="endtag">function</sgmltag> returns an
+ int.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">callout</sgmltag>
+
+ <sgmltag class="starttag">callout arearefs="co-ex-printf"</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">function</sgmltag>printf()<sgmltag class="endtag">function</sgmltag> call that writes
+ <sgmltag class="starttag">literal</sgmltag>hello, world<sgmltag class="endtag">literal</sgmltag> to standard output.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">callout</sgmltag>
+<sgmltag class="endtag">calloutlist</sgmltag></programlisting>
<para>Appearance:</para>
@@ -820,28 +838,28 @@ main(void)
<para>Usage:</para>
- <programlisting><![CDATA[<informaltable pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>This is Column Head 1</entry>
- <entry>This is Column Head 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Row 1, column 1</entry>
- <entry>Row 1, column 2</entry>
- </row>
-
- <row>
- <entry>Row 2, column 1</entry>
- <entry>Row 2, column 2</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>]]></programlisting>
+ <programlisting><sgmltag class="starttag">informaltable pgwide="1"</sgmltag>
+ <sgmltag class="starttag">tgroup cols="2"</sgmltag>
+ <sgmltag class="starttag">thead</sgmltag>
+ <sgmltag class="starttag">row</sgmltag>
+ <sgmltag class="starttag">entry</sgmltag>This is Column Head 1<sgmltag class="endtag">entry</sgmltag>
+ <sgmltag class="starttag">entry</sgmltag>This is Column Head 2<sgmltag class="endtag">entry</sgmltag>
+ <sgmltag class="endtag">row</sgmltag>
+ <sgmltag class="endtag">thead</sgmltag>
+
+ <sgmltag class="starttag">tbody</sgmltag>
+ <sgmltag class="starttag">row</sgmltag>
+ <sgmltag class="starttag">entry</sgmltag>Row 1, column 1<sgmltag class="endtag">entry</sgmltag>
+ <sgmltag class="starttag">entry</sgmltag>Row 1, column 2<sgmltag class="endtag">entry</sgmltag>
+ <sgmltag class="endtag">row</sgmltag>
+
+ <sgmltag class="starttag">row</sgmltag>
+ <sgmltag class="starttag">entry</sgmltag>Row 2, column 1<sgmltag class="endtag">entry</sgmltag>
+ <sgmltag class="starttag">entry</sgmltag>Row 2, column 2<sgmltag class="endtag">entry</sgmltag>
+ <sgmltag class="endtag">row</sgmltag>
+ <sgmltag class="endtag">tbody</sgmltag>
+ <sgmltag class="endtag">tgroup</sgmltag>
+<sgmltag class="endtag">informaltable</sgmltag></programlisting>
<para>Appearance:</para>
@@ -878,7 +896,7 @@ main(void)
<para>Table borders can be suppressed by setting the
<literal>frame</literal> attribute to <literal>none</literal>
in the <sgmltag>informaltable</sgmltag> element. For example,
- <literal><informaltable frame="none"></literal>.</para>
+ <literal><sgmltag class="starttag">informaltable frame="none"</sgmltag></literal>.</para>
<example>
<title>Tables Where <literal>frame="none"</literal></title>
@@ -981,16 +999,16 @@ main(void)
<para>Usage:</para>
- <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput>
+ <programlisting><sgmltag class="starttag">screen</sgmltag>&prompt.user; <sgmltag class="starttag">userinput</sgmltag>ls -1<sgmltag class="endtag">userinput</sgmltag>
foo1
foo2
foo3
-&prompt.user; <userinput>ls -1 | grep foo2</userinput>
+&prompt.user; <sgmltag class="starttag">userinput</sgmltag>ls -1 | grep foo2<sgmltag class="endtag">userinput</sgmltag>
foo2
-&prompt.user; <userinput>su</userinput>
-<prompt>Password: </prompt>
-&prompt.root; <userinput>cat foo2</userinput>
-This is the file called 'foo2'</screen>]]></programlisting>
+&prompt.user; <sgmltag class="starttag">userinput</sgmltag>su<sgmltag class="endtag">userinput</sgmltag>
+<sgmltag class="starttag">prompt</sgmltag>Password: <sgmltag class="endtag">prompt</sgmltag>
+&prompt.root; <sgmltag class="starttag">userinput</sgmltag>cat foo2<sgmltag class="endtag">userinput</sgmltag>
+This is the file called 'foo2'<sgmltag class="endtag">screen</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1040,8 +1058,8 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>FreeBSD is without doubt <emphasis>the</emphasis>
- premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>FreeBSD is without doubt <sgmltag class="starttag">emphasis</sgmltag>the<sgmltag class="endtag">emphasis</sgmltag>
+ premiere Unix like operating system for the Intel architecture.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1065,9 +1083,9 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the
- <quote>boundary between local and public administration</quote>,
- as RFC 1535 calls it.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>However, make sure that the search does not go beyond the
+ <sgmltag class="starttag">quote</sgmltag>boundary between local and public administration<sgmltag class="endtag">quote</sgmltag>,
+ as RFC 1535 calls it.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1103,18 +1121,18 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>To switch to the second virtual terminal, press
- <keycombo action="simul"><keycap>Alt</keycap>
- <keycap>F1</keycap></keycombo>.</para>
-
-<para>To exit <command>vi</command> without saving changes, type
- <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
- <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
-
-<para>My window manager is configured so that
- <keycombo action="simul"><keycap>Alt</keycap>
- <mousebutton>right</mousebutton>
- </keycombo> mouse button is used to move windows.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>To switch to the second virtual terminal, press
+ <sgmltag class="starttag">keycombo action="simul"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Alt<sgmltag class="endtag">keycap</sgmltag>
+ <sgmltag class="starttag">keycap</sgmltag>F1<sgmltag class="endtag">keycap</sgmltag><sgmltag class="endtag">keycombo</sgmltag>.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">para</sgmltag>To exit <sgmltag class="starttag">command</sgmltag>vi<sgmltag class="endtag">command</sgmltag> without saving changes, type
+ <sgmltag class="starttag">keycombo action="seq"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Esc<sgmltag class="endtag">keycap</sgmltag><sgmltag class="starttag">keycap</sgmltag>:<sgmltag class="endtag">keycap</sgmltag>
+ <sgmltag class="starttag">keycap</sgmltag>q<sgmltag class="endtag">keycap</sgmltag><sgmltag class="starttag">keycap</sgmltag>!<sgmltag class="endtag">keycap</sgmltag><sgmltag class="endtag">keycombo</sgmltag>.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">para</sgmltag>My window manager is configured so that
+ <sgmltag class="starttag">keycombo action="simul"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Alt<sgmltag class="endtag">keycap</sgmltag>
+ <sgmltag class="starttag">mousebutton</sgmltag>right<sgmltag class="endtag">mousebutton</sgmltag>
+ <sgmltag class="endtag">keycombo</sgmltag> mouse button is used to move windows.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1215,22 +1233,22 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para><application>Sendmail</application> is the most
- widely used Unix mail application.</para>
+ <programlisting><sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">application</sgmltag>Sendmail<sgmltag class="endtag">application</sgmltag> is the most
+ widely used Unix mail application.<sgmltag class="starttag">para</sgmltag>
-<para><application>Sendmail</application> includes the
- <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
- programs.</para>
-
-<para>One of the command line parameters to <citerefentry>
- <refentrytitle>sendmail</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>, <option>-bp</option>, will display the current
+<sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">application</sgmltag>Sendmail<sgmltag class="endtag">application</sgmltag> includes the
+ <sgmltag class="starttag">citerefentry</sgmltag>
+ <sgmltag class="starttag">refentrytitle</sgmltag>sendmail<sgmltag class="endtag">refentrytitle</sgmltag>
+ <sgmltag class="starttag">manvolnum</sgmltag>8<sgmltag class="endtag">manvolnum</sgmltag>
+ <sgmltag class="endtag">citerefentry</sgmltag>, &man.mailq.1;, and &man.newaliases.1;
+ programs.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">para</sgmltag>One of the command line parameters to <sgmltag class="starttag">citerefentry</sgmltag>
+ <sgmltag class="starttag">refentrytitle</sgmltag>sendmail<sgmltag class="endtag">refentrytitle</sgmltag>
+ <sgmltag class="starttag">manvolnum</sgmltag>8<sgmltag class="endtag">manvolnum</sgmltag>
+ <sgmltag class="endtag">citerefentry</sgmltag>, <sgmltag class="starttag">option</sgmltag>-bp<sgmltag class="endtag">option</sgmltag>, will display the current
status of messages in the mail queue. Check this on the command
- line by running <command>sendmail -bp</command>.</para>]]></programlisting>
+ line by running <sgmltag class="starttag">command</sgmltag>sendmail -bp<sgmltag class="endtag">command</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1272,12 +1290,12 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>The XML source for the Handbook in English is
- found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first
- file is called <filename>book.xml</filename> in that
- directory. There is also a <filename>Makefile</filename>
- and a number of files with a <filename>.ent</filename>
- extension.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>The XML source for the Handbook in English is
+ found in <sgmltag class="starttag">filename class="directory"</sgmltag>/usr/doc/en_US.ISO8859-1/books/handbook/<sgmltag class="endtag">filename</sgmltag>. The first
+ file is called <sgmltag class="starttag">filename</sgmltag>book.xml<sgmltag class="endtag">filename</sgmltag> in that
+ directory. There is also a <sgmltag class="starttag">filename</sgmltag>Makefile<sgmltag class="endtag">filename</sgmltag>
+ and a number of files with a <sgmltag class="starttag">filename</sgmltag>.ent<sgmltag class="endtag">filename</sgmltag>
+ extension.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1316,7 +1334,7 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>Install the <filename role="package">net/wireshark</filename> port to view network traffic.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>Install the <sgmltag class="starttag">filename role="package"</sgmltag>net/wireshark<sgmltag class="endtag">filename</sgmltag> port to view network traffic.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1352,17 +1370,17 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para><devicename>sio</devicename> is used for serial
- communication in FreeBSD. <devicename>sio</devicename> manifests
- through a number of entries in <filename>/dev</filename>, including
- <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
-
-<para>By contrast, network devices such as
- <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>
-
-<para>In MS-DOS, the first floppy drive is referred to as
- <devicename>a:</devicename>. In FreeBSD it is
- <filename>/dev/fd0</filename>.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">devicename</sgmltag>sio<sgmltag class="endtag">devicename</sgmltag> is used for serial
+ communication in FreeBSD. <sgmltag class="starttag">devicename</sgmltag>sio<sgmltag class="endtag">devicename</sgmltag> manifests
+ through a number of entries in <sgmltag class="starttag">filename</sgmltag>/dev<sgmltag class="endtag">filename</sgmltag>, including
+ <sgmltag class="starttag">filename</sgmltag>/dev/ttyd0<sgmltag class="endtag">filename</sgmltag> and <sgmltag class="starttag">filename</sgmltag>/dev/cuaa0<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">para</sgmltag>By contrast, network devices such as
+ <sgmltag class="starttag">devicename</sgmltag>ed0<sgmltag class="endtag">devicename</sgmltag> do not appear in <sgmltag class="starttag">filename</sgmltag>/dev<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">para</sgmltag>In MS-DOS, the first floppy drive is referred to as
+ <sgmltag class="starttag">devicename</sgmltag>a:<sgmltag class="endtag">devicename</sgmltag>. In FreeBSD it is
+ <sgmltag class="starttag">filename</sgmltag>/dev/fd0<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1481,26 +1499,26 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>The local machine can always be referred to by the
- name <hostid>localhost</hostid>, which will have the IP
- address <hostid role="ipaddr">127.0.0.1</hostid>.</para>
+ <programlisting><sgmltag class="starttag">para</sgmltag>The local machine can always be referred to by the
+ name <sgmltag class="starttag">hostid</sgmltag>localhost<sgmltag class="endtag">hostid</sgmltag>, which will have the IP
+ address <sgmltag class="starttag">hostid role="ipaddr"</sgmltag>127.0.0.1<sgmltag class="endtag">hostid</sgmltag>.<sgmltag class="endtag">para</sgmltag>
-<para>The <hostid role="domainname">FreeBSD.org</hostid>
+<sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">hostid role="domainname"</sgmltag>FreeBSD.org<sgmltag class="endtag">hostid</sgmltag>
domain contains a number of different hosts, including
- <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
- <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
+ <sgmltag class="starttag">hostid role="fqdn"</sgmltag>freefall.FreeBSD.org<sgmltag class="endtag">hostid</sgmltag> and
+ <sgmltag class="starttag">hostid role="fqdn"</sgmltag>bento.FreeBSD.org<sgmltag class="endtag">hostid</sgmltag>.<sgmltag class="endtag">para</sgmltag>
-<para>When adding an <acronym>IP</acronym> alias to an
- interface (using <command>ifconfig</command>)
- <emphasis>always</emphasis> use a netmask of
- <hostid role="netmask">255.255.255.255</hostid> (which can
+<sgmltag class="starttag">para</sgmltag>When adding an <sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag> alias to an
+ interface (using <sgmltag class="starttag">command</sgmltag>ifconfig<sgmltag class="endtag">command</sgmltag>)
+ <sgmltag class="starttag">emphasis</sgmltag>always<sgmltag class="endtag">emphasis</sgmltag> use a netmask of
+ <sgmltag class="starttag">hostid role="netmask"</sgmltag>255.255.255.255<sgmltag class="endtag">hostid</sgmltag> (which can
also be expressed as
- <hostid role="netmask">0xffffffff</hostid>).</para>
+ <sgmltag class="starttag">hostid role="netmask"</sgmltag>0xffffffff<sgmltag class="endtag">hostid</sgmltag>).<sgmltag class="endtag">para</sgmltag>
-<para>The <acronym>MAC</acronym> address uniquely identifies
+<sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">acronym</sgmltag>MAC<sgmltag class="endtag">acronym</sgmltag> address uniquely identifies
every network card in existence. A typical
- <acronym>MAC</acronym> address looks like
- <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
+ <sgmltag class="starttag">acronym</sgmltag>MAC<sgmltag class="endtag">acronym</sgmltag> address looks like
+ <sgmltag class="starttag">hostid role="mac"</sgmltag>08:00:20:87:ef:d0<sgmltag class="endtag">hostid</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1547,8 +1565,8 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>To carry out most system administration functions
- requires logging in as <username>root</username>.</para>]]></programlisting>
+ <programlisting><sgmltag class="starttag">para</sgmltag>To carry out most system administration functions
+ requires logging in as <sgmltag class="starttag">username</sgmltag>root<sgmltag class="endtag">username</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1587,19 +1605,19 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>Two common targets in a <filename>Makefile</filename>
- are <maketarget>all</maketarget> and
- <maketarget>clean</maketarget>.</para>
+ <programlisting><sgmltag class="starttag">para</sgmltag>Two common targets in a <sgmltag class="starttag">filename</sgmltag>Makefile<sgmltag class="endtag">filename</sgmltag>
+ are <sgmltag class="starttag">maketarget</sgmltag>all<sgmltag class="endtag">maketarget</sgmltag> and
+ <sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag>.<sgmltag class="endtag">para</sgmltag>
-<para>Typically, invoking <maketarget>all</maketarget> will
+<sgmltag class="starttag">para</sgmltag>Typically, invoking <sgmltag class="starttag">maketarget</sgmltag>all<sgmltag class="endtag">maketarget</sgmltag> will
rebuild the application, and invoking
- <maketarget>clean</maketarget> will remove the temporary
- files (<filename>.o</filename> for example) created by the
- build process.</para>
-
-<para><maketarget>clean</maketarget> may be controlled by a
- number of variables, including <makevar>CLOBBER</makevar>
- and <makevar>RECURSE</makevar>.</para>]]></programlisting>
+ <sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag> will remove the temporary
+ files (<sgmltag class="starttag">filename</sgmltag>.o<sgmltag class="endtag">filename</sgmltag> for example) created by the
+ build process.<sgmltag class="endtag">para</sgmltag>
+
+<sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag> may be controlled by a
+ number of variables, including <sgmltag class="starttag">makevar</sgmltag>CLOBBER<sgmltag class="endtag">makevar</sgmltag>
+ and <sgmltag class="starttag">makevar</sgmltag>RECURSE<sgmltag class="endtag">makevar</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1642,10 +1660,10 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>The <literal>maxusers 10</literal> line in the kernel
+ <programlisting><sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">literal</sgmltag>maxusers 10<sgmltag class="endtag">literal</sgmltag> 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>
+ support.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1675,7 +1693,7 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
+ <programlisting><sgmltag class="starttag">screen</sgmltag>&prompt.user; <sgmltag class="starttag">userinput</sgmltag>man <sgmltag class="starttag">replaceable</sgmltag>command<sgmltag class="endtag">replaceable</sgmltag><sgmltag class="endtag">userinput</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1693,13 +1711,13 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<para>The <literal>maxusers <replaceable>n</replaceable></literal>
+ <programlisting><sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">literal</sgmltag>maxusers <sgmltag class="starttag">replaceable</sgmltag>n<sgmltag class="endtag">replaceable</sgmltag><sgmltag class="endtag">literal</sgmltag>
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>
+ support.<sgmltag class="endtag">para</sgmltag>
-<para>For a desktop workstation, <literal>32</literal> is a good value
- for <replaceable>n</replaceable>.</para>]]></programlisting>
+<sgmltag class="starttag">para</sgmltag>For a desktop workstation, <sgmltag class="starttag">literal</sgmltag>32<sgmltag class="endtag">literal</sgmltag> is a good value
+ for <sgmltag class="starttag">replaceable</sgmltag>n<sgmltag class="endtag">replaceable</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1726,7 +1744,7 @@ This is the file called 'foo2'</screen>
<para>Usage:</para>
- <programlisting><![CDATA[<screen><errorname>Panic: cannot mount root</errorname></screen>]]></programlisting>
+ <programlisting><sgmltag class="starttag">screen</sgmltag><sgmltag class="starttag">errorname</sgmltag>Panic: cannot mount root<sgmltag class="endtag">errorname</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting>
<para>Appearance:</para>
@@ -1781,8 +1799,8 @@ This is the file called 'foo2'</screen>
images should be committed to the documentation
repository.</para>
- <para>Use the appropriate format for each image. It is to be
- expected that documentation will have a mix of
+ <para>Use the appropriate format for each image. Documentation
+ will often have a mix of
<acronym>EPS</acronym> and <acronym>PNG</acronym> images. The
<filename>Makefile</filename>s ensure that the correct format
image is chosen depending on the output format used.
@@ -1791,7 +1809,7 @@ This is the file called 'foo2'</screen>
formats</emphasis>.</para>
<important>
- <para>It is anticipated that the Documentation Project will
+ <para>The Documentation Project may eventually
switch to using the <acronym>SVG</acronym> (Scalable Vector
Graphic) format for vector images. However, the current
state of <acronym>SVG</acronym> capable editing tools makes
More information about the svn-doc-all
mailing list