NAME¶

po4a-build.conf - Konfigurationsdatei zur Erstellung übersetzter Inhalte

Einleitung¶

po4a-build.conf beschreibt, wie "po4a-build" die übersetzte und die unübersetzte Dokumentation aus einer Sammlung an Quelldokumenten und zugehörigen PO-Dateien bauen soll. Alle unterstützten Formate in allen unterstützten Kombinationen können in einer einzigen Konfigurationsdatei po4a-build.conf und mit einem einzigen Aufruf von "po4a-build" verwandt werden. Sie können sich aber auch dafür entscheiden, die po/-Verzeichnisse zu trennen und eine einzelne Konfigurationsdatei für jeden Aufruf zu verwenden. (Rufen Sie "po4a-build -f DATEI" für jede Konfigurationsdatei auf) Beachten Sie, dass po4a-build zwar Unterstützung für das Hinzufügen von Gettext-Unterstützung zur Übersetzung von Skriptausgabenachrichten enthält, allerdings po4a-build.conf keinen Einfluss auf solche Übersetzungen hat. po4a-build.conf ist nur für die Übersetzung von statischen Inhalten wie Handbuchseiten zuständig. Für Informationen über die Unterstützung der Übersetzung von Nachrichten zur Programmlaufzeit durch po4a-build lesen Sie po4a-runtime(7).

Unterstützte Formate¶

Derzeit unterstützt "po4a-build" die folgenden Kombinationen:

DocBook XML für Abschnitt 1 und 3

Typischerweise für Handbuchseiten für Shell-Skripte oder andere Interpreter verwandt, die über keine eigenen Dokumentationsformate wie POD verfügen. Geeignetes XML kann direkt aus einer existierenden Handbuchseite mittels "doclifter" erstellt werden und "po4a-build" wird dann eine POT-Datei ohne zusätzlichen Arbeitsaufwand generiert. Die POT-Datei kann dann zur Übersetzung angeboten und die PO-Dateien dem relevanten po/-Verzeichnis hinzugefügt werden. "po4a-build" wird dann nicht nur die unübersetzte Handbuchseite aus dem "doclifter"-XML erstellen, sondern auch "po4a" verwenden, um übersetztes XML aus der PO-Datei zu generieren und dann die übersetzten Handbuchseiten aus dem XML zu bauen.

Handbuchseiten werden mit der standardmäßigen Unterstützung in Docbook-xsl gebaut - das zu verwendende Stylesheet kann mit der "XSLFILE"-Einstellung in der Konfigurationsdatei "po4a-build" überschrieben werden.

DocBook XML für HTML

Das standardmäßige Stylesheet, das zur Erstellung des abschließenden HTMLs verwandt wird, kann mit der Einstellung "HTMLXSL" in der Konfigurationsdatei "po4a-build" überschrieben werden.

POD für Abschnitt 1, 3, 5 und 7

Pod2man wird zum Konvertieren von POD-Inhalten für jeden unterstützten Abschnitt verwandt.

Verwenden Sie "PODFILE" für Abschnitt 1, "PODMODULES" für Abschnitt 3, "POD5FILES" für Abschnitt 5 und "POD7FILES" für Abschnitt 7.

Für Inhalte in den Abschnitten 5 oder 7 (wo oft ein Dateiname benötigt wird, der auch für Inhalte in Abschnitt 1 verwandt wird) wird, wenn der Dateiname »5« oder »7« als Teil des Dateinamens enthält, diese Nummer (und alle Dateinamenerweiterungen) automatisch entfernt.

Wird z.B. /usr/share/man/man7/po4a.7.gz vorbereitet:

 # POD-Dateien für Abschnitt 7
 POD7FILES="doc/po4a.7.pod"
    

Dateiinhalte¶

Konfigurationswerte können in jeder Reihenfolge in der Konfigurationsdatei auftauchen. Alle Inhalte nach einem »#« werden ignoriert. Jeder Wert, der immer leer wäre, kann aus der Datei entfallen. Einige Konfigurationsfelder müssen angegeben werden - po4a-build könnte im Nichts enden, falls erforderliche Felder leer sind.

CONFIG

Erforderlich

Name und Ort der (temporären) "po4a"-Konfigurationsdatei, die "po4a-build" erstellen und verwalten wird. Diese Datei muss nicht in Ihrem Versionskontrollsystem gepflegt werden und kann während der Paketerstellung problemlos aufgeräumt werden.

 # Name und Ort der Konfigurationsdatei
 CONFIG="_build/po4a.config"
    

PODIR

Erforderlich

