Index: head/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.xml =================================================================== --- head/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.xml (revision 52982) +++ head/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.xml (revision 52983) @@ -1,571 +1,571 @@ Die Erzeugung der Zieldokumente JohannKoisÜbersetzt von Dieses Kapitels erklärt detailliert, wie der Bau der Dokumentation organisiert ist und wie Sie diesen Prozess mit &man.make.1; beeinflussen können. DocBook in verschiedene Ausgabeformate konvertieren Aus einer einzigen DocBook-Quellcodedatei können verschiedene Ausgabeformate erstellt werden. Welches Dateiformat erstellt wird, wird über die Variable FORMATS festgelegt. Eine Liste aller verfügbaren Formate ist in KNOWN_FORMATS gespeichert: &prompt.user; cd ~/doc/en_US.ISO8859-1/books/handbook &prompt.user; make -V KNOWN_FORMATS Häufige Ausgabeformate FORMATS Dateityp Beschreibung html HTML, Einzeldatei Eine einzelne book.html oder article.html. html-split HTML, multiple Dateien Multiple HTML-Dateien, eine für jedes Kapitel oder für jeden Abschnitt. Dieser Typ wird in der Regel für die Nutzung des Dokuments auf einer Internetseite verwendet. pdf PDF Portable Document Format
Welches Format verwendet wird, hängt vom jeweiligen Dokument ab, in der Regel handelt es sich aber um html-split. Weitere Formate werden über die Variable FORMATS angegeben. Dabei können Sie ein einzelnes Format, aber auch mehrere Formate gleichzeitig definieren. Das Dokument als eine einzelne HTML-Seite bauen &prompt.user; cd ~/doc/en_US.ISO8859-1/books/handbook &prompt.user; make FORMATS=html Das Dokument in den Formaten HTML-Split sowie <acronym>PDF</acronym> bauen &prompt.user; cd ~/doc/en_US.ISO8859-1/books/handbook &prompt.user; make FORMATS="html-split pdf" Für den Bau der &os;-Dokumentation benötigte Werkzeuge Die folgende Werkzeuge werden benötigt, um die FDP-Dokumente zu bauen und zu installieren. Das wichtigste Werkzeug ist &man.make.1;, genauer Berkeley Make. Der Bau von Paketen erfolgt unter FreeBSD mit - &man.pkg.create.1;. + &man.pkg-create.8;. &man.gzip.1; dient zur Erstellung komprimierter Versionen der Dokumentation. &man.bzip2.1; wird ebenfalls unterstützt. Wollen Sie Pakete der Dokumentation erstellen, benötigen Sie auch &man.tar.1;. Mit &man.install.1; installieren Sie die Dokumentation auf Ihrem System. Die <filename>Makefile</filename>s des Dokumentationsbaums verstehen Innerhalb des &os; Documentation Projects gibt es drei verschiedene Arten von Makefiles: Ein Makefile in einem Unterverzeichnis gibt Anweisungen an dessen Dateien und Unterverzeichnisse weiter. Ein Dokument-Makefile beschreibt das Dokument, das aus dem Inhalt des jeweiligen Verzeichnisses gebaut werden soll. Make-Includes sind der "Klebstoff", der für den Bau der Dokumentation erforderlich ist. In der Regel heissen diese Dokumente doc.xxx.mk. Unterverzeichnis-<filename>Makefile</filename>s Derartige Makefiles sind in der Regel wie folgt aufgebaut: SUBDIR =articles SUBDIR+=books COMPAT_SYMLINK = en DOC_PREFIX?= ${.CURDIR}/.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" Die ersten vier nicht-leeren Zeilen definieren die &man.make.1;-Variablen SUBDIR, COMPAT_SYMLINK, und DOC_PREFIX. Die SUBDIR-Anweisung weist (ebenso wie die COMPAT_SYMLINK-Anweisung) einer Variable einen Wert zu und überschreibt dabei deren ursprünglichen Wert. Die zweite SUBDIR-Anweisung zeigt, wie man den aktuellen Wert einer Variable ergänzen kann. Nach der Ausführung dieser Anweisung hat die Variable SUBDIR den Wert articles books. Die Anweisung DOC_PREFIX zeigt, wie man einer Variable einen Wert zuweist (vorausgesetzt, die Variable ist nicht bereits definiert). Eine derartige Anweisung ist beispielsweise sinnvoll, wenn sich DOC_PREFIX nicht dort befindet, wo es vom Makefile erwartet wird. Durch das Setzen dieser Variable kann der korrekte Wert an das Makefile übergeben werden. Was heißt dies nun konkret? Mit den SUBDIR-Anweisungen legen Sie fest, welche Unterverzeichnisse beim Bau der Dokumentation eingeschlossen werden müssen. COMPAT_SYMLINK wird zur Erstellung von symbolischen Links zwischen den jeweiligen Dokumentsprachen und deren offizieller Kodierung benötigt (so wird beispielsweise doc/en nach en_US.ISO-8859-1 verlinkt). DOC_PREFIX gibt den Pfad zum Wurzelverzeichnis des Quellcode-Baums des FreeBSD Documentation Projects an. Diese Vorgabe kann jederzeit durch einen eigenen Wert ersetzt werden. Bei .CURDIR handelt es sich um eine in &man.make.1; eingebaute Variable, die den Pfad des aktuellen Verzeichnisses enthält. Die letzte Zeile bindet doc.project.mk, die zentrale, projektweite &man.make.1;-Datei des &os; Documentation Projects, in den Bau ein. Diese Datei enthält den "Klebstoff", der die diversen Variablen in Anweisungen zum Bau der Dokumentation konvertiert. Dokument-<filename>Makefile</filename>s Diese Makefiles definieren diverse make-Variablen mit Vorgaben zum Bau der im Verzeichnis enthaltenen Dokumentation. Dazu ein Beispiel: MAINTAINER=nik@FreeBSD.org DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # SGML content SRCS= book.xml DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk" Die Variable MAINTAINER ist von zentraler Bedeutung. Sie legt fest, wer für ein bestimmtes Dokument des FreeBSD Documentation Projects verantwortlich ist. DOC (ohne die Erweiterung .xml) ist der Name des Hauptdokuments des Verzeichnisses, in dem sich das Makefile befindet. Mit SRCS-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. Mit FORMATS geben Sie an, in welchen Formaten die Dokumentation gebaut werden soll. INSTALL_COMPRESSED enthält die Standardvorgaben, die beim Bau komprimierter Pakte der Dokumentation verwendet werden sollen. Der Variable INSTALL_ONLY_COMPRESS (die in der Voreinstellung leer ist) wird nur dann ein Wert zugewiesen, wenn ausschließlich komprimierte Pakete der Dokumentation erstellt werden sollen. Die Variable DOC_PREFIX und die verschiedenen Include-Anweisungen sollten Ihnen ebenfalls bereits vertraut sein. &man.make.1;-Includes des &os; Documentation Projects Diese Dateien lassen sich am besten verstehen, indem man sich deren Inhalt näher ansieht. Konkret handelt es sich dabei um folgende Dateien: doc.project.mk ist die Haupt-Include-Datei, die bei Bedarf alle folgenden Include-Dateien enthält. doc.subdir.mk sorgt dafür, dass alle benötigten Verzeichnisse (und Unterverzeichnisse) beim Bau der Dokumentation durchlaufen werden. doc.install.mk definiert Variablen, die die Installation der Dokumentation beeinflussen. doc.docbook.mk wird verwendet, wenn die Variable DOCFORMAT den Wert docbook hat und die Variable DOC gesetzt ist. - + <filename>doc.project.mk</filename> Diese Datei hat folgenden Aufbau: 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" - + Variablen DOCFORMAT und MAINTAINER enthalten Standardwerte, falls ihnen über das Dokument-Makefile keine anderen Werte zugewiesen werden. Bei PREFIX handelt es sich um das Präfix, unter dem die zum Bau der Dokumentation erforderlichen SGML-Werkzeuge installiert sind. In der Regel handelt es sich dabei um /usr/local. PRI_LANG 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". PRI_LANG beeinflusst nicht, 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. - + Bedingungen Die Zeile .if defined(DOC) ist ein Beispiel für eine &man.make.1;-Bedingung, die (analog zum Einsatz in anderen Programmen) festlegt, was geschehen soll, wenn eine Bedingung "wahr" oder "falsch" ist. defined ist eine Funktion, die zurückgibt, ob die angegebene Variable existiert oder nicht. .if ${DOCFORMAT} == "docbook" testet, ob die Variable DOCFORMAT den Wert "docbook" hat. Ist dies der Fall, wird doc.docbook.mk mit in den Bau aufgenommen. Die zwei .endifs schließen die zwei weiter oben definierten Bedingungen. - + <filename>doc.subdir.mk</filename> 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. - + Variablen SUBDIR legt die Unterverzeichnisse fest, deren Inhalt beim Bau der Dokumentation inkludiert werden muss. Mit ROOT_SYMLINKS 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 PRI_LANG festgelegt wird). COMPAT_SYMLINK wird im Abschnitt Unterverzeichnis-Makefiles beschrieben. - + Targets und Makros Abhängigkeiten (Dependencies) werden folgendermaßen definiert: target abhaengigkeit1 abhaengigkeit2 .... Um target zu bauen, müssen Sie zuvor die angegebenen Abhängigkeiten bauen. 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. Die spezielle Abhängigkeit .USE definiert das Äquivalent eines Makros. _SUBDIRUSE: .USE .for entry in ${SUBDIR} @${ECHO} "===> ${DIRPRFX}${entry}" @(cd ${.CURDIR}/${entry} && \ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor In diesem Beispiel kann _SUBDIRUSE nun als Makro, welches die angegebenen Befehle ausführt, verwendet werden, indem es im Makefile als Abhängigkeit angegeben wird. Was unterscheidet dieses Makro nun von beliebigen anderen Targets? Der Hauptunterschied ist, dass es nach den Anweisungen der Bauprozedur, in der es als Abhängigkeit angegeben ist, ausgeführt wird. Außerdem ändert es die Variable .TARGET (die den Namen des aktuell gebauten Targets enthält) nicht. clean: _SUBDIRUSE rm -f ${CLEANFILES} In diesem Beispiel führt clean das Makro _SUBDIRUSE aus, nachdem es den Befehl rm -f ${CLEANFILES} erfolgreich ausgeführt hat. Dadurch löscht clean zwar beim Wechsel in ein neues Unterverzeichnis beim Bau erstellte Dateien, aber nicht beim Wechsel aus einem Unterverzeichnis in ein übergeordnetes Verzeichnis. - + Vorhandene Targets install und package arbeiten nacheinander alle Unterverzeichnisse ab und rufen dabei jeweils ihre realen Versionen (realinstall beziehungsweise realpackage) auf. clean entfernt alle Dateien, die beim Bau der Dokumentation erzeugt wurden (dies sowohl im aktuellen Verzeichnis als auch in allen Unterverzeichnissen). cleandir hat die gleiche Aufgabe, würde aber zusätzlich die Objekt-Verzeichnisse löschen (falls diese existieren). - + Weitere Bedingungen exists gibt "wahr" zurück, wenn die angegebene Datei bereits existiert. empty gibt "wahr" zurück, wenn die angegebene Variable leer ist. target gibt "wahr" zurück, wenn das angegebene Target noch nicht existiert. - + Schleifenkonstrukte in <command>make (.for)</command> .for 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. _SUBDIRUSE: .USE .for entry in ${SUBDIR} @${ECHO} "===> ${DIRPRFX}${entry}" @(cd ${.CURDIR}/${entry} && \ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor Falls das Verzeichnis SUBDIR leer ist, würde in unserem Beispiel keine Aktion erfolgen. Enthält das Verzeichnis hingegen ein oder mehrere Elemente, werden die Anweisungen zwischen .for und .endfor für jedes Element ausgeführt, wobei entry durch das jeweilige Element ersetzt werden würde.