Provided by: po4a_0.55-1_all bug

NAME

       Locale::Po4a::TeX - konvertiert TeX-Dokumente und Derivate von/in PO-Dateien

BESCHREIBUNG

       Das Projektziel von Po4a (PO für alles) ist es, die Übersetzung (und interessanter, die
       Wartung der Übersetzung) zu vereinfachen, indem die Gettext-Werkzeuge auch für Gebiete
       verwendet werden, wo diese nicht erwartet werden, wie Dokumentation.

       Locale::Po4a::TeX ist ein Modul, um bei der Übersetzung von TeX-Dokumenten in andere
       [natürliche] Sprachen zu helfen. Es kann auch als Grundlage für die Entwicklung von
       Modulen für TeX-basierte Dokumente verwandt werden.

       Benutzer sollten wahrscheinlich das LaTeX-Modul verwenden, das vom TeX-Modul abgeleitet
       ist und die Definitionen von typischen LaTeX-Befehlen enthält.

ÜBERSETZEN MIT PO4A::TEX

       Dieses Modul kann direkt verwandt werden, um mit generischen TeX-Dokumenten umzugehen. Es
       wird Ihr Dokument in kleinere Blöcke (Absätze, »verbatim«-Blöcke oder sogar kleinere wie
       Titel oder Indices) teilen.

       Es gibt einige Optionen (die im nächsten Abschnitt beschrieben werden), die dieses
       Verhalten anpassen lassen. Falls dies nicht auf Ihr Dokumentenformat passt, ermutigen wir
       Sie, Ihr eigenes, von diesem Modul abgeleitetes Modul zu schreiben, um die Details Ihres
       Formats zu beschreiben. Lesen Sie den Abschnitt SCHREIBEN ABGELEITETER MODULE weiter unten
       für die Beschreibung des Prozesses.

       Dieses Modul kann auch durch Zeilen in der TeX-Datei, die mit »% po4a:« beginnen,
       angepasst werden. Diese Anpassungen werden im Abschnitt ANPASSUNGEN IM DOKUMENT
       beschrieben.

VON DIESEM MODUL AKZEPTIERTE OPTIONEN

       Dies sind die Modul-spezifischen Optionen:

       debug
           Aktiviert Fehlersuchroutinen für einige interne Mechanismen dieses Moduls. Verwenden
           Sie den Quelltext, um zu sehen, welche Teile damit auf Fehler untersucht werden
           können.

       no_wrap
           durch Kommata getrennte Liste von Umgebungen, die nicht neu umgebrochen werden sollen

           Beachten Sie, dass es zwischen den Umgebungen »verbatim« und »no_wrap« einen
           Unterschied gibt. In »verbatim«-Blöcken erfolgt keine Befehls- und Inhaltsanalyse.

           Falls diese Umgebung noch nicht registriert war, wird Po4a annehmen, dass diese
           Umgebung keine Parameter erwartet.

       exclude_include
           durch Doppelpunkte getrennte Liste von Dateien, die nicht von \input und \include
           eingeschlossen werden sollten

       definitions
           Der Name der Datei, die die Definitionen für Po4a enthält, wie diese im Abschnitt
           ANPASSUNGEN IM DOKUMENT beschrieben sind. Sie können diese Option verwenden, falls es
           nicht möglich ist, die Definitionen in das zu übersetzende Dokument zu schreiben.

       verbatim
           durch Kommata getrennte Liste von Umgebungen, die »verbatim« angenommen werden sollten

           Falls diese Umgebung noch nicht registriert war, wird Po4a annehmen, dass diese
           Umgebung keine Parameter erwartet.

       Die Verwendung dieser Option ermöglicht es, das Verhalten der Befehle, die in dieser
       Standardliste definiert werden, zu überschreiben.

