<!-- 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: de-docproj/books/fdp-primer/examples/appendix.sgml,v 1.11 2005/04/03 23:44:24 mheinen Exp $
     basiert auf: 1.11
-->

<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&uuml;r das
    Dokumentationsprojekt ordnungsgem&auml;&szlig; installiert wurden,
    k&ouml;nnen die angebotenen Beispiele direkt &uuml;bernommen
    werden.</para>

  <para>Die Beispiele dieses Abschnitts sind bewusst einfach aufgebaut.
    Daher fehlen in den Beispielen einige Elemente, insbesondere
    Elemente f&uuml;r die Titelei.  Weitere DocBook-Beispiele
    k&ouml;nnen in den DocBook-Quellen dieses und anderer Dokumente
    des FDPs gefunden werden. Die Quellen des FDPs sind &uuml;ber
    <application>CVSup</application> und online unter <ulink
      url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</ulink>
    verf&uuml;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>
  <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>
  <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&uuml;r diesen Abschnitt wird vorausgesetzt, dass die
      im Port <filename role="package">textproc/docproj</filename>
      enthaltene Software manuell oder &uuml;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&uuml;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"> datei.sgml &gt; datei.html <co id="examples-co-jade-1-filename"></userinput></screen>

	<calloutlist>
	  <callout arearefs="examples-co-jade-1-nochunks">
            <para>&Uuml;bergibt den Parameter
              <literal>nochunks</literal> an die Stylesheets. Dadurch
              wird die gesamte Ausgabe nach
              <abbrev>STDOUT</abbrev> geschrieben (bei der Benutzung
              von Norm Walshs Stylesheets).</para>
	  </callout>

	  <callout arearefs="examples-co-jade-1-catalog">
            <para>Legt die von Jade zur Verarbeitung ben&ouml;tigten
              drei Kataloge fest. Der erste Katalog enth&auml;lt
              Informationen zu den DSSSL-Stylesheets, der zweite zur
              DocBook DTD und der dritte Jade-spezifische
              Informationen.</para>
	  </callout>

	  <callout arearefs="examples-co-jade-1-dsssl">
            <para>&Uuml;bergibt den vollen Pfad zum
	      DSSSL-Stylesheet, das von Jade zur
	      Verarbeitung des Dokuments benutzt wird.</para>
	  </callout>

	  <callout arearefs="examples-co-jade-1-transform">
            <para>Weist Jade 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 Jade 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 Jade zur Verarbeitung ben&ouml;tigten
              drei Kataloge fest. Der erste Katalog enth&auml;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>&Uuml;bergibt den vollen Pfad zum
	      DSSSL-Stylesheet, das von Jade zur
	      Verarbeitung des Dokuments benutzt wird.</para>
          </callout>

	  <callout arearefs="examples-co-jade-2-transform">
            <para>Weist Jade 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&auml;ndig die Namen aller
              HTML-Ausgabedateien.</para>
	  </callout>
	</calloutlist>

        <para>Abh&auml;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 -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>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 Jade zur Verarbeitung ben&ouml;tigten
              drei Kataloge fest. Der erste Katalog enth&auml;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>&Uuml;bergibt den vollen Pfad zum
	      DSSSL-Stylesheet, das von Jade zur
	      Verarbeitung des Dokuments benutzt wird.</para>
	  </callout>

	  <callout arearefs="examples-co-jade-3-tex">
            <para>Weist Jade an, die Ausgabe in &tex;
              umzuwandeln.</para>
          </callout>
	</calloutlist>

        <para>Die so erzeugte <filename>.tex</filename>-Datei
          muss anschlie&szlig;end mittels <command>tex</command>,
          unter Angabe des Makropakets
          <literal>&amp;jadetex</literal> weiterverarbeitet
          werden.</para>

	<screen>&prompt.user; <userinput>tex "&amp;jadetex" <replaceable>datei</replaceable>.tex</userinput></screen>

        <para><command>tex</command> muss <emphasis>mindestens</emphasis>
          dreimal ausgef&uuml;hrt werden. Der erste Lauf ermittelt die
          die Querverweise innerhalb des Dokumentes, die
          f&uuml;r Stichwortverzeichnisse und &auml;hnliches
	  ben&ouml;tigt werden.</para>

        <para>Warnungen, wie <literal>LaTeX Warning: Reference `136'
            on page 5 undefined on input line 728.</literal>, die zu
          diesem Zeitpunkt ausgegeben werden, k&ouml;nnen ohne
          weiteres ignoriert werden.</para>

        <para>Der zweite Lauf kann jetzt, da mehr Informationen, wie
          zum Beispiel die Seitenl&auml;ngen, zur Verf&uuml;gung
          stehen, Eintr&auml;ge im Stichwortverzeichnis und
          Querverweise genauer bestimmen.</para>

        <para>Der dritte Lauf ist f&uuml;r abschlie&szlig;ende
          Aufr&auml;umarbeiten notwendig. Die so von
          <command>tex</command> erzeugte Ausgabe befindet sich
          anschlie&szlig;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 &uuml;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
          pdfTex mit mit &amp;pdfjadetex-Paket anstelle von tex
          aufgerufen werden.</para>

	<screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" <replaceable>datei</replaceable>.tex</userinput></screen>

        <para>Dieser Befehl muss ebenfalls dreimal ausgef&uuml;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>

<!--
     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:
-->
