os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes, mostly wrapping long lines. Translators, please

Browse source 
ignore.
This commit is contained in:
Warren Block 2012-05-20 04:02:21 +00:00
parent 68bb5ab3b0
commit f9e81e11a9
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=38847
1 changed files with 111 additions and 90 deletions

201
en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml
View file

@ -33,24 +33,25 @@
<appendix id="examples"> <appendix id="examples">
<title>Examples</title> <title>Examples</title>
<para>This appendix contains example SGML files and command lines you can <para>This appendix contains example SGML files and command lines
use to convert them from one output format to another. If you have you can use to convert them from one output format to another. If
successfully installed the Documentation Project tools then you should you have successfully installed the Documentation Project tools
be able to use these examples directly.</para> then you should be able to use these examples directly.</para>
<para>These examples are not exhaustive&mdash;they do not contain all the <para>These examples are not exhaustive&mdash;they do not contain
elements you might want to use, particularly in your document's front all the elements you might want to use, particularly in your
matter. For more examples of DocBook markup you should examine the SGML document's front matter. For more examples of DocBook markup you
source for this and other documents, available in the should examine the SGML source for this and other documents,
<application>svn</application> <literal>doc</literal> repository, or available in the <application>svn</application>
available online starting at <literal>doc</literal> repository, or available online starting at
<ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para> <ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para>
<para>To avoid confusion, these examples use the standard DocBook 4.1 DTD <para>To avoid confusion, these examples use the standard DocBook
rather than the FreeBSD extension. They also use the stock stylesheets 4.1 DTD rather than the FreeBSD extension. They also use the
distributed by Norm Walsh, rather than any customizations made to those stock stylesheets distributed by Norm Walsh, rather than any
stylesheets by the FreeBSD Documentation Project. This makes them more customizations made to those stylesheets by the FreeBSD
useful as generic DocBook examples.</para> Documentation Project. This makes them more useful as generic
DocBook examples.</para>
<sect1 id="examples-docbook-book"> <sect1 id="examples-docbook-book">
<title>DocBook <sgmltag>book</sgmltag></title> <title>DocBook <sgmltag>book</sgmltag></title>
@ -152,20 +153,21 @@
<sect1 id="examples-formatted"> <sect1 id="examples-formatted">
<title>Producing Formatted Output</title> <title>Producing Formatted Output</title>
<para>This section assumes that you have installed the software listed in <para>This section assumes that you have installed the software
the <filename role="package">textproc/docproj</filename> port, either by hand, or by listed in the <filename
using the port. Further, it is assumed that your software is installed role="package">textproc/docproj</filename> port, either by
in subdirectories under <filename>/usr/local/</filename>, and the hand, or by using the port. Further, it is assumed that your
directory where binaries have been installed is in your software is installed in subdirectories under
<envar>PATH</envar>. Adjust the paths as necessary for your <filename>/usr/local/</filename>, and the directory where
system.</para> binaries have been installed is in your <envar>PATH</envar>.
Adjust the paths as necessary for your system.</para>
<sect2> <sect2>
<title>Using Jade</title> <title>Using Jade</title>
<example> <example>
<title>Converting DocBook to HTML (One Large File)</title> <title>Converting DocBook to HTML (One Large File)</title>
<screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"> <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/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog">
-c /usr/local/share/sgml/docbook/catalog \ -c /usr/local/share/sgml/docbook/catalog \
@ -175,41 +177,48 @@
<calloutlist> <calloutlist>
<callout arearefs="examples-co-jade-1-nochunks"> <callout arearefs="examples-co-jade-1-nochunks">
<para>Specifies the <literal>nochunks</literal> parameter to the <para>Specifies the <literal>nochunks</literal> parameter
stylesheets, forcing all output to be written to to the stylesheets, forcing all output to be written to
the standard output (using Norm Walsh's stylesheets).</para> the standard output (using Norm Walsh's
stylesheets).</para>
</callout> </callout>
<callout arearefs="examples-co-jade-1-catalog"> <callout arearefs="examples-co-jade-1-catalog">
<para>Specifies the catalogs that <application>Jade</application> will need to process. <para>Specifies the catalogs that
Three catalogs are required. The first is a catalog that <application>Jade</application> will need to process.
contains information about the DSSSL stylesheets. The second Three catalogs are required. The first is a catalog
contains information about the DocBook DTD. The third contains that contains information about the DSSSL stylesheets.
information specific to <application>Jade</application>.</para> The second contains information about the DocBook DTD.
The third contains information specific to
<application>Jade</application>.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-1-dsssl"> <callout arearefs="examples-co-jade-1-dsssl">
<para>Specifies the full path to the DSSSL stylesheet that <application>Jade</application> <para>Specifies the full path to the DSSSL stylesheet that
will use when processing the document.</para> <application>Jade</application> will use when processing
the document.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-1-transform"> <callout arearefs="examples-co-jade-1-transform">
<para>Instructs <application>Jade</application> to perform a <para>Instructs <application>Jade</application> to perform
<emphasis>transformation</emphasis> from one DTD to another. In a <emphasis>transformation</emphasis> from one DTD to
this case, the input is being transformed from the DocBook DTD another. In this case, the input is being transformed
to the HTML DTD.</para> from the DocBook DTD to the HTML DTD.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-1-filename"> <callout arearefs="examples-co-jade-1-filename">
<para>Specifies the file that <application>Jade</application> should process, and redirects <para>Specifies the file that
output to the specified <filename>.html</filename> file.</para> <application>Jade</application> should process, and
redirects output to the specified
<filename>.html</filename> file.</para>
</callout> </callout>
</calloutlist> </calloutlist>
</example> </example>
<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 \ <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/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog">
-c /usr/local/share/sgml/docbook/catalog \ -c /usr/local/share/sgml/docbook/catalog \
@ -219,42 +228,48 @@
<calloutlist> <calloutlist>
<callout arearefs="examples-co-jade-2-catalog"> <callout arearefs="examples-co-jade-2-catalog">
<para>Specifies the catalogs that <application>Jade</application> will need to process. <para>Specifies the catalogs that
Three catalogs are required. The first is a catalog that <application>Jade</application> will need to process.
contains information about the DSSSL stylesheets. The second Three catalogs are required. The first is a catalog
contains information about the DocBook DTD. The third contains that contains information about the DSSSL stylesheets.
information specific to Jade.</para> The second contains information about the DocBook DTD.
The third contains information specific to Jade.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-2-dsssl"> <callout arearefs="examples-co-jade-2-dsssl">
<para>Specifies the full path to the DSSSL stylesheet that <application>Jade</application> <para>Specifies the full path to the DSSSL stylesheet that
will use when processing the document.</para> <application>Jade</application> will use when processing
the document.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-2-transform"> <callout arearefs="examples-co-jade-2-transform">
<para>Instructs <application>Jade</application> to perform a <para>Instructs <application>Jade</application> to perform
<emphasis>transformation</emphasis> from one DTD to another. In a <emphasis>transformation</emphasis> from one DTD to
this case, the input is being transformed from the DocBook DTD another. In this case, the input is being transformed
to the HTML DTD.</para> from the DocBook DTD to the HTML DTD.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-2-filename"> <callout arearefs="examples-co-jade-2-filename">
<para>Specifies the file that <application>Jade</application> should process. The <para>Specifies the file that
stylesheets determine how the individual HTML files will be <application>Jade</application> should process. The
named, and the name of the <quote>root</quote> file (i.e., the stylesheets determine how the individual HTML files will
one that contains the start of the document.</para> be named, and the name of the <quote>root</quote> file
(i.e., the one that contains the start of the
document.</para>
</callout> </callout>
</calloutlist> </calloutlist>
<para>This example may still only generate one HTML file, depending on <para>This example may still only generate one HTML file,
the structure of the document you are processing, and the depending on the structure of the document you are
stylesheet's rules for splitting output.</para> processing, and the stylesheet's rules for splitting
output.</para>
</example> </example>
<example id="examples-docbook-postscript"> <example id="examples-docbook-postscript">
<title>Converting DocBook to Postscript</title> <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"> <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/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog">
@ -268,51 +283,56 @@
<para>Customizes the stylesheets to use various options <para>Customizes the stylesheets to use various options
specific to producing output for &tex;.</para> specific to producing output for &tex;.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-3-catalog"> <callout arearefs="examples-co-jade-3-catalog">
<para>Specifies the catalogs that <application>Jade</application> will need to process. Three <para>Specifies the catalogs that
catalogs are required. The first is a catalog that contains <application>Jade</application> will need to process.
information about the DSSSL stylesheets. The second contains Three catalogs are required. The first is a catalog
information about the DocBook DTD. The third contains that contains information about the DSSSL stylesheets.
information specific to Jade.</para> The second contains information about the DocBook DTD.
The third contains information specific to Jade.</para>
</callout> </callout>
<callout arearefs="examples-co-jade-3-dsssl"> <callout arearefs="examples-co-jade-3-dsssl">
<para>Specifies the full path to the DSSSL stylesheet that <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>
<callout arearefs="examples-co-jade-3-tex"> <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> </callout>
</calloutlist> </calloutlist>
<para>The generated <filename>.tex</filename> file must now be run <para>The generated <filename>.tex</filename> file must now be
through <command>tex</command>, specifying the run through <command>tex</command>, specifying the
<literal>&amp;jadetex</literal> macro package.</para> <literal>&amp;jadetex</literal> macro package.</para>
<screen>&prompt.user; <userinput>tex "&amp;jadetex" <replaceable>file</replaceable>.tex</userinput></screen> <screen>&prompt.user; <userinput>tex "&amp;jadetex" <replaceable>file</replaceable>.tex</userinput></screen>
<para>You have to run <command>tex</command> <emphasis>at <para>You have to run <command>tex</command> <emphasis>at
least</emphasis> three times. The first run processes the least</emphasis> three times. The first run processes the
document, and determines areas of the document which are referenced document, and determines areas of the document which are
from other parts of the document, for use in indexing, and so referenced from other parts of the document, for use in
on.</para> indexing, and so on.</para>
<para>Do not be alarmed if you see warning messages such as <para>Do not be alarmed if you see warning messages such as
<errorname>LaTeX Warning: Reference `136' on page 5 undefined on input <errorname>LaTeX Warning: Reference `136' on page 5
line 728.</errorname> at this point.</para> 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 <para>The second run reprocesses the document now that certain
allows index entries and other cross-references to be fixed pieces of information are known (such as the document's page
up.</para> 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 third pass performs any final cleanup necessary.</para>
<para>The output from this stage will be <para>The output from this stage will be
<filename><replaceable>file</replaceable>.dvi</filename>.</para> <filename><replaceable>file</replaceable>.dvi</filename>.</para>
<para>Finally, run <command>dvips</command> to convert the <para>Finally, run <command>dvips</command> to convert the
<filename>.dvi</filename> file to Postscript.</para> <filename>.dvi</filename> file to Postscript.</para>
@ -327,17 +347,18 @@
<command>jade</command> command line (<xref <command>jade</command> command line (<xref
linkend="examples-docbook-postscript">).</para> linkend="examples-docbook-postscript">).</para>
<para>When the <filename>.tex</filename> file has been generated you <para>When the <filename>.tex</filename> file has been
run <application>pdfTeX</application>. However, use the <literal>&amp;pdfjadetex</literal> macro package generated you run <application>pdfTeX</application>.
instead.</para> However, use the <literal>&amp;pdfjadetex</literal> macro
package instead.</para>
<screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen> <screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen>
<para>Again, run this command three times.</para> <para>Again, run this command three times.</para>
<para>This will generate <para>This will generate
<filename><replaceable>file</replaceable>.pdf</filename>, which does <filename><replaceable>file</replaceable>.pdf</filename>,
not need to be processed any further.</para> which does not need to be processed any further.</para>
</example> </example>
</sect2> </sect2>
</sect1> </sect1>