Verzeichnis, das die PO-Dateien für ALLE Übersetzungen enthält, die von dieser Konfigurationsdatei verarbeitet werden. Alle Zeichenketten werden in eine POT-Datei in diesem Verzeichnis zusammengeführt und alle PO-Dateien werden mit dieser POT-Datei zusammengeführt. »KEEP«-Schwellwerte (siehe unten) werden auf alle Zeichenketten von allen in dieser Datei angegebenen Eingabedateien und allen PO-Dateien in diesem Verzeichnis angewandt. Das Verzeichnis muss nicht »po« heißen. Bitte beachten Sie allerdings, dass einige Statistikwerkzeuge erwarten, dass der Name »po« lauten sollte, daher wird empfohlen, diesen Namen beizubehalten.

 # PO-Verzeichnis für Handbuchseiten/Dokumentation
 PODIR="po/pod"
    

POTFILE

Erforderlich

Pfad zur POT-Datei (relativ zu der Lage dieser Konfigurationsdatei), die durch "po4a-build" für diese Übersetzung erstellt, gewartet und aktualisiert wird.

 # POT-Dateipfad
 POTFILE="po/pod/po4a-pod.pot"
    

BASEDIR

Erforderlich

Basisverzeichnis zum Schreiben der übersetzten Inhalte.

 # Basisverzeichnis für erstellte Dateien, z.B. dok
 BASEDIR="_build"
    

BINARIES

Erforderlich

Selbst falls nur ein Paket gebaut wird, wird mindestens ein Wert hier benötigt.

Die Zeichenkette ist beliebig, besteht aber typischerweise aus dem Paketnamen. Erstellte Inhalte werden dann in Unterverzeichnissen von BASEDIR/BINARIES gespeichert:

 _build/po4a/man/man1/foo.1
    

Falls das Paket mehr als ein Binärpaket baut (d.h. ein Quellpaket und mehrere .deb- oder .rpm-Dateien), kann dieses Feld dabei helfen, Inhalte für jedes Ziel abzugrenzen und damit die Automatisierung des Bauprozesses zu erleichtern.

Zeichenketten mit Leerzeichen trennen.

 # Binärpakete, die erstellte Handbuchseiten enthalten werden
 BINARIES="po4a"
    

KEEP

Wert, der direkt an "po4a -k" übergeben wird, um den Schwellwert für den korrekt übersetzten Inhalt anzugeben, bevor eine bestimmte Übersetzung beim Bauen ausgeschlossen wird. Lassen Sie dies leer oder entfernen Sie es, um den Standardwert (80%) zu verwenden oder geben Sie Null an, um allen Inhalt aufzunehmen, selbst falls er vollständig unübersetzt ist.

Für vollständige Kontrolle über dieses Verhalten, beachten Sie sorgfältig, welche Dateien welcher Konfigurationsdatei po4a-build.conf zugeordnet sind.

Beachten Sie, dass viele Dateien in einer POT-Datei für Übersetzer bequemer sind, insbesondere falls Dateien über gemeinsame Zeichenketten verfügen. Andersherum sind POT-Dateien mit tausenden von langen Zeichenketten für Übersetzer einschüchternd, woraus lange Perioden mit eingefrorenen Zeichenketten resultieren.

 # minimaler Schwellwert, ab dem Übersetzungen beibehalten werden sollen
 KEEP=
    

XMLMAN1

DocBook-XML-Dateien, um Handbuchseiten in Abschnitt 1 zu erstellen. Trennen Sie Dateinamen durch Leerzeichen. Alle Dateien müssen sich im XMLDIR-Verzeichnis befinden.

Es ist übliche Praxis, mehrere XML-Dateien in einem Buch zusammenzustellen, um ein Inhaltsverzeichnis usw. bereitzustellen. Falls das Buch auch Dateien enthält, die in XMLMAN3 angegeben sind, dann geben Sie nur die XML-Dateien für Abschnitt 1 hier an, nicht das Buch selbst. Falls das Buch nur Inhalte für diesen Abschnitt enthält, geben Sie das Buch hier an.

 # DocBook-XML-Dateien für Abschnitt 1
 XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"
    

XMLMAN3

DocBook-XML-Dateien, um Handbuchseiten in Abschnitt 3 zu erstellen. Trennen Sie Dateinamen durch Leerzeichen. Alle Dateien müssen sich im XMLDIR-Verzeichnis befinden.

Es ist übliche Praxis, mehrere XML-Dateien in einem Buch zusammenzustellen, um ein Inhaltsverzeichnis usw. bereitzustellen. Falls das Buch auch Dateien enthält, die in XMLMAN1 angegeben sind, dann geben Sie nur die XML-Dateien für Abschnitt 3 hier an, nicht das Buch selbst. Falls das Buch nur Inhalte für diesen Abschnitt enthält, geben Sie das Buch hier an.

 # DocBook-XML-Dateien für Abschnitt 3
 XMLMAN3=""
    

XMLDIR

Ablageort aller DocBook-XML-Dateien. Derzeit erwartet "po4a-build", alle in XMLMAN1 und XMLMAN3 aufgeführten Dateien zu finden, indem es nach *.xml in diesem Verzeichnis sucht.

