doc/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- Copyright (c) 1999 Neil Blakey-Milner, 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 THE AUTHOR "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: r38845
-->

<chapter id="doc-build">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Johann</firstname>
	<surname>Kois</surname>
	<contrib>Übersetzt von </contrib>
      </author>
    </authorgroup>
  </chapterinfo>

  <title>Die Erzeugung der Zieldokumente</title>

  <para>Dieses Kapitels erklärt detailliert,
    <emphasis>wie der Bau der Dokumentation organisiert
    ist</emphasis> und <emphasis>wie Sie diesen Prozess beeinflussen
    können</emphasis>.</para>

  <para>Nachdem Sie dieses Kapitel gelesen haben, werden Sie:</para>

  <itemizedlist>
    <listitem>
      <para>Wissen, wie Sie (unter Verwendung der im Kapitel <link
	linkend="tools">SGML-Werkzeuge</link> beschriebenen Tools)
	die FDP-Dokumentation selbst bauen können.</para>
    </listitem>

    <listitem>
      <para>In der Lage sein, sowohl die
	<application>make</application>-Anweisungen der für
	jedes Dokument benötigten <filename>Makefile</filename>s
	als auch die Anweisungen der projektweiten Vorgaben der Datei
	<filename>doc.project.mk</filename> zu lesen und zu
	verstehen.</para>
    </listitem>

    <listitem>
      <para>Den Bau der Dokumentation über
	<application>make</application>-Variablen und
	<application>make</application>-Target anpassen
	können.</para>
    </listitem>
  </itemizedlist>

  <sect1 id="doc-build-toolset">
    <title>Für den Bau der FreeBSD-Dokumentation benötigte
      Werkzeuge</title>

    <para>Zusätzlich zu den im Kapitel <link
      linkend="tools">SGML-Werkzeuge</link> beschriebenen
      Werkzeugen benötigen Sie noch folgende Programme:</para>

    <itemizedlist>
      <listitem>
	<para>Das wichtigste Werzeug zum Bau der Dokumentation ist
	  <application>make</application>, genauer
	  <application>Berkeley Make</application>.</para>
      </listitem>

      <listitem>
	<para>Der Bau von Paketen erfolgt unter FreeBSD mit
	  <application>pkg_create</application>.  Wenn Sie ein
	  anderes Betriebssystem als FreeBSD einsetzen, müssen
	  Sie entweder ohne Pakete auskommen oder den Quellcode
	  selbst kompilieren.</para>
      </listitem>

      <listitem>
	<para><application>gzip</application> dient zur Erstellung
	  komprimierter Versionen der Dokumentation.  Unterstützt
	  werden sowohl <application>bzip2</application>- als auch
	  <application>zip</application>-Archive.  Wollen Sie Pakete
	  der Dokumentation erstellen, benötigen Sie auch noch
	  <application>tar</application>.</para>
      </listitem>

      <listitem>
	<para>Mit <application>install</application> installieren
	  Sie in der Standardeinstellung die Dokumentation auf Ihrem
	  System.  Es gibt aber auch alternative Wege, die Dokumentation
	  zu installieren.</para>
      </listitem>
    </itemizedlist>
 </sect1>

  <sect1 id="doc-build-makefiles">
    <title>Die <filename>Makefile</filename>s des Dokumentationsbaums
      verstehen</title>

    <para>Innerhalb des FreeBSD Documentation Projects gibt es drei
      verschiedene Arten von <filename>Makefile</filename>s:</para>

    <itemizedlist>
      <listitem>
	<para>Ein <link linkend="sub-make">
	  <filename>Makefile</filename></link> in einem
	  Unterverzeichnis gibt Anweisungen an dessen Dateien und
	  Unterverzeichnisse weiter.</para>
      </listitem>

      <listitem>
	<para>Ein <link linkend="doc-make">
	  Dokument-<filename>Makefile</filename></link> beschreibt das
	  Dokument, das aus dem Inhalt des jeweiligen Verzeichnisses
	  gebaut werden soll.</para>
      </listitem>

      <listitem>
	<para><link linkend="make-includes">
	  <application>Make</application>-Includes</link> sind der
	  "Klebstoff", der für den Bau der Dokumentation
	  erforderlich ist.  In der Regel heissen diese Dokumente
	  <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
      </listitem>
    </itemizedlist>

    <sect2 id="sub-make">
      <title>Unterverzeichnis-<filename>Makefile</filename>s</title>

      <para>Derartige <filename>Makefile</filename>s sind in der Regel
	wie folgt aufgebaut:</para>

      <programlisting>SUBDIR =articles