ANPASSUNGEN IM DOKUMENT

       Das TeX-Modul kann durch Zeilen, die mit % po4a: beginnen, angepasst werden. Diese Zeilen
       werden vom Parser als Befehle interpretiert. Die folgenden Befehle werden erkannt:

       % po4a: command Befehl1 alias Befehl2
           zeigt an, dass die Argumente des Befehls Befehl1 als Argumente des Befehls Befehl2
           behandelt werden sollen

       % po4a: command Befehl1 Parameter
           Dies erlaubt es, die Parameter des Befehls Befehl1 im Detail zu beschreiben. Diese
           Information wird zur Überprüfung der Anzahl der Argumente und ihrer Typen verwandt.

           Sie können Folgendes dem Befehl Befehl1 voranstellen:

           einen Stern (*)
               Po4a wird diesen Befehl aus Absätzen herauslesen (falls er sich am Anfang oder
               Ende eines Absatzes befindet). Der Übersetzer muss dann die Parameter übersetzen,
               die als übersetzbar markiert sind.

           ein Plus (+)
               Wie bei einem Stern wird der Befehl herausgelesen, falls er an den Endpunkten
               eines Blocks erscheint, aber die Parameter werden nicht separat übersetzt. Der
               Übersetzer muss den Befehl, zusammengesetzt mit allen seinen Parametern,
               übersetzen. Dies erlaubt es, mehr Kontext zu erhalten und ist für Befehle
               nützlich, die kleine Wörter in ihren Parametern enthalten, die mehrere Bedeutungen
               (und Übersetzungen) haben können.

               Hinweis: In diesem Fall müssen Sie nicht angeben, welche Parameter übersetzbar
               sind, aber Po4a muss die Anzahl und den Typ der Parameter wissen.

           ein Minus (-)
               In diesem Fall wird der Befehl aus keinem Block herausgelesen. Falls er aber
               alleine in einem Block erscheint, werden nur die als übersetzbar markierten
               Parameter dem Übersetzer angeboten. Dies ist für Schriftsatzbefehle nützlich.
               Diese Befehle sollten im Allgemeinen nicht von ihrem Absatz getrennt werden (um
               den Kontext zu erhalten), aber es gibt keinen Grund, den Übersetzer damit zu
               belästigen, falls die gesamte Zeichenkette in einem solchen Befehl eingeschlossen
               ist.

           Das Argument Parameter ist ein Satz von [] (um ein optionales Argument anzuzeigen)
           oder {} (um ein verpflichtendes Argument anzuzeigen). Sie können einen Unterstrich (_)
           zwischen diese Klammern setzen, um anzugeben, dass der Parameter übersetzt werden
           muss. Beispiel:
            % po4a: command *chapter [_]{_}

           Dies zeigt an, dass der Befehl »chapter« zwei Parameter erwartet: einen optionalen
           (den kurzen Titel) und einen verpflichtenden, wobei beide übersetzt werden müssen.
           Falls Sie angeben möchten, dass der Befehl »href« zwei verpflichtende Parameter hat,
           dass Sie die URL nicht übersetzen möchten (den ersten Parameter) und dass Sie nicht
           möchten, dass der Befehl von seinem Absatz getrennt wird (was dem Übersetzer erlaubt,
           den Link im Satz zu verschieben), können Sie folgendes verwenden:
            % po4a: command -href {}{_}

           In diesem Fall wird die Information, welche Argumente übersetzt werden müssen, nur
           verwandt, falls ein Absatz nur aus diesem href-Befehl besteht.

       % po4a: environment Umgeb Parameter
           Dies erlaubt es, die von der Umgebung Umgeb akzeptierten Parameter zu definieren.
           Diese Information wird später zum Überprüfen der Anzahl der Argumente des
           \begin-Befehls verwandt und erlaubt die Spezifizierung, welche davon übersetzt werden
           müssen. Die Syntax ist die gleiche, wie sie für die anderen Befehle beschrieben ist.
           Der erste Parameter des Befehls \begin ist der Name der Umgebung. Dieser Parameter
           darf nicht in der Liste der Parameter spezifziert werden. Einige Beispiele:
            % po4a: environment multicols {}
            % po4a: environment equation

           Wie bei den Befehlen kann Umgeb ein Plus (+) vorangestellt werden, um anzuzeigen, dass
           der Befehl \begin mit allen seinen Argumenten übersetzt werden muss.

       % po4a: separator Umgeb "RegAus"
           zeigt an, dass die Umgebung entsprechend des übergebenen regulären Ausdruckes
           aufgeteilt werden soll

           Der reguläre Ausdruck wird durch Anführungszeichen begrenzt. Er sollte keine
           Rückreferenzen erstellen. Sie sollten (?:) verwenden, falls Sie Gruppen benötigen. Es
           könnte auch notwendig sein, Teile zu schützen.

           Beispielsweise verwendet das LaTeX-Modul den regulären Ausdruck »(?:&|\\\\)«, um jede
           Zelle einer Tabelle zu trennen (Zeilen werden durch »\\«, Zellen durch »&« getrennt).

           Der Begriff der Umgebung wird auf den in der PO-Datei angezeigten Typ angewandt. Dies
           kann benutzt werden, um auf »\\\\« im ersten zwingenden Argument des Titelbefehls zu
           unterteilen. In diesem Fall ist die Umgebung Title{#1}.

       % po4a: verbatim environment Umgeb
           Zeigt an, dass Umgeb eine »verbatim«-Umgebung ist. Kommentare und Befehle werden
           innerhalb dieser Umgebung ignoriert.

           Falls diese Umgebung noch nicht registriert war, wird Po4a annehmen, dass diese
           Umgebung keine Parameter erwartet.

SCHREIBEN ABGELEITETER MODULE

       pre_trans
       post_trans
       translate
           Wrapper um die Übersetzung von TransTractor, mit Vor- und Nachverarbeitungsfiltern.

           Kommentare eines Absatzes werden als PO-Kommentare bei der ersten übersetzten
           Zeichenkette dieses Absatzes eingefügt.

       get_leading_command($buffer)
           Diese Funktion liefert folgendes zurück:

           Einen Befehlsnamen
               Falls kein Befehl am Anfang des Puffers gefunden wird, wird diese Zeichenkette
               leer sein. Nur Befehle, die getrennt werden können, werden betrachtet. Der Hash
               %separated_command enthält eine Liste dieser Befehle.

           Eine Variante
               Dies zeigt an, ob eine Variante benutzt wurde. Beispielsweise kann ein Stern (*)
               am Ende eines »section«-Befehls verwendet werden, um anzugeben, dass diese nicht
               nummeriert werden sollen. In diesem Fall wird dieses Feld »*« enthalten. Falls es
               keine Variante gibt, enthält dieses Feld die leere Zeichenkette.

           Ein Feld von Tupeln (Argumenttyp, Argument)
               Der Typ des Arguments kann entweder »{« (für verpflichtende Argumente) oder »[«
               (für optionale Argumente) sein.

           Der verbleibende Puffer
               Der Rest des Puffers nach der Entfernung des führenden Befehls und seiner
               Argumente. Falls kein Befehl gefunden wird, wird der ursprüngliche Puffer nicht
               angerührt und in diesem Feld zurückgeliefert.

       get_trailing_command($buffer)
           identisch zu get_leading_command, allerdings für Befehle am Ende des Puffers

       translate_buffer
           rekursives Übersetzen eins Puffers durch Trennung von führenden and abschließenden
           Befehlen (solche, die separat übersetzt werden sollten) aus dem Puffer

           Falls eine Funktion in %translate_buffer_env  für die aktuelle Umgebung definiert ist,
           wird diese Funktion zur Übersetzung des Puffers (statt translate_buffer()) verwandt.

       read
           überlädt Transtractors read().

       read_file
           Liest rekursiv eine Datei und hängt eingebundene Dateien, die nicht im Feld
           @exclude_include aufgeführt sind, an. Eingebundene Dateien werden mittels des Befehls
           kpsewhich aus der Bibliothek Kpathsea gesucht.

           Abgesehen von dem Teil der Einbindung von Dateien ist es eine eingefügte Kopie aus
           Transtractors read.

       parse_definition_file
           Subroutine zum Auswerten einer Datei mit Po4a-Direktiven (Definitionen für neue
           Befehle).

       parse_definition_line
           eine Definitionszeile der Form »% po4a: « auswerten

           Lesen Sie den Abschnitt ANPASSUNGEN IM DOKUMENT für weitere Details.

       is_closed
       docheader

INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden

       Befehls- und Umgebungsfunktionen erwarten die folgenden Argumente (zusätzlich zum Objekt
       $self):

       Einen Befehlsnamen
       Eine Variante
       Ein Feld von (Typ, Argument)-Tupeln
       Die aktuelle Umgebung

       Die ersten drei Argumente werden durch get_leading_command oder get_trailing_command
       herausgelöst.

       Befehls- und Umgebungsfunktionen liefern die Übersetzung des Befehls mit seinen Argumenten
       und eine neue Umgebung zurück.

       Umgebungsfunktionen werden aufgerufen, wenn ein \begin gefunden wird. Sie werden mit dem
       Befehl \begin und seinen Argumenten aufgerufen.

       Das TeX-Modul schlägt nur eine Befehlsfunktion und eine Umgebungsfunktion vor:
       generic_command und generic_environment.

       generic_command verwendet die durch register_generic_command spezifizierte Information
       oder durch Hinzufügen von Definitionen zu der TeX-Datei:
        % po4a: command Befehl Parameter

       generic_environment verwendet die durch register_generic_environment spezifizierte
       Information oder durch Hinzufügen von Definitionen zu der TeX-Datei:
        % po4a: environment Umgeb Parameter

       Beide Funktionen werden nur die als übersetzbar (mit einem »_«) angegebenen Parameter
       übersetzen. generic_environment wird den Namen der Umgebung an den Umgebungsstapel
       anhängen und generic_command wird den Namen des Befehls gefolgt von einer Kennung des
       Parameters (wie{#7} oder [#2]) anhängen.

STATUS DIESES MODULS

       Dieses Modul benötigt weitere Tests.

       Es wurde mit einem Buch und mit der Python-Dokumentation getestet.

TODO-LISTE

       Automatische Erkennung neuer Befehle
           Das TeX-Modul könnte die »newcommand«-Argumente auswerten und versuchen, die Anzahl
           der Argumente, ihren Typ und ob (oder ob nicht) sie übersetzt werden sollten, zu
           raten.

       Übersetzung des Umgebungstrenners
           Wird \item als Trenner für Umgebungen verwandt, dann wird das Argument von »item« an
           die folgenden Zeichenkette angefügt.

       Einige Befehle sollten dem Umgebungsstapel hinzugefügt werden.
           Diese Befehle sollten paarweise angegeben werden. Dies könnte die Angabe von Befehlen
           ermöglichen, die eine wortgetreue Umgebung beginnen oder beenden.

       Weitere
           Verschiedene andere Punkte werden in der Quelle als TODO gekennzeichnet.

BEKANNTE FEHLER

       Verschiedene Punkte werden in der Quelle als FIXME gekennzeichnet.

SIEHE AUCH

       Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

AUTOREN

        Nicolas François <nicolas.francois@centraliens.net>

URHEBERRECHT UND LIZENZ

       Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

       Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL (siehe die
       Datei COPYING) vertreiben und/oder verändern.