aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>2000-07-16 16:35:41 +0000
committerNik Clayton <nik@FreeBSD.org>2000-07-16 16:35:41 +0000
commitf3e88313ac4df15d46b15610e90bf73f01135f4b (patch)
tree32a46f590f389791dedf223e538db0635cf9ddea /en_US.ISO8859-1
parent69a59546e0c61cdb7b4ec10e62e07eb3ee59a2f5 (diff)
downloaddoc-f3e88313ac4df15d46b15610e90bf73f01135f4b.tar.gz
doc-f3e88313ac4df15d46b15610e90bf73f01135f4b.zip
Add some examples for sample documents and command lines showing how
to convert the documents from DocBook to various output formats. Requested by: Patrick Powell <papowell@astart.com>
Notes
Notes: svn path=/head/; revision=7629
Diffstat (limited to 'en_US.ISO8859-1')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml355
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..229f36aeb7
--- /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: doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v 1.8 2000/06/15 01:00:01 kevlo Exp $
+-->
+
+<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 to use these examples directly.</para>
+
+ <para>These examples are not exhaustive&mdash;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/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</ulink>.</para>
+
+ <para>To avoid confusion, these examples use the standard DocBook 3.1 DTD
+ rather than the FreeBSD extension. They also use the stock stylesheets
+ distributed by Norm Walsh, rather than any customisations made to those
+ stylesheets by the FreeBSD Documentation Project. This makes them more
+ useful as generic DocBook examples.</para>
+
+ <sect1>
+ <title>DocBook <sgmltag>book</sgmltag></title>
+
+ <example>
+ <title>DocBook <sgmltag>book</sgmltag></title>
+
+ <programlisting><![ CDATA [<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.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>
+ <title>DocBook <sgmltag>article</sgmltag></title>
+
+ <example>
+ <title>DocBook <sgmltag>article</sgmltag></title>
+
+ <programlisting><![ CDATA [<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+
+<article>
+ <artheader>
+ <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>
+ </artheader>
+
+ <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>
+ <title>Producing formatted output</title>
+
+ <para>This section assumes that you have installed the software listed in
+ the <filename>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"> file.sgml > file.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
+ <abbrev>STDOUT</abbrev> (using Norm Walsh's stylesheets).</para>
+ </callout>
+
+ <callout arearefs="examples-co-jade-1-catalog">
+ <para>Specifies the catalogs that Jade 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-1-dsssl">
+ <para>Specifies the full path to the DSSSL stylesheet that Jade
+ will use when processing the document.</para>
+ </callout>
+
+ <callout arearefs="examples-co-jade-1-transform">
+ <para>Instructs Jade 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 Jade 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 Jade 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 Jade
+ will use when processing the document.</para>
+ </callout>
+
+ <callout arearefs="examples-co-jade-2-transform">
+ <para>Instructs Jade 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 Jade 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 -Vtex-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>Customises 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 Jade 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
+ Jade will use when processing the document.</para>
+ </callout>
+
+ <callout arearefs="examples-co-jade-3-tex">
+ <para>Instructs Jade 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>&amp;jadetex</literal> macro package.</para>
+
+ <screen>&prompt.user; <userinput>tex "&amp;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
+ <literal>LaTeX Warning: Reference `136' on page 5 undefined on input
+ line 728.</literal> 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 TeX as before. However, use the &amp;pdfjadetex macro package
+ instead.</para>
+
+ <screen>&prompt.user; <userinput>tex "&amp;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:
+-->