SUBDIR+=books

COMPAT_SYMLINK = en

DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>

      <para>Die ersten vier nicht-leeren Zeilen definieren die
	<application>make</application>-Variablen
	<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
	und <makevar>DOC_PREFIX</makevar>.</para>

      <para>Die erste <makevar>SUBDIR</makevar>-Anweisung weist
	(ebenso wie die <makevar>COMPAT_SYMLINK</makevar>-Anweisung)
	einer Variable einen Wert zu und überschreibt dabei
	deren ursprünglichen Wert.</para>

      <para>Die zweite <makevar>SUBDIR</makevar>-Anweisung zeigt,
	wie man den aktuellen Wert einer Variable ergänzen
	kann.  Nach der Ausführung dieser Anweisung hat die
	Variable <makevar>SUBDIR</makevar> den Wert
	<literal>articles books</literal>.</para>

      <para>Die Anweisung <makevar>DOC_PREFIX</makevar> zweigt, wie
	man einer Variable einen Wert zuweist (vorausgesetzt, die
	Variable ist nicht bereits definiert).  Eine derartige
	Anweisung ist beispielsweise sinnvoll, wenn sich
	<makevar>DOC_PREFIX</makevar> nicht dort befindet, wo es
	vom <filename>Makefile</filename> erwartet wird.
	Durch das Setzen dieser Variable kann der korrekte Wert an
	das Makefile übergeben werden.</para>

      <para>Was heißt dies nun konkret?  Mit den
	<makevar>SUBDIR</makevar>-Anweisungen legen Sie fest, welche
	Unterverzeichnisse beim Bau der Dokumentation eingeschlossen
	werden müssen.</para>

      <para><makevar>COMPAT_SYMLINK</makevar> wird zur Erstellung
	von symbolischen Links zwischen den jeweiligen Dokumentsprachen
	und deren offizieller Kodierung benötigt (so wird
	beispielsweise <filename>doc/en</filename> nach
	<filename>en_US.ISO-8859-1</filename> verlinkt).</para>

      <para><makevar>DOC_PREFIX</makevar> gibt den Pfad zum
	Wurzelverzeichnis des Quellcode-Baums des FreeBSD Documentation
	Projects an.  Diese Vorgabe kann jederzeit durch einen eigenen
	Wert ersetzt werden.  Bei <makevar>.CURDIR</makevar> handelt es
	sich um eine in <application>make</application> eingebaute
	Variable, die den Pfad des aktuellen Verzeichnisses
	enthält.</para>

      <para>Die letzte Zeile bindet <filename>doc.project.mk</filename>,
	die zentrale, projektweite <application>make</application>-Datei
	des FreeBSD Documentation Projects, in den Bau ein.  Diese Datei
	enthält den "Klebstoff", der die diversen Variablen in
	Anweisungen zum Bau der Dokumentation konvertiert.</para>

    </sect2>
    <sect2 id="doc-make">
      <title>Dokument-<filename>Makefile</filename>s</title>

      <para>Diese <filename>Makefile</filename>s definieren diverse
	<application>make</application>-Variablen mit Vorgaben
	zum Bau der im Verzeichnis enthaltenen Dokumentation.</para>

      <para>Dazu ein Beispiel:</para>

      <programlisting>MAINTAINER=nik@FreeBSD.org

DOC?= book

FORMATS?= html-split html

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

# SGML content
SRCS=  book.sgml

DOC_PREFIX?= ${.CURDIR}/../../..

