svn commit: r45124 - head/en_US.ISO8859-1/books/fdp-primer/examples

Warren Block wblock at FreeBSD.org
Wed Jun 25 14:19:47 UTC 2014


Author: wblock
Date: Wed Jun 25 14:19:46 2014
New Revision: 45124
URL: http://svnweb.freebsd.org/changeset/doc/45124

Log:
  Remove obsolete example build instructions.  Update book and article
  examples for DocBook 5 and FreeBSD DTD.
  
  Note to translators: there are content whitespace changes in the example
  programlistings that should be included in translations.

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	Wed Jun 25 14:11:47 2014	(r45123)
+++ head/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml	Wed Jun 25 14:19:46 2014	(r45124)
@@ -33,45 +33,40 @@
 <appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="examples">
   <title>Examples</title>
 
-  <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 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>
+    documents available in the <application>Subversion</application>
     <literal>doc</literal> repository, or available online starting at
     <uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>
 
-  <para>To avoid confusion, these examples use the standard DocBook
-    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 &os;
-    Documentation Project.  This makes them more useful as generic
-    DocBook examples.</para>
-
   <sect1 xml:id="examples-docbook-book">
     <title>DocBook <tag>book</tag></title>
 
     <example>
       <title>DocBook <tag>book</tag></title>
 
-      <programlisting><!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 "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+
+<tag class="starttag">book xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:lang="en"</tag>
 
-<tag class="starttag">book lang='en'</tag>
-  <tag class="starttag">bookinfo</tag>
+  <tag class="starttag">info</tag>
     <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag>
 
     <tag class="starttag">author</tag>
-      <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
-      <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
+      <tag class="starttag">personname</tag>
+        <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
+        <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
+      <tag class="endtag">personname</tag>
+
       <tag class="starttag">affiliation</tag>
-	<tag class="starttag">address</tag><tag class="starttag">email</tag>foo at example.com<tag class="endtag">email</tag><tag class="endtag">address</tag>
+	<tag class="starttag">address</tag>
+	  <tag class="starttag">email</tag>foo at example.com<tag class="endtag">email</tag>
+	<tag class="endtag">address</tag>
       <tag class="endtag">affiliation</tag>
     <tag class="endtag">author</tag>
 
@@ -83,7 +78,7 @@
     <tag class="starttag">abstract</tag>
       <tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag>
     <tag class="endtag">abstract</tag>
-  <tag class="endtag">bookinfo</tag>
+  <tag class="endtag">info</tag>
 
   <tag class="starttag">preface</tag>
     <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag>
@@ -113,18 +108,26 @@
     <example>
       <title>DocBook <tag>article</tag></title>
 
-      <programlisting><!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 "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+
+<tag class="starttag">article xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:lang="en"</tag>
 
-<tag class="starttag">article lang='en'</tag>
-  <tag class="starttag">articleinfo</tag>
+  <tag class="starttag">info</tag>
     <tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag>
 
     <tag class="starttag">author</tag>
-      <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
-      <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
+      <tag class="starttag">personname</tag>
+        <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
+        <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
+      <tag class="endtag">personname</tag>
+
       <tag class="starttag">affiliation</tag>
-	<tag class="starttag">address</tag><tag class="starttag">email</tag>foo at example.com<tag class="endtag">email</tag><tag class="endtag">address</tag>
+	<tag class="starttag">address</tag>
+	  <tag class="starttag">email</tag>foo at example.com<tag class="endtag">email</tag>
+	<tag class="endtag">address</tag>
       <tag class="endtag">affiliation</tag>
     <tag class="endtag">author</tag>
 
@@ -136,7 +139,7 @@
     <tag class="starttag">abstract</tag>
       <tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag>
     <tag class="endtag">abstract</tag>
-  <tag class="endtag">articleinfo</tag>
+  <tag class="endtag">info</tag>
 
   <tag class="starttag">sect1</tag>
     <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
@@ -152,223 +155,4 @@
 <tag class="endtag">article</tag></programlisting>
     </example>
   </sect1>
