Provided by: po4a_0.73-2ubuntu1_all 
NAME
Locale::Po4a::Man - konvertiert Handbuchseiten 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::Man ist ein Modul, um bei der Übersetzung von Dokumentation im Nroff-Format (die Sprache
der Handbuchseiten) in andere [natürliche] Sprachen zu helfen.
ÜBERSETZEN MIT PO4A::MAN
Das Modul gibt sich sehr viel Mühe, das Leben von Übersetzern zu erleichtern. Dafür ist der Text, der dem
Übersetzer vorgelegt wird, keine wörtliche Kopie des Textes, wie er in der Handbuchseite vorliegt.
Tatsächlich werden die unfeinen Teile des Nroff-Formats versteckt, so dass die Übersetzer nicht mit ihnen
Unordnung erzeugen können.
Zeilenumbruch
Nicht eingerückte Absätze werden für den Übersetzer automatisch umgebrochen. Dies kann zu ein paar
kleineren Unterschieden in der erstellten Ausgabe führen, da die von Groff verwandten Zeilenumbruchregeln
nicht sehr klar sind. Beispielsweise werden zwei Leerzeichen nach einer Klammer manchmal erhalten.
Wie dem auch sei, der Unterschied besteht nur in der Position von zusätzlichen Leerzeichen in
umgebrochenen Absätzen und ich denke, das ist es Wert.
Schriftangabe
Die erste Änderung besteht in der Schriftänderungsspezifikation. In Nroff gibt es mehrere Arten,
anzugeben, ob ein Wort in kleinen Buchstaben, fett oder kursiv geschrieben werden soll. In dem zu
übersetzenden Text gibt es nur eine Art, ausgeliehen vom POD- (Perl online documentation) Format:
I<Text> -- kursiver Text
äquivalent zu \fIText\fP or ".I Text"
B<Text> -- fetter Text
äquivalent zu \fBText\fP or ".B Text"
R<text> -- aufrechter Text
äquivalent zu \fRtext\fP
CW<text> -- Text mit konstanter Breite
äquivalent zu \f(CWtext\fP oder ".CW text"
Bemerkung: Die CW-Schriftart ist nicht für alle Groff-Geräte verfügbar. Es wird empfohlen, sie nicht zu
verwenden. Sie wird zur Bequemlichkeit bereitgestellt.
Automatische Zeichenumschreibung
Po4a schreibt automatisch einige Zeichen um, um die Übersetzung oder die Begutachtung der Übersetzung zu
vereinfachen. Folgende Zeichen werden umgeschrieben:
Gedankenstriche
Bindestriche (-) und Minuszeichen (\-) in Handbuchseiten werden alle zu Gedankenstrichen (-) in der
PO-Datei umgeschrieben. Dann werden alle Gedankenstriche in Roff-Minuszeichen (\-) umgeschrieben,
wenn die Übersetzung in das Ausgabedokument eingefügt wird.
Übersetzer können einen Gedankenstrich erzwingen, indem Sie das Roff-Zeichen »\[hy]« in ihrer
Übersetzung verwenden.
nicht trennbare Leerzeichen
Übersetzer können nicht trennbare Leerzeichen in ihren Übersetzungen verwenden. Diese nicht
trennbaren Leerzeichen (0xA0 in latin1) werden in ein nicht trennbares Leerzeichen (»\ «) von Roff
umgeschrieben.
Umschreibung von Anführungszeichen
`` und '' werden in \*(lq und \*(rq respektive umgeschrieben.
Um diese Umschreibung zu vermeiden, können Übersetzer ein Roff-Zeichen mit einer Breite von Null
einfügen (d.h. `\&` oder '\&' respektive verwenden).
»<« und »>« in Übersetzungen einbauen
Da diese Zeichen zur Begrenzung von Teilen mit Schriftänderung verwandt werden, können Sie sie nicht
unverändert verwenden. Verwenden Sie stattdessen E<lt> und E<gt> (wie in POD, nochmals).
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.
verbose
Ausführlichkeit erhöhen
groff_code
Diese Option steuert das Verhalten des Moduls, wenn es auf einen Abschnitt ».de«, ».ie« oder ».if«
trifft. Sie kann die folgenden Werte annehmen:
fail
Dies ist der Standardwert. Das Modul wird fehlschlagen, wenn es auf einen Abschnitt ».de«, ».ie«
oder ».if« trifft.
verbatim
gibt an, dass die Abschnitte ».de«, ».ie« und ».if« unverändert vom Original in das übersetzte
Dokument kopiert werden müssen
translate
Gibt an, dass die Abschnitte ».de«, ».ie« und ».if« zur Übersetzung vorgeschlagen werden. Sie
sollten diese Option nur verwenden, wenn innerhalb dieser Abschnitte sich eine übersetzbare
Zeichenkette befindet. Andernfalls sollte verbatim vorgezogen werden.
generated
Diese Option gibt an, dass die Datei automatisch generiert wurde und dass Po4a nicht versuchen
sollte, herauszufinden, ob die Handbuchseite aus einem anderen Format generiert wurde. Diese Option
ist zwingend anzugeben, wenn Po4a mit generierten Handbuchseiten verwandt wird. Beachten Sie, dass
die Übersetzung von generierten Handbuchseiten (statt der Quellseiten) oft fehleranfälliger und daher
keine Gute Idee ist.
mdoc
Diese Option ist nur für Mdoc-Seiten nützlich.
Es wählt eine strengere Unterstützung für das Mdoc-Format aus, indem Po4a angewiesen wird, den
Abschnitt »NAME« nicht zu übersetzen. Mdoc-Seiten, deren »NAME«-Abschnitt übersetzt wurde, erstellen
keine Kopf- oder Fußzeilen.
Entsprechend der Groff-Mdoc-Seite, sind die Abschnitte »NAME«, »SYNOPSIS« (im deutschen »ÜBERSICHT«)
und »DESCRIPTION« (»BESCHREIBUNG«) verpflichtend. Es gibt keine bekannten Probleme mit übersetzten
SYNPOSIS- oder DESCRIPTION-Abschnitten, Sie können aber diese Abschnitte auch in dieser Art
spezifizieren:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION
Dieses Mdoc-Problem kann auch mit einem Addendum der folgenden Art behoben werden:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Monat Tag, Jahr" OS "Abschnittname"
Die folgenden Optionen legen das Verhalten eines benutzerdefinierten Makros (mit einem .de-Konstrukt)
oder einem klassischen, von Po4a nicht unterstützten Makro fest. Sie erwarten als Argument eine durch
Kommata getrennte Liste von Makros, beispielsweise:
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Hinweis: Falls ein Makro von Po4a nicht unterstützt wird und falls Sie denken, dass dies ein Standard-
Roff-Makro ist, dann sollten Sie es dem Po4a-Entwicklungsteam mitteilen.
untranslated
untranslated gibt an, dass dieses Makro (und seine Argumente) nicht übersetzt werden müssen.
noarg
noarg verhält sich wie untranslated, außer dass Po4a überprüfen wird, dass kein Argument zu diesem
Makro hinzugefügt wird.
translate_joined
translate_joined zeigt an, dass Po4a die Argumente dieses Makros zur Übersetzung vorschlagen muss.
translate_each
Mit translate_each werden die Argumente auch zur Übersetzung vorgeschlagen, außer dass jedes separat
übersetzt wird.
no_wrap
Diese Option akzeptiert als Argument eine Komma-separierte Liste von Anfang:Ende-Paaren, wobei Anfang
und Ende Befehle sind, die den Anfang und das Ende eines Abschnitts, der nicht neu umgebrochen werden
soll, abgrenzen.
Hinweis: Es erfolgt keine Überprüfung, um sicherzustellen, dass der Ende-Befehl auf einen
Anfang-Befehl passt, jeder Beendigungsbefehl beendet den »no_wrap«-Modus. Falls ein Anfang-
(respektive ein Ende-)Makro existiert, für das kein Ende (respektive Anfang) existiert, können Sie
ein existierendes Ende (wie fi) oder Anfang (wie nf) als Gegenstück angeben. Diese Makros (und ihre
Argumente) werden nicht übersetzt.
inline
Diese Option gibt eine Komma-separierte Liste von Makros an, die den aktuellen Absatz nicht trennen
dürfen. Die zu übersetzende Zeichenkette wird dann foo <.bar baz qux> quux enthalten, wobei bar der
Befehl ist, der in der Zeile bleiben soll und baz qux seine Argumente sind.
unknown_macros
Diese Option zeigt an, wie sich Po4a verhalten soll, wenn ein unbekanntes Makro gefunden wird.
Standardmäßig schlägt Po4a mit einer Warnung fehl. Diese Option kann die folgenden Werte annehmen:
failed (der Standardwert), untranslated, noarg, translate_joined oder translate_each (die Erklärung
dieser Werte ist weiter oben erfolgt).
ERSTELLEN VON PO4A::MAN-KONFORMEN HANDBUCHSEITEN
Dieses Modul ist noch sehr begrenzt und wird dies immer bleiben, da es kein echter Nroff-Interpreter ist.
Es wäre möglich, einen echten Nroff-Interpreter zu erstellen, um Autoren die Verwendung aller
existierender Makros (und sogar die Definition neuer Makros) in ihren Seiten zu erlauben, aber wir
wollten das nicht. Es wäre zu schwierig und wir dachten, es wäre nicht notwendig. Wir glauben, dass
Handbuchseitenautoren, die ihre Werke übersetzt bekommen möchten, sich anpassen müssen, um die Arbeit der
Übersetzer zu erleichtern.
Daher hat der Parser in Po4a einige bekannte Einschränkungen, die wir nicht planen, zu korrigieren und
die einige Fallstricke enthalten, die Sie vermeiden sollten, falls Sie möchten, dass Übersetzer sich um
Ihre Dokumentation kümmern.
Programmieren Sie nicht in Nroff
Nroff ist eine komplette Programmiersprache mit Makrodefinitionen, Bedingungen und so weiter. Da dieser
Parser kein vollständiger Nroff-Interpreter ist, wird er bei Seiten fehlschlagen, die diese
Funktionalitäten verwenden (es gibt rund 200 solche Seiten auf meiner Kiste).
Verwenden Sie den Makrosatz »plain«
Es gibt noch einige Makros, die von po4a::man nicht unterstützt werden. Das passiert nur, da ich keine
Information über sie gefunden habe. Es folgt eine Liste von nicht unterstützen Makros, die ich auf meiner
Kiste gefunden habe. Beachten Sie, dass diese Liste nicht abschließend ist, da das Programm beim ersten
nicht unterstützten Makro abbricht. Falls Sie über einige dieser Makros Informationen haben, werde ich
gerne die Unterstützung hierfür hinzufügen. Aufgrund dieser Makros sind rund 250 Seiten auf meinem
Rechner nicht für po4a::man verfügbar.
.. ." .AT .b .bank
.BE ..br .Bu .BUGS .BY
.ce .dbmmanage .do .En
.EP .EX .Fi .hw .i
.Id .l .LO .mf
.N .na .NF .nh .nl
.Nm .ns .NXR .OPTIONS .PB
.pp .PR .PRE .PU .REq
.RH .rn .S< .sh .SI
.splitfont .Sx .T .TF .The
.TT .UC .ul .Vb .zZ
Text vor Po4a verstecken
Manchmal weiß der Autor, dass einige Teile nicht übersetzbar sind und daher von Po4a nicht ausgelesen
werden sollten. Beispielsweise könnte eine Option other als Argument akzeptieren und other könnte
zusätzlich als letztes Argument in einer Liste auftauchen. Im ersten Fall sollte other nicht übersetzt
werden, im zweiten Falls dagegen schon (z.B. ins Deutsche als »sonstiges«).
In diesem Fall kann der Autor durch spezielle Groff-Konstrukte Po4a anweisen, bestimmte Zeichenketten
nicht auszulesen:
.if !'po4a'hide' .B other
(dies benötigt die Option -o groff_code=verbatim)
Ein neues Makro kann auch zur Automatisierung hiervon verwandt werden:
.de IR_untranslated
. IR \\$@
..
.IR_untranslated \-q ", " \-\-quiet
(dies benötigt die Option -o groff_code=verbatim und -o untranslated=IR_untranslated; mit diesem
Konstrukt wird die Bedingung .if !'po4a'hide' streng genommen nicht benötigt, da Po4a nicht die Interna
der Makrodefinition auswerten wird)
oder durch Verwendung eines Alias:
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
(dies benötigt die Option -o untranslated=als,IR_untranslated)
Schlussfolgerungen
Um diesen Abschnitt zusammenzufassen: Halten Sie es einfach und versuchen Sie nicht, beim Verfassen Ihrer
Handbuchseiten überschlau zu sein. In Nroff sind viele Dinge möglich und werden nicht von diesem Parser
unterstützt. Versuchen Sie zum Beispiel nicht, mit \c herumzumurksen, um die Textverarbeitung zu
unterbrechen (wie es 40 Seiten auf der Kiste des Verfassers tun). Oder stellen Sie sicher, dass Sie die
Makro-Argumente auf die gleiche Zeile wie das Makro selbst legen. Es ist bekannt, dass dies in Nroff
gültig ist, würde aber die Handhabung durch den Parser zu sehr komplizieren.
Natürlich wäre eine weitere Möglichkeit, ein anderes, übersetzerfreundlicheres Format zu benutzen (wie
POD unter Benutzung von po4a::pod oder einem aus der XML-Familie, wie SGML), aber dank po4a::man ist das
nicht mehr nötig. Davon abgesehen, falls das Quellformat Ihrer Dokumentation POD oder XML ist, könnte es
klug sein, das Quellformat und nicht das erzeugte zu übersetzen. In den meisten Fällen wird po4a::man
erzeugte Seiten ermitteln und ein Warnung ausgeben. Es wird sogar die Verarbeitung der erzeugten Seiten
verweigern, da diese Seiten perfekt durch po4a::pod gehandhabt werden und da ihr Nroff-Gegenstück eine
große Menge neuer Makros definiert, für die der Verfasser keine Unterstützung schreiben möchte. Auf
dessen Kiste wurden 1432 der 4323 Seiten aus POD erzeugt und werden von po4a::man ignoriert.
In den meisten Fällen wird po4a::man das Problem feststellen und die Verarbeitung der Seite verweigern
und eine angepasste Nachricht ausgeben. In einigen seltenen Fällen wird das Programm vollständig ohne
Warnung ausgeführt, die Ausgabe ist aber falsch. Solche Fälle werden »Fehler« genannt. ;) Falls Sie auf
einen solchen Fall stoßen, stellen Sie sicher, dass Sie dies melden, wenn möglich zusammen mit einer
Fehlerbehebung …
STATUS DIESES MODULS
Dieses Module kann für die meisten existierenden Handbuchseiten benutzt werden.
Einige Tests werden regelmäßig auf Linux-Kisten ausgeführt:
• ein Drittel Seiten werden abgelehnt, da sie in einem anderen durch Po4a unterstützten Format erzeugt
wurde (z.B. POD or SGML).
• Zehn Prozent der verbleibenden Seiten werden mit einem Fehler zurückgewiesen (z.B. wird ein Groff-
Makro nicht unterstützt).
• Dann wird weniger als ein Prozent der Seiten stillschweigend durch Po4a akzeptiert, aber mit
wesentlichen Problemen (d.h. fehlenden Wörtern oder neu eingefügten Wörtern),
• Die anderen Seiten werden üblicherweise ohne Unterschiede gehandhabt, die wichtiger sind als
Leerzeichenunterschiede oder neue Zeilenaufteilung (Schriftprobleme in weniger als zehn Prozent der
verarbeiteten Seiten).
SIEHE AUCH
Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
AUTOREN
Denis Barbier <barbier@linuxfr.org>
Nicolas François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
URHEBERRECHT UND LIZENZ
Copyright © 2002-2008 SPI, Inc.
Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL v2.0 oder neuer (siehe
die Datei COPYING) vertreiben und/oder verändern.
perl v5.38.2 2024-08-28 LOCALE::PO4A::MAN.3PM(1)