Muss angegeben werden, falls XMLMAN1 oder XMLMAN3 verwandt wird. Pfade sind relativ zum Ort der Konfigurationsdatei.

 # Ort der XML-Dateien
 XMLDIR="share/doc/"
    

XMLPACKAGES

welche Pakete aus der Liste in BINARIES XML-Quellinhalte verwenden

Falls XMLMAN1 oder XMLMAN3 ein Wert gegeben wird, muss hier auch ein Wert angegeben werden.

 # Binärpakete, die DocBook-XML & xsltproc verwenden
 XMLPACKAGES="po4a"
    

DOCBOOKDIR

Ähnlich zu XMLDIR, aber nur für die Vorbereitung der übersetzten DocBook-Dateien verwandt. Falls Ihr Paket .sgml-Dateien verwenden soll, diskutieren Sie bitte die Bauvorschriften auf der Mailingliste po4a-devel.

 # Muster zum Finden der .docbook-Dateien
 DOCBOOKDIR=""
    

XSLFILE

XSL-Stylesheet, das zum Vorbereiten der übersetzten und nicht übersetzten Inhalte aus den DocBook-XML-Dateien verwandt wird.

 # XSL-Datei für die Verwendung mit DocBook-XML
 XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
    

PODFILE

POD-Dateien zur Erstellung von Handbuchseiten-Inhalten in Abschnitt 1. Trennen Sie POD-Dateien durch Leerzeichen. Pfade, falls verwandt, müssen relativ zum Ort der angegebenen Konfigurationsdatei sein.

 # POD-Dateien für Abschnitt 1
 PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"
    

PODMODULES

Spezialisierte Unterstützung für Perl-Module, die POD-Inhalte enthalten - der Modulname wird aus dem Pfad rekonstruiert (er sollte daher dem typischen Perl-Layout entsprechen) und die Handbuchseiten werden automatisch in Abschnitt 3 abgelegt.

 # POD-Dateien für Abschnitt 3 - Modulnamen aus dem Pfad neu erstellt
 PODMODULES="lib/Locale/Po4a/*.pm"
    

POD5FILES

Beliebiger POD-Inhalt für die Erstellung von Handbuchseiten in Abschnitt 5. Pfade, falls verwandt, müssen relativ zum Ort der angegebenen Konfigurationsdatei sein.

Für Inhalte in den Abschnitten 5 oder 7 (wo oft ein Dateiname benötigt wird, der auch für Inhalte in Abschnitt 1 verwandt wird) wird, wenn der Dateiname »5« oder »7« als Teil des Dateinamens enthält, diese Nummer (und alle Dateinamenerweiterungen) automatisch entfernt.

 # POD-Dateien für Abschnitt 5
 POD5FILES="doc/po4a-build.conf.5.pod"
    

POD7FILES

Beliebiger POD-Inhalt für die Erstellung von Handbuchseiten in Abschnitt 7. Pfade, falls verwandt, müssen relativ zum Ort der angegebenen Konfigurationsdatei sein.

Für Inhalte in den Abschnitten 5 oder 7 (wo oft ein Dateiname benötigt wird, der auch für Inhalte in Abschnitt 1 verwandt wird) wird, wenn der Dateiname »5« oder »7« als Teil des Dateinamens enthält, diese Nummer (und alle Dateinamenerweiterungen) automatisch entfernt.

 # POD-Dateien für Abschnitt 7
 POD7FILES="doc/po4a.7.pod"
    

PODPACKAGES

Ähnlich zu XMLPACKAGES - für jedes Paket, für das Inhalte aus POD-Dateien gebaut werden sollen, muss ein Wert in PODPACKAGES aufgenommen werden. Benötigt, falls Werte für PODFILE, PODMODULES, POD5FILES oder POD7FILES angegeben sind.

 # POD-verwendende Binärpakete
 PODPACKAGES="po4a"
    

HTMLDIR

Unterverzeichnis von BASEDIR, das für die Ausgabe der unübersetzten und übersetzten HTML-Ausgabe verwandt werden soll.

 # HTML-Ausgabe (Unterverzeichnis von BASEDIR)
 HTMLDIR=""
    

HTMLFILE

DocBook-Datei, die nach HTML konvertiert werden soll (kann eine der gleichen Dateien aus XMLMAN1 oder XMLMAN3 sein). Abschnitte sind für die HTML-Ausgabe nicht relevant, Sie können daher hier eine einzelne Buchdatei verwenden, so dass das HTML ein Inhaltsverzeichnis usw. hat.

 # HTML-DocBook-Datei
 HTMLFILE=""
    

HTMLXSL

Standardmäßig wird ein zerteiltes (»chunked«) XSL-Stylesheet verwandt. Derzeit wird die Verwendung von mehr als einem Stylesheet pro HTML-Lauf nicht unterstützt.

 # für HTML zu verwendende XSL-Datei
 HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"
    

AUTOREN¶

 Neil Williams <linux@codehelp.co.uk>