svn commit: r42393 - head/en_US.ISO8859-1/books/fdp-primer/examples
Warren Block
wblock at FreeBSD.org
Tue Jul 23 01:35:21 UTC 2013
Author: wblock
Date: Tue Jul 23 01:35:20 2013
New Revision: 42393
URL: http://svnweb.freebsd.org/changeset/doc/42393
Log:
First pass through the examples appendix, updating, simplifying, and
changing CDATA sections to sgmltag.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml Tue Jul 23 00:45:09 2013 (r42392)
+++ head/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml Tue Jul 23 01:35:20 2013 (r42393)
@@ -34,23 +34,23 @@
<appendix id="examples">
<title>Examples</title>
- <para>This appendix contains example XML files and command lines
- you can use to convert them from one output format to another. If
- you have successfully installed the Documentation Project tools
- then you should be able to use these examples directly.</para>
+ <para>This appendix contains example <acronym>XML</acronym> files and the commands
+ to convert them from one output format to another. After
+ installing the Documentation Project tools (see <xref linkend="tools-required"/>),
+ these examples can be used directly.</para>
<para>These examples are not exhaustive—they do not contain
- all the elements you might want to use, particularly in your
- document's front matter. For more examples of DocBook markup you
- should examine the XML source for this and other documents,
+ all the elements that might be desirable to use, particularly in a
+ document's front matter. For more examples of DocBook markup,
+ examine the <acronym>XML</acronym> source for this and other documents
available in the <application>svn</application>
<literal>doc</literal> repository, or available online starting at
<ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para>
<para>To avoid confusion, these examples use the standard DocBook
- 4.1 DTD rather than the FreeBSD extension. They also use the
+ 4.1 <acronym>DTD</acronym> rather than the &os; extension. They also use the
stock stylesheets distributed by Norm Walsh, rather than any
- customizations made to those stylesheets by the FreeBSD
+ customizations made to those stylesheets by the &os;
Documentation Project. This makes them more useful as generic
DocBook examples.</para>
@@ -60,50 +60,50 @@
<example>
<title>DocBook <sgmltag>book</sgmltag></title>
- <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ <programlisting><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<book lang='en'>
- <bookinfo>
- <title>An Example Book</title>
-
- <author>
- <firstname>Your first name</firstname>
- <surname>Your surname</surname>
- <affiliation>
- <address><email>foo at example.com</email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year>2000</year>
- <holder>Copyright string here</holder>
- </copyright>
-
- <abstract>
- <para>If your book has an abstract then it should go here.</para>
- </abstract>
- </bookinfo>
-
- <preface>
- <title>Preface</title>
-
- <para>Your book may have a preface, in which case it should be placed
- here.</para>
- </preface>
-
- <chapter>
- <title>My First Chapter</title>
-
- <para>This is the first chapter in my book.</para>
-
- <sect1>
- <title>My First Section</title>
-
- <para>This is the first section in my book.</para>
- </sect1>
- </chapter>
-</book>]]></programlisting>
+<sgmltag class="starttag">book lang='en'</sgmltag>
+ <sgmltag class="starttag">bookinfo</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>An Example Book<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">author</sgmltag>
+ <sgmltag class="starttag">firstname</sgmltag>Your first name<sgmltag class="endtag">firstname</sgmltag>
+ <sgmltag class="starttag">surname</sgmltag>Your surname<sgmltag class="endtag">surname</sgmltag>
+ <sgmltag class="starttag">affiliation</sgmltag>
+ <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag>foo at example.com<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>2000<sgmltag class="endtag">year</sgmltag>
+ <sgmltag class="starttag">holder</sgmltag>Copyright string here<sgmltag class="endtag">holder</sgmltag>
+ <sgmltag class="endtag">copyright</sgmltag>
+
+ <sgmltag class="starttag">abstract</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>If your book has an abstract then it should go here.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">abstract</sgmltag>
+ <sgmltag class="endtag">bookinfo</sgmltag>
+
+ <sgmltag class="starttag">preface</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>Preface<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">para</sgmltag>Your book may have a preface, in which case it should be placed
+ here.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">preface</sgmltag>
+
+ <sgmltag class="starttag">chapter</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>My First Chapter<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">para</sgmltag>This is the first chapter in my book.<sgmltag class="endtag">para</sgmltag>
+
+ <sgmltag class="starttag">sect1</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>My First Section<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">para</sgmltag>This is the first section in my book.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">sect1</sgmltag>
+ <sgmltag class="endtag">chapter</sgmltag>
+<sgmltag class="endtag">book</sgmltag></programlisting>
</example>
</sect1>
@@ -113,63 +113,56 @@
<example>
<title>DocBook <sgmltag>article</sgmltag></title>
- <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ <programlisting><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<article lang='en'>
- <articleinfo>
- <title>An Example Article</title>
-
- <author>
- <firstname>Your first name</firstname>
- <surname>Your surname</surname>
- <affiliation>
- <address><email>foo at example.com</email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year>2000</year>
- <holder>Copyright string here</holder>
- </copyright>
-
- <abstract>
- <para>If your article has an abstract then it should go here.</para>
- </abstract>
- </articleinfo>
-
- <sect1>
- <title>My First Section</title>
-
- <para>This is the first section in my article.</para>
-
- <sect2>
- <title>My First Sub-Section</title>
-
- <para>This is the first sub-section in my article.</para>
- </sect2>
- </sect1>
-</article>]]></programlisting>
+<sgmltag class="starttag">article lang='en'</sgmltag>
+ <sgmltag class="starttag">articleinfo</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>An Example Article<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">author</sgmltag>
+ <sgmltag class="starttag">firstname</sgmltag>Your first name<sgmltag class="endtag">firstname</sgmltag>
+ <sgmltag class="starttag">surname</sgmltag>Your surname<sgmltag class="endtag">surname</sgmltag>
+ <sgmltag class="starttag">affiliation</sgmltag>
+ <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag>foo at example.com<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>2000<sgmltag class="endtag">year</sgmltag>
+ <sgmltag class="starttag">holder</sgmltag>Copyright string here<sgmltag class="endtag">holder</sgmltag>
+ <sgmltag class="endtag">copyright</sgmltag>
+
+ <sgmltag class="starttag">abstract</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>If your article has an abstract then it should go here.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">abstract</sgmltag>
+ <sgmltag class="endtag">articleinfo</sgmltag>
+
+ <sgmltag class="starttag">sect1</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>My First Section<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">para</sgmltag>This is the first section in my article.<sgmltag class="endtag">para</sgmltag>
+
+ <sgmltag class="starttag">sect2</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>My First Sub-Section<sgmltag class="endtag">title</sgmltag>
+
+ <sgmltag class="starttag">para</sgmltag>This is the first sub-section in my article.<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">sect2</sgmltag>
+ <sgmltag class="endtag">sect1</sgmltag>
+<sgmltag class="endtag">article</sgmltag></programlisting>
</example>
</sect1>
<sect1 id="examples-formatted">
<title>Producing Formatted Output</title>
- <para>This section assumes that you have installed the software
- listed in the <filename
- role="package">textproc/docproj</filename> port, either by
- hand, or by using the port. Further, it is assumed that your
- software is installed in subdirectories under
- <filename>/usr/local/</filename>, and the directory where
- binaries have been installed is in your <envar>PATH</envar>.
- Adjust the paths as necessary for your system.</para>
+ <para>Before using this examples, install the required tools as shown in <xref linkend="tools-required"/>.</para>
<sect2>
- <title>Using Jade</title>
+ <title>Using <application>Jade</application></title>
<example>
- <title>Converting DocBook to HTML (One Large File)</title>
+ <title>Converting DocBook to <acronym>XHTML</acronym> (One Large File)</title>
<screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"/>
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog"/>
@@ -190,23 +183,23 @@
<para>Specifies the catalogs that
<application>Jade</application> will need to process.
Three catalogs are required. The first is a catalog
- that contains information about the DSSSL stylesheets.
- The second contains information about the DocBook DTD.
+ that contains information about the <acronym>DSSSL</acronym> stylesheets.
+ The second contains information about the DocBook <acronym>DTD</acronym>.
The third contains information specific to
<application>Jade</application>.</para>
</callout>
<callout arearefs="examples-co-jade-1-dsssl">
- <para>Specifies the full path to the DSSSL stylesheet that
+ <para>Specifies the full path to the <acronym>DSSSL</acronym> stylesheet that
<application>Jade</application> will use when processing
the document.</para>
</callout>
<callout arearefs="examples-co-jade-1-transform">
<para>Instructs <application>Jade</application> to perform
- a <emphasis>transformation</emphasis> from one DTD to
+ a <emphasis>transformation</emphasis> from one <acronym>DTD</acronym> to
another. In this case, the input is being transformed
- from the DocBook DTD to the HTML DTD.</para>
+ from the DocBook <acronym>DTD</acronym> to the <acronym>XHTML</acronym> <acronym>DTD</acronym>.</para>
</callout>
<callout arearefs="examples-co-jade-1-filename">
@@ -219,7 +212,7 @@
</example>
<example>
- <title>Converting DocBook to HTML (Several Small
+ <title>Converting DocBook to <acronym>XHTML</acronym> (Several Small
Files)</title>
<screen>&prompt.user; <userinput>jade \
@@ -234,44 +227,44 @@
<para>Specifies the catalogs that
<application>Jade</application> will need to process.
Three catalogs are required. The first is a catalog
- that contains information about the DSSSL stylesheets.
- The second contains information about the DocBook DTD.
- The third contains information specific to Jade.</para>
+ that contains information about the <acronym>DSSSL</acronym> stylesheets.
+ The second contains information about the DocBook <acronym>DTD</acronym>.
+ The third contains information specific to <application>Jade</application>.</para>
</callout>
<callout arearefs="examples-co-jade-2-dsssl">
- <para>Specifies the full path to the DSSSL stylesheet that
+ <para>Specifies the full path to the <acronym>DSSSL</acronym> stylesheet that
<application>Jade</application> will use when processing
the document.</para>
</callout>
<callout arearefs="examples-co-jade-2-transform">
<para>Instructs <application>Jade</application> to perform
- a <emphasis>transformation</emphasis> from one DTD to
+ a <emphasis>transformation</emphasis> from one <acronym>DTD</acronym> to
another. In this case, the input is being transformed
- from the DocBook DTD to the HTML DTD.</para>
+ from the DocBook <acronym>DTD</acronym> to the <acronym>XHTML</acronym> <acronym>DTD</acronym>.</para>
</callout>
<callout arearefs="examples-co-jade-2-filename">
<para>Specifies the file that
<application>Jade</application> should process. The
- stylesheets determine how the individual HTML files will
- be named, and the name of the <quote>root</quote> file
- (i.e., the one that contains the start of the
+ stylesheets determine how the individual <acronym>XHTML</acronym> files will
+ be named, and the name of the <quote>root</quote> file,
+ the one that contains the start of the
document.</para>
</callout>
</calloutlist>
- <para>This example may still only generate one HTML file,
+ <para>This example may still only generate one <acronym>XHTML</acronym> file,
depending on the structure of the document you are
processing, and the stylesheet's rules for splitting
output.</para>
</example>
<example id="examples-docbook-postscript">
- <title>Converting DocBook to Postscript</title>
+ <title>Converting DocBook to &postscript;</title>
- <para>The source XML file must be converted to a &tex;
+ <para>The source <acronym>XML</acronym> file must be converted to a &tex;
file.</para>
<screen>&prompt.user; <userinput>jade -V tex-backend \ <co id="examples-co-jade-3-tex-backend"/>
@@ -291,13 +284,13 @@
<para>Specifies the catalogs that
<application>Jade</application> will need to process.
Three catalogs are required. The first is a catalog
- that contains information about the DSSSL stylesheets.
- The second contains information about the DocBook DTD.
- The third contains information specific to Jade.</para>
+ that contains information about the <acronym>DSSSL</acronym> stylesheets.
+ The second contains information about the DocBook <acronym>DTD</acronym>.
+ The third contains information specific to <application>Jade</application>.</para>
</callout>
<callout arearefs="examples-co-jade-3-dsssl">
- <para>Specifies the full path to the DSSSL stylesheet that
+ <para>Specifies the full path to the <acronym>DSSSL</acronym> stylesheet that
<application>Jade</application> will use when processing
the document.</para>
</callout>
@@ -314,7 +307,7 @@
<screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen>
- <para>You have to run <command>tex</command> <emphasis>at
+ <para><command>tex</command> commands must be run <emphasis>at
least</emphasis> three times. The first run processes the
document, and determines areas of the document which are
referenced from other parts of the document, for use in
@@ -337,21 +330,21 @@
<filename><replaceable>file</replaceable>.dvi</filename>.</para>
<para>Finally, run <command>dvips</command> to convert the
- <filename>.dvi</filename> file to Postscript.</para>
+ <filename>.dvi</filename> file to &postscript;.</para>
<screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen>
</example>
<example>
- <title>Converting DocBook to PDF</title>
+ <title>Converting DocBook to <acronym>PDF</acronym></title>
- <para>The first part of this process is identical to that when
- converting DocBook to Postscript, using the same
+ <para>The first part of this process is identical to that of
+ converting DocBook to &postscript;, using the same
<command>jade</command> command line (<xref
linkend="examples-docbook-postscript"/>).</para>
- <para>When the <filename>.tex</filename> file has been
- generated you run <application>pdfTeX</application>.
+ <para>After the <filename>.tex</filename> file has been
+ generated, run <application>pdfTeX</application>.
However, use the <literal>&pdfjadetex</literal> macro
package instead.</para>
More information about the svn-doc-head
mailing list