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"

       The following options specify the behavior of a user-defined macro (with a .de request),
       or of a classical macro that is not supported by po4a. They take as argument a comma-
       separated list of macros. For example:

        -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 (siehe die
       Datei COPYING) vertreiben und/oder verändern.