diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/examples')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml | 205 |
1 files changed, 113 insertions, 92 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 index 65fdab4233..f27874e648 100644 --- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml @@ -33,24 +33,25 @@ <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>svn</application> <literal>doc</literal> repository, or - available online starting at + <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>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 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> + <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> @@ -152,20 +153,21 @@ <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>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 \ @@ -175,41 +177,48 @@ <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> + <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> + <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> + <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> + <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> + <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> - + <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 \ @@ -219,42 +228,48 @@ <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> + <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> + <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> + <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> + <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> + <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> + <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"> @@ -268,51 +283,56 @@ <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> + <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> + <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> + <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 + <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> + 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> - + <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> @@ -327,17 +347,18 @@ <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> + <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> + <filename><replaceable>file</replaceable>.pdf</filename>, + which does not need to be processed any further.</para> </example> </sect2> </sect1> |