Date: Tue, 23 Jul 2013 01:35:20 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42393 - head/en_US.ISO8859-1/books/fdp-primer/examples Message-ID: <201307230135.r6N1ZKNc001898@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@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@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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307230135.r6N1ZKNc001898>