diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml')
-rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml new file mode 100644 index 0000000000..142df0c812 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml @@ -0,0 +1,355 @@ +<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> + +<appendix id="examples"> + <title>Examples</title> + + <para>This appendix contains example SGML 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>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 SGML + source for this and other documents, available in the + <application>CVSup</application> <literal>doc</literal> collection, or + available online starting at + <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/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 stock stylesheets + distributed by Norm Walsh, rather than any customizations made to those + stylesheets by the FreeBSD Documentation Project. This makes them more + useful as generic DocBook examples.</para> + + <sect1 id="examples-docbook-book"> + <title>DocBook <sgmltag>book</sgmltag></title> + + <example> + <title>DocBook <sgmltag>book</sgmltag></title> + + <programlisting><![ CDATA [<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<book> + <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> + </example> + </sect1> + + <sect1 id="examples-docbook-article"> + <title>DocBook <sgmltag>article</sgmltag></title> + + <example> + <title>DocBook <sgmltag>article</sgmltag></title> + + <programlisting><![ CDATA [<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<article> + <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> + </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> + + <sect2> + <title>Using Jade</title> + + <example> + <title>Converting DocBook to HTML (one large file)</title> + + <screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"> + -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog"> + -c /usr/local/share/sgml/docbook/catalog \ + -c /usr/local/share/sgml/jade/catalog \ + -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-1-dsssl"> + -t sgml <co id="examples-co-jade-1-transform"> <replaceable>file</replaceable>.sgml > <replaceable>file</replaceable>.html <co 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 DSSSL stylesheets. The second + contains information about the DocBook DTD. 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 <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 another. In + this case, the input is being transformed from the DocBook DTD + to the HTML DTD.</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 HTML (several small files)</title> + + <screen>&prompt.user; <userinput>jade \ + -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog"> + -c /usr/local/share/sgml/docbook/catalog \ + -c /usr/local/share/sgml/jade/catalog \ + -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-2-dsssl"> + -t sgml <co id="examples-co-jade-2-transform"> <replaceable>file</replaceable>.sgml <co 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 DSSSL stylesheets. The second + contains information about the DocBook DTD. The third contains + information specific to Jade.</para> + </callout> + + <callout arearefs="examples-co-jade-2-dsssl"> + <para>Specifies the full path to the DSSSL 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 another. In + this case, the input is being transformed from the DocBook DTD + to the HTML DTD.</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 document.</para> + </callout> + </calloutlist> + + <para>This example may still only generate one HTML 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> + + <para>The source SGML 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"> + -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog"> + -c /usr/local/share/sgml/docbook/catalog \ + -c /usr/local/share/sgml/jade/catalog \ + -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \<co id="examples-co-jade-3-dsssl"> + -t tex <co id="examples-co-jade-3-tex"> <replaceable>file</replaceable>.sgml</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 DSSSL stylesheets. The second contains + information about the DocBook DTD. The third contains + information specific to Jade.</para> + </callout> + + <callout arearefs="examples-co-jade-3-dsssl"> + <para>Specifies the full path to the DSSSL 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>You have to run <command>tex</command> <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 PDF</title> + + <para>The first part of this process is identical to that when + 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>. 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> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../appendix.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "appendix") + End: +--> |