.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>

      <para>Die Variable <makevar>MAINTAINER</makevar> ist von
	zentraler Bedeutung.  Sie legt fest, wer für ein
	bestimmtes Dokument des FreeBSD Documentation Projects
	verantwortlich ist.</para>

      <para><makevar>DOC</makevar> (ohne die Erweiterung
	<filename>.sgml</filename>) ist der Name des Hauptdokuments des
	Verzeichnisses, in dem sich das Makefile befindet.  Mit
	<makevar>SRCS</makevar>-Anweisungen geben Sie alle Dokumente an,
	aus denen das Dokument besteht.  Zusätzlich binden Sie
	damit wichtige Dateien ein, deren Änderung einen erneuten
	Bau der Dokumentation erforderlich macht.</para>

      <para>Mit <makevar>FORMATS</makevar> geben Sie an, in welchen
	Formaten die Dokumentation gebaut werden soll.
	<makevar>INSTALL_COMPRESSED</makevar> enthält die
	Standardvorgaben, die beim Bau komprimierter Pakte der
	Dokumentation verwendet werden sollen.  Der Variable
	<makevar>INSTALL_ONLY_COMPRESS</makevar> (die in der
	Voreinstellung leer ist) wird nur dann ein Wert zugewiesen,
	wenn ausschließlich komprimierte Pakete der Dokumentation
	erstellt werden sollen.</para>

      <note>
	<para>Die Zuweisung von Werten an verschiedene Variablen wurde
	  bereits im Abschnitt <link
	  linkend="sub-make">Unterverzeichnis-Makefiles</link>
	  behandelt.</para>
      </note>

      <para>Die Variable <makevar>DOC_PREFIX</makevar> und die
	verschiedenen Include-Anweisungen sollten Ihnen ebenfalls
	bereits vertraut sein.</para>
    </sect2>
  </sect1>

  <sect1 id="make-includes">
    <title><application>Make</application>-Includes des FreeBSD
      Documentation Projects</title>

    <para>Diese Dateien lassen sich am besten verstehen, indem man sich
      deren Inhalt näher ansieht.  Konkret handelt es sich dabei
      um folgende Dateien:</para>

    <itemizedlist>
      <listitem>
	<para><filename>doc.project.mk</filename> ist die
	  Haupt-Include-Datei, die bei Bedarf alle folgenden
	  Include-Dateien enthält.</para>
      </listitem>

      <listitem>
	<para><filename>doc.subdir.mk</filename> sorgt dafür, dass
	  alle benötigten Verzeichnisse (und Unterverzeichnisse)
	  beim Bau der Dokumentation durchlaufen werden.</para>
      </listitem>

      <listitem>
	<para><filename>doc.install.mk</filename> definiert Variablen,
	  die die Installation der Dokumentation beeinflussen.</para>
      </listitem>

      <listitem>
	<para><filename>doc.docbook.mk</filename> wird verwendet, wenn
	  die Variable <makevar>DOCFORMAT</makevar> den Wert
	  <literal>docbook</literal> hat und und die Variable
	  <makevar>DOC</makevar> gesetzt ist.</para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title><filename>doc.project.mk</filename></title>

      <para>Diese Datei hat folgenden Aufbau:</para>

      <programlisting>DOCFORMAT?=	docbook
MAINTAINER?=	doc@FreeBSD.org

PREFIX?=	/usr/local
PRI_LANG?=	en_US.ISO8859-1

.if defined(DOC)
.if ${DOCFORMAT} == "docbook"
.include "doc.docbook.mk"
.endif
.endif

