376 lines
14 KiB
XML
376 lines
14 KiB
XML
<?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>
|