LOCALE::PO4A::MAN.3PM(1) User Contributed Perl Documentation NAME Locale::Po4a::Man - konvertiert Handbuchseiten von/in PO-Dateien BESCHREIBUNG Das Projektziel von Po4a (PO fur alles) ist es, die Ubersetzung (und interessanter, die Wartung der Ubersetzung) zu vereinfachen, indem die Gettext-Werkzeuge auch fur Gebiete verwendet werden, wo diese nicht erwartet werden, wie Dokumentation. Locale::Po4a::Man ist ein Modul, um bei der Ubersetzung von Dokumentation im Nroff-Format (die Sprache der Handbuchseiten) in andere [naturliche] Sprachen zu helfen. UBERSETZEN MIT PO4A::MAN Das Modul gibt sich sehr viel Muhe, das Leben von Ubersetzern zu erleichtern. Dafur ist der Text, der dem Ubersetzer vorgelegt wird, keine wortliche Kopie des Textes, wie er in der Handbuchseite vorliegt. Tatsachlich werden die unfeinen Teile des Nroff-Formats versteckt, so dass die Ubersetzer nicht mit ihnen Unordnung erzeugen konnen. Zeilenumbruch Nicht eingeruckte Absatze werden fur den Ubersetzer automatisch umgebrochen. Dies kann zu ein paar kleineren Unterschieden in der erstellten Ausgabe fuhren, 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 zusatzlichen Leerzeichen in umgebrochenen Absatzen und ich denke, das ist es Wert. Schriftangabe Die erste Anderung besteht in der Schriftanderungsspezifikation. In Nroff gibt es mehrere Arten, anzugeben, ob ein Wort in kleinen Buchstaben, fett oder kursiv geschrieben werden soll. In dem zu ubersetzenden Text gibt es nur eine Art, ausgeliehen vom POD- (Perl online documentation) Format: I -- kursiver Text aquivalent zu \fIText\fP or ".I Text" B -- fetter Text aquivalent zu \fBText\fP or ".B Text" R -- aufrechter Text aquivalent zu \fRtext\fP CW -- Text mit konstanter Breite aquivalent zu \f(CWtext\fP oder ".CW text" Bemerkung: Die CW-Schriftart ist nicht fur alle Groff-Gerate verfugbar. Es wird empfohlen, sie nicht zu verwenden. Sie wird zur Bequemlichkeit bereitgestellt. Automatische Zeichenumschreibung Po4a schreibt automatisch einige Zeichen um, um die Ubersetzung oder die Begutachtung der Ubersetzung 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 Ubersetzung in das Ausgabedokument eingefugt wird. Ubersetzer konnen einen Gedankenstrich erzwingen, indem Sie das Roff-Zeichen >>\[hy]<< in ihrer Ubersetzung verwenden. nicht trennbare Leerzeichen Ubersetzer konnen nicht trennbare Leerzeichen in ihren Ubersetzungen verwenden. Diese nicht trennbaren Leerzeichen (0xA0 in latin1) werden in ein nicht trennbares Leerzeichen (>>\ <<) von Roff umgeschrieben. Umschreibung von Anfuhrungszeichen `` und '' werden in \*(lq und \*(rq respektive umgeschrieben. Um diese Umschreibung zu vermeiden, konnen Ubersetzer ein Roff-Zeichen mit einer Breite von Null einfugen (d.h. `\&` oder '\&' respektive verwenden). >><<< und >>><< in Ubersetzungen einbauen Da diese Zeichen zur Begrenzung von Teilen mit Schriftanderung verwandt werden, konnen Sie sie nicht unverandert verwenden. Verwenden Sie stattdessen E und E (wie in POD, nochmals). VON DIESEM MODUL AKZEPTIERTE OPTIONEN Dies sind die Modul-spezifischen Optionen: debug Aktiviert Fehlersuchroutinen fur einige interne Mechanismen dieses Moduls. Verwenden Sie den Quelltext, um zu sehen, welche Teile damit auf Fehler untersucht werden konnen. verbose Ausfuhrlichkeit erhohen 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<< unverandert vom Original in das ubersetzte Dokument kopiert werden mussen translate Gibt an, dass die Abschnitte >>.de<<, >>.ie<< und >>.if<< zur Ubersetzung vorgeschlagen werden. Sie sollten diese Option nur verwenden, wenn innerhalb dieser Abschnitte sich eine ubersetzbare 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 Ubersetzung von generierten Handbuchseiten (statt der Quellseiten) oft fehleranfalliger und daher keine Gute Idee ist. mdoc Diese Option ist nur fur Mdoc-Seiten nutzlich. Es wahlt eine strengere Unterstutzung fur das Mdoc-Format aus, indem Po4a angewiesen wird, den Abschnitt >>NAME<< nicht zu ubersetzen. Mdoc-Seiten, deren >>NAME<<-Abschnitt ubersetzt wurde, erstellen keine Kopf- oder Fusszeilen. Entsprechend der Groff-Mdoc-Seite, sind die Abschnitte >>NAME<<, >>SYNOPSIS<< (im deutschen >>UBERSICHT<<) und >>DESCRIPTION<< (>>BESCHREIBUNG<<) verpflichtend. Es gibt keine bekannten Probleme mit ubersetzten SYNPOSIS- oder DESCRIPTION-Abschnitten, Sie konnen 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 unterstutzten 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 unterstutzt 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 ubersetzt werden mussen. noarg noarg verhalt sich wie untranslated, ausser dass Po4a uberprufen wird, dass kein Argument zu diesem Makro hinzugefugt wird. translate_joined translate_joined zeigt an, dass Po4a die Argumente dieses Makros zur Ubersetzung vorschlagen muss. translate_each Mit translate_each werden die Argumente auch zur Ubersetzung vorgeschlagen, ausser dass jedes separat ubersetzt 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 Uberprufung, 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, fur das kein Ende (respektive Anfang) existiert, konnen Sie ein existierendes Ende (wie fi) oder Anfang (wie nf) als Gegenstuck angeben. Diese Makros (und ihre Argumente) werden nicht ubersetzt. inline Diese Option gibt eine Komma-separierte Liste von Makros an, die den aktuellen Absatz nicht trennen durfen. Die zu ubersetzende 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. Standardmassig schlagt Po4a mit einer Warnung fehl. Diese Option kann die folgenden Werte annehmen: failed (der Standardwert), untranslated, noarg, translate_joined oder translate_each (die Erklarung 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 ware moglich, 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 ware zu schwierig und wir dachten, es ware nicht notwendig. Wir glauben, dass Handbuchseitenautoren, die ihre Werke ubersetzt bekommen mochten, sich anpassen mussen, um die Arbeit der Ubersetzer zu erleichtern. Daher hat der Parser in Po4a einige bekannte Einschrankungen, die wir nicht planen, zu korrigieren und die einige Fallstricke enthalten, die Sie vermeiden sollten, falls Sie mochten, dass Ubersetzer sich um Ihre Dokumentation kummern. Programmieren Sie nicht in Nroff Nroff ist eine komplette Programmiersprache mit Makrodefinitionen, Bedingungen und so weiter. Da dieser Parser kein vollstandiger Nroff-Interpreter ist, wird er bei Seiten fehlschlagen, die diese Funktionalitaten 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 unterstutzt werden. Das passiert nur, da ich keine Information uber sie gefunden habe. Es folgt eine Liste von nicht unterstutzen Makros, die ich auf meiner Kiste gefunden habe. Beachten Sie, dass diese Liste nicht abschliessend ist, da das Programm beim ersten nicht unterstutzten Makro abbricht. Falls Sie uber einige dieser Makros Informationen haben, werde ich gerne die Unterstutzung hierfur hinzufugen. Aufgrund dieser Makros sind rund 250 Seiten auf meinem Rechner nicht fur po4a::man verfugbar. .. ." .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 weiss der Autor, dass einige Teile nicht ubersetzbar sind und daher von Po4a nicht ausgelesen werden sollten. Beispielsweise konnte eine Option other als Argument akzeptieren und other konnte zusatzlich als letztes Argument in einer Liste auftauchen. Im ersten Fall sollte other nicht ubersetzt 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 benotigt 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 benotigt die Option -o groff_code=verbatim und -o untranslated=IR_untranslated; mit diesem Konstrukt wird die Bedingung .if !'po4a'hide' streng genommen nicht benotigt, da Po4a nicht die Interna der Makrodefinition auswerten wird) oder durch Verwendung eines Alias: .als IR_untranslated IR .IR_untranslated \-q ", " \-\-quiet (dies benotigt die Option -o untranslated=als,IR_untranslated) Schlussfolgerungen Um diesen Abschnitt zusammenzufassen: Halten Sie es einfach und versuchen Sie nicht, beim Verfassen Ihrer Handbuchseiten uberschlau zu sein. In Nroff sind viele Dinge moglich und werden nicht von diesem Parser unterstutzt. 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 gultig ist, wurde aber die Handhabung durch den Parser zu sehr komplizieren. Naturlich ware eine weitere Moglichkeit, ein anderes, ubersetzerfreundlicheres 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 notig. Davon abgesehen, falls das Quellformat Ihrer Dokumentation POD oder XML ist, konnte es klug sein, das Quellformat und nicht das erzeugte zu ubersetzen. In den meisten Fallen 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-Gegenstuck eine grosse Menge neuer Makros definiert, fur die der Verfasser keine Unterstutzung schreiben mochte. Auf dessen Kiste wurden 1432 der 4323 Seiten aus POD erzeugt und werden von po4a::man ignoriert. In den meisten Fallen wird po4a::man das Problem feststellen und die Verarbeitung der Seite verweigern und eine angepasste Nachricht ausgeben. In einigen seltenen Fallen wird das Programm vollstandig ohne Warnung ausgefuhrt, die Ausgabe ist aber falsch. Solche Falle werden >>Fehler<< genannt. ;) Falls Sie auf einen solchen Fall stossen, stellen Sie sicher, dass Sie dies melden, wenn moglich zusammen mit einer Fehlerbehebung STATUS DIESES MODULS Dieses Module kann fur die meisten existierenden Handbuchseiten benutzt werden. Einige Tests werden regelmassig auf Linux-Kisten ausgefuhrt: o ein Drittel Seiten werden abgelehnt, da sie in einem anderen durch Po4a unterstutzten Format erzeugt wurde (z.B. POD or SGML). o Zehn Prozent der verbleibenden Seiten werden mit einem Fehler zuruckgewiesen (z.B. wird ein Groff-Makro nicht unterstutzt). o Dann wird weniger als ein Prozent der Seiten stillschweigend durch Po4a akzeptiert, aber mit wesentlichen Problemen (d.h. fehlenden Wortern oder neu eingefugten Wortern), o Die anderen Seiten werden ublicherweise 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 Nicolas Francois Martin Quinson (mquinson#debian.org) URHEBERRECHT UND LIZENZ Copyright (C) 2002-2008 SPI, Inc. Dieses Programm ist freie Software; Sie konnen es unter den Bedingungen der GPL v2.0 oder neuer (siehe die Datei COPYING) vertreiben und/oder verandern. perl v5.42.0 2025-11-22 LOCALE::PO4A::MAN.3PM(1)