.include "doc.subdir.mk"
.include "doc.install.mk"</programlisting>

      <sect3>

	<title>Variablen</title>

	<para><makevar>DOCFORMAT</makevar> und <makevar>MAINTAINER</makevar>
	  enthalten Standardwerte, falls ihnen über das
	  Dokument-Makefile keine anderen Werte zugewiesen werden.</para>

	<para>Bei <makevar>PREFIX</makevar> handelt es sich um das
	  Präfix, unter dem die zum Bau der Dokumentation
	  erforderlichen <link linkend="tools">SGML-Werkzeuge</link>
	  installiert sind.  In der Regel handelt es sich dabei um
	  <filename>/usr/local</filename>.</para>

	<para><makevar>PRI_LANG</makevar> sollte auf die Sprache und
	  Kodierung eingestellt werden, die unter den Leser der
	  Dokumentation am häufigsten verwendet wird.  Diese
	  Variable hat den Standardwert "US English".</para>

	<note>
	  <para><makevar>PRI_LANG</makevar> beeinflusst in keinster
	    Weise, welche Dokumente gebaut werden können oder
	    sollen.  Diese Variable wird lediglich dazu verwendet,
	    häufig verwendete Dokumente in das Wurzelverzeichnis
	    der installierten Dokumentation zu verlinken.</para>
	</note>
      </sect3>

      <sect3>
	<title>Bedingungen</title>

	<para>Die Zeile <literal>.if defined(DOC)</literal> ist ein
	  Beispiel für eine
	  <application>make</application>-Bedingung, die (analog zum
	  Einsatz in anderen Programmen) festlegt, was geschehen soll,
	  wenn eine Bedingung "wahr" oder "falsch" ist.
	  <literal>defined</literal> ist eine Funktion, die
	  zurückgibt, ob die angegebene Variable existiert oder
	  nicht.</para>

	<para><literal>.if ${DOCFORMAT} == "docbook"</literal> testet,
	  ob die Variable <makevar>DOCFORMAT</makevar> den Wert
	  <literal>"docbook"</literal> hat.  Ist dies der Fall, wird
	  <filename>doc.docbook.mk</filename> mit in den Bau
	  aufgenommen.</para>

	<para>Die zwei <literal>.endif</literal>s schließen die
	  zwei weiter oben definierten Bedingungen.</para>
      </sect3>
    </sect2>

    <sect2>
      <title><filename>doc.subdir.mk</filename></title>

      <para>Den Inhalt dieser Datei hier zu beschreiben, würde
	zu weit führen.  Sie sollten aber nach dem Lesen der
	vorangegangenen Abschnitte und der folgenden Ausführungen
	in der Lage sein, Inhalt und Aufgabe dieser Datei zu
	verstehen.</para>

      <sect3>
	<title>Variablen</title>

	<itemizedlist>
	  <listitem>
	    <para><makevar>SUBDIR</makevar> legt die Unterverzeichnisse
	      fest, deren Inhalt beim Bau der Dokumentation inkludiert
	      werden muss.</para>
	  </listitem>

	  <listitem>
	    <para>Mit <makevar>ROOT_SYMLINKS</makevar> wird der Name der
	      Verzeichnisse angegeben, die von ihrer tatsächlichen
	      Position aus in das Wurzelverzeichnis, unter dem die
	      Dokumentation installiert wird, verlinkt werden sollen.
	      Vorausgesetzt, bei der verwendeten Sprache handelt es sich
	      um die primäre Sprache (die über
	      <makevar>PRI_LANG</makevar> festgelegt wird).</para>
	  </listitem>

	  <listitem>
	    <para><makevar>COMPAT_SYMLINK</makevar> wird im Abschnitt
	      <link linkend="sub-make">Unterverzeichnis-Makefile</link>s
	      beschrieben.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Targets und Makros</title>

	<para>Abhängigkeiten
	  (<foreignphrase>Dependencies</foreignphrase>) werden
	  folgendermaßen definiert:
	  <literal><replaceable>target</replaceable>
	  <replaceable>abhaengigkeit1 abhaengigkeit2 ...</replaceable></literal>.
	  Um <literal>target</literal> zu bauen, müssen Sie zuvor
	  die angegebenen Abhängigkeiten bauen.</para>

	<para>Daran anschließend können Anweisungen zum
	  Bau des angegebenen Targets folgen, falls der
	  Konvertierungsprozess zwischen dem Target und seinen
	  Abhängigkeiten nicht bereits früher definiert
	  wurde oder falls die Konvertierung nicht der
	  Standardkonvertierungsmethode entspricht.</para>

	<para>Die spezielle Abhängigkeit <literal>.USE</literal>
	  definiert das Äquivalent eines Makros.</para>

