Date: Wed, 25 Jun 2014 14:19:47 +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: r45124 - head/en_US.ISO8859-1/books/fdp-primer/examples Message-ID: <201406251419.s5PEJlqK045451@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@example.com<tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag>foo@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@example.com<tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="starttag">address</tag> + <tag class="starttag">email</tag>foo@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201406251419.s5PEJlqK045451>