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).

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ällenwird 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 …