<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===&gt; ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} &amp;&amp; \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>

	<para>In diesem Beispiel kann <maketarget>_SUBDIRUSE</maketarget>
	  nun als Makro, welches die angegebenen Befehle ausführt,
	  verwendet werden, indem es im Makefile als Abhängigkeit
	  angegeben wird.</para>

	<para>Was unterscheidet dieses Makro nun von beliebigen anderen
	  Targets?  Der Hauptunterschied ist, dass es
	  <emphasis>nach</emphasis> den Anweisungen der Bauprozedur,
	  in der es als Abhängigkeit angegeben ist, ausgeführt
	  wird.  Außerdem ändert es die Variable
	  <makevar>.TARGET</makevar> (die den Namen des aktuell gebauten
	  Targets enthält) nicht.</para>

<programlisting>clean: _SUBDIRUSE
	rm -f ${CLEANFILES}</programlisting>

	<para>In diesem Beispiel führt <maketarget>clean</maketarget>
	  das Makro <maketarget>_SUBDIRUSE</maketarget> aus, nachdem es
	  den Befehl <command>rm -f ${CLEANFILES}</command> erfolgreich
	  ausgeführt hat.  Dadurch löscht
	  <maketarget>clean</maketarget> zwar beim Wechsel in ein neues
	  <emphasis>Unterverzeichnis</emphasis> beim Bau erstellte
	  Dateien, aber nicht beim Wechsel aus einem Unterverzeichnis
	  in ein übergeordnetes Verzeichnis.</para>

	<sect4>
	  <title>Vorhandene Targets</title>

	  <itemizedlist>
	    <listitem>
	      <para><maketarget>install</maketarget> und
		<maketarget>package</maketarget> arbeiten nacheinander
		alle Unterverzeichnisse ab und rufen dabei jeweils ihre
		realen Versionen (<maketarget>realinstall</maketarget>
		beziehungsweise <maketarget>realpackage</maketarget>)
		auf.</para>
	    </listitem>

	    <listitem>
	      <para><maketarget>clean</maketarget> entfernt alle
		Dateien, die beim Bau der Dokumentation erzeugt wurden
		(dies sowohl im aktuellen Verzeichnis als auch in allen
		Unterverzeichnissen).  <maketarget>cleandir</maketarget>
		hat die gleiche Aufgabe, würde aber zusätzlich
		die Objekt-Verzeichnisse löschen (falls diese
		existieren).</para>
	    </listitem>
	  </itemizedlist>
	</sect4>
      </sect3>

      <sect3>
	<title>Weitere Bedingungen</title>

	<itemizedlist>
	  <listitem>
	    <para><literal>exists</literal> gibt "wahr" zurück, wenn
	      wenn die angegebene Datei bereits existiert.</para>
	  </listitem>

	  <listitem>
	    <para><literal>empty</literal> gibt "wahr" zurück, wenn
	      die angegebene Variable leer ist.</para>
	  </listitem>

	  <listitem>
	    <para><literal>target</literal> gibt "wahr" zurück, wenn
	      das angegebene Target noch nicht existiert.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Schleifenkonstrukte in
	  <command>make (.for)</command></title>

	<para><literal>.for</literal> erlaubt es, bestimmte
	  Anweisungen für jedes Element einer Variable zu
	  wiederholen, indem dieser Variable in jedem Durchlauf
	  der Schleife das jeweilige Element der untersuchten Liste
	  zugewiesen wird.</para>

<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===&gt; ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} &amp;&amp; \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor</programlisting>

	<para>Falls das Verzeichnis <makevar>SUBDIR</makevar> leer ist,
	  würde in unserem Beispiel keine Aktion erfolgen.
	  Enthält das Verzeichnis hingegen ein oder mehrere
	  Elemente, werden die Anweisungen zwischen
	  <literal>.for</literal> und <literal>.endfor</literal>
	  für jedes Element ausgeführt, wobei
	  <makevar>entry</makevar> durch das jeweilige Element ersetzt
	  werden würde.</para>
      </sect3>
    </sect2>
  </sect1>
</chapter>