<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- 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$
$FreeBSDde$
basiert auf: r38847
-->
<appendix id="examples">
<title>Beispiele</title>
<para>In diesem Anhang sind SGML-Beispieldokumente und Befehle
enthalten, die zeigen, wie man aus DocBook-Dokumenten verschiedene
Ausgabeformate erzeugen kann. Sofern alle Werkzeuge f�r das
Dokumentationsprojekt ordnungsgem�� installiert wurden,
k�nnen die angebotenen Beispiele direkt �bernommen
werden.</para>
<para>Die Beispiele dieses Abschnitts sind bewusst einfach aufgebaut.
Daher fehlen in den Beispielen einige Elemente, insbesondere
Elemente f�r die Titelei. Weitere DocBook-Beispiele
k�nnen in den DocBook-Quellen dieses und anderer Dokumente
des FDPs gefunden werden. Die Quellen des FDPs sind im
<application>svn</application> doc-Repository und online unter <ulink
url="http://svnweb.FreeBSD.org/doc/"></ulink> verf�gbar.</para>
<para>Um Irritationen zu vermeiden, bauen die SGML-Beispiele auf der
4.1er Standard-DocBook DTD anstatt auf der erweiterten
FreeBSD-Variante auf. Ebenso werden die Standardstylesheets von
Norman Welsh, anstatt der angepassten Stylesheets des
FreeBSD-Dokumentationsprojektes benutzt. Dadurch eignen sich die
Beispiele auch als generische DocBook-Vorlagen.</para>
<sect1 id="examples-docbook-book">
<title>DocBook-Buch (<sgmltag>book</sgmltag>)</title>
<example>
<title>Ein DocBook-Buch (<sgmltag>book</sgmltag>)</title>
<programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book lang='de'>
<bookinfo>
<title>Ein Buchbeispiel</title>
<author>
<firstname>Vorname</firstname>
<surname>Nachname</surname>
<affiliation>
<address><email>vorname.nachname@domain.de</email></address>
</affiliation>
</author>
<copyright>
<year>2000</year>
<holder>Urheberhinweis</holder>
</copyright>
<abstract>
<para>Falls das Buch eine Zusammenfassung hat, sollte sie
hier stehen.</para>
</abstract>
</bookinfo>
<preface>
<title>Einleitung</title>
<para>Falls das Buch eine Einleitung hat, sollte diese hier
stehen.</para>
</preface>
<chapter>
<title>Das erste Kapitel</title>
<para>Das ist das erste Kapitel des Buches.</para>
<sect1>
<title>Der erste Abschnitt</title>
<para>Das ist der erste Abschnitte des Buches.</para>
</sect1>
</chapter>
</book>]]></programlisting>
</example>
</sect1>
<sect1 id="examples-docbook-article">
<title>DocBook-Artikel (<sgmltag>article</sgmltag>)</title>
<example>
<title>Ein DocBook-Artikel (<sgmltag>article</sgmltag>)</title>
<programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article lang='de'>
<articleinfo>
<title>Ein Beispielartikel</title>
<author>
<firstname>Vorname</firstname>
<surname>Nachname</surname>
<affiliation>
<address><email>vorname.nachname@domain.de</email></address>
</affiliation>
</author>
<copyright>
<year>2000</year>
<holder>Urheberhinweis</holder>
</copyright>
<abstract>
<para>Falls der Artikel eine Zusammenfassung hat, sollte sie
hier stehen.</programlisting>
</abstract>
</articleinfo>
<sect1>
<title>Der erste Abschnitt</title>
<para>Das ist der erste Abschnitt des Artikels.</para>
<sect2>
<title>Der erste Unterabschnitt</title>
<para>Das ist der erste Unterabschnitt des Artikels.</para>
</sect2>
</sect1>
</article>]]></programlisting>
</example>
</sect1>
<sect1 id="examples-formatted">
<title>Ausgabeformate erzeugen</title>
<para>F�r diesen Abschnitt wird vorausgesetzt, dass die
im Port <filename role="package">textproc/docproj</filename>
enthaltene Software manuell oder �ber das Portssystem
installiert wurde. Weiter wird vorausgesetzt, dass alle
Programme unterhalb des Verzeichnisses
<filename class="directory">/usr/local</filename> installiert
worden sind und die Verzeichnisse, die die ausf�hrbaren
Programme enthalten, in der Variable <envar>PATH</envar>
enthalten sind.</para>
<sect2>
<title>Benutzung von Jade</title>
<example>
<title>Ein DocBook-Dokument in eine einzelne HTML-Datei
umwandeln</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>datei</replaceable>.sgml > <replaceable>datei</replaceable>.html <co id="examples-co-jade-1-filename"/></userinput></screen>
<calloutlist>
<callout arearefs="examples-co-jade-1-nochunks">
<para>�bergibt den Parameter
<literal>nochunks</literal> an die Stylesheets. Dadurch
wird die gesamte Ausgabe in die Standardausgabe
geschrieben (bei der Benutzung
von Norm Walshs Stylesheets).</para>
</callout>
<callout arearefs="examples-co-jade-1-catalog">
<para>Legt die von <application>Jade</application> zur
Verarbeitung ben�tigten
drei Kataloge fest. Der erste Katalog enth�lt
Informationen zu den DSSSL-Stylesheets, der zweite zur
DocBook DTD und der dritte
<application>Jade</application>-spezifische Informationen.</para>
</callout>
<callout arearefs="examples-co-jade-1-dsssl">
<para>�bergibt den vollen Pfad zum
DSSSL-Stylesheet, das von <application>Jade</application> zur
Verarbeitung des Dokuments benutzt wird.</para>
</callout>
<callout arearefs="examples-co-jade-1-transform">
<para>Weist <application>Jade</application> an, eine
<emphasis>Transformation</emphasis> von einer DTD zu
einer anderen DTD vorzunehmen. In diesem Falle, von der
DocBook DTD zur HTML DTD.</para>
</callout>
<callout arearefs="examples-co-jade-1-filename">
<para>Legt fest, welche Datei <application>Jade</application>
verarbeiten soll und leitet die Ausgabe in die Datei
<filename>datei.html</filename> um.</para>
</callout>
</calloutlist>
</example>
<example>
<title>Ein DocBook-Dokument in mehrere kleine HTML-Dateien umwandeln</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>datei</replaceable>.sgml <co id="examples-co-jade-2-filename"/></userinput></screen>
<calloutlist>
<callout arearefs="examples-co-jade-2-catalog">
<para>Legt die von <application>Jade</application>
zur Verarbeitung ben�tigten
drei Kataloge fest. Der erste Katalog enth�lt
Informationen zu den DSSSL-Stylesheets, der zweite zur
DocBook DTD und der dritte Jade-spezifische
Informationen.</para>
</callout>
<callout arearefs="examples-co-jade-2-dsssl">
<para>�bergibt den vollen Pfad zum
DSSSL-Stylesheet, das von
<application>Jade</application> zur
Verarbeitung des Dokuments benutzt wird.</para>
</callout>
<callout arearefs="examples-co-jade-2-transform">
<para>Weist <application>Jade</application> an, eine
<emphasis>Transformation</emphasis> von einer DTD zu
einer anderen DTD vorzunehmen. In diesem Falle, von der
DocBook DTD zur HTML DTD.</para>
</callout>
<callout arearefs="examples-co-jade-2-filename">
<para>Legt die zu verarbeitende Datei fest. Die
Stylesheets ermitteln eigenst�ndig die Namen aller
HTML-Ausgabedateien.</para>
</callout>
</calloutlist>
<para>Abh�ngig von der Struktur des zu verarbeitenden
Dokumentes und den Stylesheetregeln zur Aufteilung des
Dokumentes, kann dieser Befehl auch nur eine einzelne
HTML-Datei erzeugen.</para>
</example>
<example id="examples-docbook-postscript">
<title>Ein DocBook-Dokument nach Postscript umwandeln</title>
<para>Um eine Postscript-Ausgabe zu erzeugen, muss zuerst
die SGML-Quelle in eine &tex;-Datei umgewandelt werden.</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>datei</replaceable>.sgml</userinput></screen>
<calloutlist>
<callout arearefs="examples-co-jade-3-tex-backend">
<para>Weist die Stylesheets an, verschiedene
&tex;-spezifische Optionen zu benutzen.</para>
</callout>
<callout arearefs="examples-co-jade-3-catalog">
<para>Legt die von <application>Jade</application>
zur Verarbeitung ben�tigten
drei Kataloge fest. Der erste Katalog enth�lt
Informationen zu den DSSSL-Stylesheets, der zweite zur
DocBook DTD und der dritte Jade-spezifische
Informationen.</para>
</callout>
<callout arearefs="examples-co-jade-3-dsssl">
<para>�bergibt den vollen Pfad zum
DSSSL-Stylesheet, das von
<application>Jade</application> zur
Verarbeitung des Dokuments benutzt wird.</para>
</callout>
<callout arearefs="examples-co-jade-3-tex">
<para>Weist <application>Jade</application> an,
die Ausgabe in eine &tex;-Datei umzuwandeln.</para>
</callout>
</calloutlist>
<para>Die so erzeugte <filename>.tex</filename>-Datei
muss anschlie�end mittels <command>tex</command>,
unter Angabe des Makropakets
<literal>&jadetex</literal> weiterverarbeitet
werden.</para>
<screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>datei</replaceable>.tex</userinput></screen>
<para><command>tex</command> muss <emphasis>mindestens</emphasis>
dreimal ausgef�hrt werden. Der erste Lauf ermittelt die
die Querverweise innerhalb des Dokumentes, die
f�r Stichwortverzeichnisse und �hnliches
ben�tigt werden.</para>
<para>Warnungen, wie <errorname>LaTeX Warning: Reference `136'
on page 5 undefined on input line 728.</errorname>, die zu
diesem Zeitpunkt ausgegeben werden, k�nnen ohne
weiteres ignoriert werden.</para>
<para>Der zweite Lauf kann jetzt, da mehr Informationen, wie
zum Beispiel die Seitenl�ngen, zur Verf�gung
stehen, Eintr�ge im Stichwortverzeichnis und
Querverweise genauer bestimmen.</para>
<para>Der dritte Lauf ist f�r abschlie�ende
Aufr�umarbeiten notwendig. Die so von
<command>tex</command> erzeugte Ausgabe befindet sich
anschlie�end in der Datei
<filename><replaceable>datei</replaceable>.div</filename>.</para>
<para>Zum Schluss muss noch <command>dvips</command>
aufgerufen werden, um die <filename>.div</filename>-Datei in
ein Postscript-Dokument umzuwandeln.</para>
<screen>&prompt.user; <userinput>dvips -o <replaceable>datei</replaceable>.ps <replaceable>datei.dvi</replaceable></userinput></screen>
</example>
<example>
<title>Eine PDF-Datei aus einem DocBook-Dokument
erzeugen</title>
<para>Die ersten Schritte, um ein DocBook-Dokument in ein PDF
umzuwandeln, stimmen mit denen �berein, die notwendig sind,
um eine Postscript-Ausgabe zu erzeugen (<xref
linkend="examples-docbook-postscript"/>).</para>
<para>Nachdem die <filename>.tex</filename>-Datei durch
<application>Jade</application> erzeugt wurde, muss
<application>pdfTeX</application> stattdessen mit dem
Makropaket <literal>&pdfjadetex</literal> aufgerufen
werden.</para>
<screen>&prompt.user; <userinput>pdftex "&pdfjadetex" <replaceable>datei</replaceable>.tex</userinput></screen>
<para>Dieser Befehl muss ebenfalls dreimal ausgef�hrt werden.
Am Ende liegt mit
<filename><replaceable>datei</replaceable>.pdf</filename>
das fertige PDF-Dokument vor. Weitere Schritte sind jetzt
nicht mehr notwendig.</para>
</example>
</sect2>
</sect1>
</appendix>