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

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.
       Dieser Prozess wird 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.

Verwenden Sie diese Optionen, um das Standardverhalten der definierten Befehle 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 beschreibt die Parameter des Befehls Befehl1 im Detail. 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 erhält mehr Kontext 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 definiert die von der Umgebung Umgeb akzeptierten Parameter und legt die zu übersetzenden fest.
Diese Information wird später zum Überprüfen der Anzahl der Argumente des \begin-Befehls verwandt.
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 erweitert. 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
add_comment
Fügt einen Zeichensatz als Kommentar hinzu, der um das nächste übersetzte Element herum hinzugefügt
werden soll. Dies ist hauptsächlich für das Texinfo-Modul nützlich, da Kommentare in TeX automatisch
gehandhabt werden.

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
parse
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.
           These  commands  should  be  specified  by couples. This can be used to specify commands beginning or
           ending a verbatim environment.

       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.

Po4a-Werkzeuge                                     2023-01-03                             Locale::Po4a::TeX(3pm)