-
-  <sect1 xml:id="examples-formatted">
-    <title>Producing Formatted Output</title>
-
-    <para>Before using these examples, install the required tools as
-      shown in <xref linkend="tools-required"/>.</para>
-
-    <sect2>
-      <title>Using <application>Jade</application></title>
-
-      <example>
-	<title>Converting DocBook to <acronym>XHTML</acronym> (One
-	  Large File)</title>
-
-	<screen>&prompt.user; <userinput>jade -V nochunks \  <co xml:id="examples-co-jade-1-nochunks"/>
-    -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-1-catalog"/>
-    -c /usr/local/share/xml/docbook/catalog \
-    -c /usr/local/share/xml/jade/catalog \
-    -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-1-dsssl"/>
-    -t sgml <co xml:id="examples-co-jade-1-transform"/> <replaceable>file</replaceable>.xml > <replaceable>file</replaceable>.html <co xml:id="examples-co-jade-1-filename"/></userinput></screen>
-
-	<calloutlist>
-	  <callout arearefs="examples-co-jade-1-nochunks">
-	    <para>Specifies the <literal>nochunks</literal> parameter
-	      to the stylesheets, forcing all output to be written to
-	      the standard output (using Norm Walsh's
-	      stylesheets).</para>
-	  </callout>
-
-	  <callout arearefs="examples-co-jade-1-catalog">
-	    <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
-	      <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
-	      <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
-	      <acronym>DTD</acronym> to another.  In this case, the
-	      input is being transformed from the DocBook
-	      <acronym>DTD</acronym> to the <acronym>XHTML</acronym>
-	      <acronym>DTD</acronym>.</para>
-	  </callout>
-
-	  <callout arearefs="examples-co-jade-1-filename">
-	    <para>Specifies the file that
-	      <application>Jade</application> should process, and
-	      redirects output to the specified
-	      <filename>.html</filename> file.</para>
-	  </callout>
-	</calloutlist>
-      </example>
-
-      <example>
-	<title>Converting DocBook to <acronym>XHTML</acronym> (Several
-	  Small Files)</title>
-
-	<screen>&prompt.user; <userinput>jade \
-    -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-2-catalog"/>
-    -c /usr/local/share/xml/docbook/catalog \
-    -c /usr/local/share/xml/jade/catalog \
-    -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-2-dsssl"/>
-    -t sgml <co xml:id="examples-co-jade-2-transform"/> <replaceable>file</replaceable>.xml <co xml:id="examples-co-jade-2-filename"/></userinput></screen>
-
-	<calloutlist>
-	  <callout arearefs="examples-co-jade-2-catalog">
-	    <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
-	      <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
-	      <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
-	      <acronym>DTD</acronym> to another.  In this case, the
-	      input is being transformed 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
-	      <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
-	  <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 xml:id="examples-docbook-postscript">
-	<title>Converting DocBook to &postscript;</title>
-
-	<para>The source <acronym>XML</acronym> file must be converted
-	  to a &tex; file.</para>
-
-	<screen>&prompt.user; <userinput>jade -V tex-backend \ <co xml:id="examples-co-jade-3-tex-backend"/>
-    -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-3-catalog"/>
-    -c /usr/local/share/xml/docbook/catalog \
-    -c /usr/local/share/xml/jade/catalog \
-    -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \<co xml:id="examples-co-jade-3-dsssl"/>
-    -t tex <co xml:id="examples-co-jade-3-tex"/> <replaceable>file</replaceable>.xml</userinput></screen>
-
-	<calloutlist>
-	  <callout arearefs="examples-co-jade-3-tex-backend">
-	    <para>Customizes the stylesheets to use various options
-	      specific to producing output for &tex;.</para>
-	  </callout>
-
-	  <callout arearefs="examples-co-jade-3-catalog">
-	    <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
-	      <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
-	      <acronym>DSSSL</acronym> stylesheet that
-	      <application>Jade</application> will use when processing
-	      the document.</para>
-	  </callout>
-
-	  <callout arearefs="examples-co-jade-3-tex">
-	    <para>Instructs <application>Jade</application> to convert
-	      the output to &tex;.</para>
-	  </callout>
-	</calloutlist>
-
-	<para>The generated <filename>.tex</filename> file must now be
-	  run through <command>tex</command>, specifying the
-	  <literal>&jadetex</literal> macro package.</para>
-
-	<screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen>
-
-	<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 indexing, and so on.</para>
-
-	<para>Do not be alarmed if you see warning messages such as
-	  <errorname>LaTeX Warning: Reference `136' on page 5
-	    undefined on input line 728.</errorname> at this
-	  point.</para>
-
-	<para>The second run reprocesses the document now that certain
-	  pieces of information are known (such as the document's page
-	  length).  This allows index entries and other
-	  cross-references to be fixed up.</para>
-
-	<para>The third pass performs any final cleanup
-	  necessary.</para>
-
-	<para>The output from this stage will be
-	  <filename><replaceable>file</replaceable>.dvi</filename>.</para>
-
-	<para>Finally, run <command>dvips</command> to convert the
-	  <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 <acronym>PDF</acronym></title>
-
-	<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>After the <filename>.tex</filename> file has been
-	  generated, run <application>pdfTeX</application>.
-	  However, use the <literal>&pdfjadetex</literal> macro
-	  package instead.</para>
-
-	<screen>&prompt.user; <userinput>pdftex "&pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen>
-
-	<para>Again, run this command three times.</para>
-
-	<para>This will generate
-	  <filename><replaceable>file</replaceable>.pdf</filename>,
-	  which does not need to be processed any further.</para>
-      </example>
-    </sect2>
-  </sect1>
 </appendix>


More information about the svn-doc-all mailing list