e84c225de8
- Mark up arguments for Jade in the examples with <replaceable> (to be consistent) - Mark up Jade, pdfTeX with <application> - Mark up pdfjadetex with <literal> - Unfold <abbrev>STDOUT</abbrev> to "standard output" - Mark up Jade error message with <errorname>
355 lines
14 KiB
Text
355 lines
14 KiB
Text
<!-- 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:
|
|
-->
|