Locale::Po4a::Sgml(3pm)

NAME
Locale::Po4a::Sgml - konvertiert SGML-Dokumente 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::Sgml ist ein Modul, um bei der Übersetzung von Dokumentation im SGML-Format in andere [natürliche] Sprachen zu helfen.

This module uses onsgmls(1) to parse the SGML files. Make sure it is installed. Also make sure that the DTD of the SGML files are installed in the system.

VON DIESEM MODUL AKZEPTIERTE OPTIONEN

debug
    Durch Leerzeichen getrennte Liste von Schlüsselwörtern, die angeben, welchen Teil Sie auf Fehler prüfen wollen. Mögliche Werte sind: tag, generic, entities und refs.

verbose
    mehr Informationen darüber ausgeben, was vorgeht

translate
    durch Leerzeichen getrennte Liste von zusätzlichen Markierungen (»Tags«) (neben denen von der DTD vorgegebenen), deren Inhalt eine zusätzliche »msgid« ergeben soll

section
    durch Leerzeichen getrennte Liste von zusätzlichen Markierungen (»Tags«) (neben denen von der DTD vorgegebenen), die andere Markierungen enthalten, wobei einige in die Kategorie translate fallen

indent
    durch Leerzeichen getrennte Liste von Markierungen (»Tags«), die die Einzugsstufe erhöhen

verbatim
    Das Layout innerhalb dieser Markierungen (»Tags«) sollte nicht geändert werden. Der Absatz erfährt keinen Zeilenumbruch und keine zusätzliche Einrückung und keine zusätzliche Zeilen werden für kosmetische Zwecke eingefügt.

empty
    Markierungen (»Tags«), die nicht geschlossen werden müssen

ignore
    Markierungen (»Tags«), die von Po4a ignoriert und als reine Zeichendaten betrachtet werden. Das bedeutet, dass sie Teil einer Msgid sein können. Beispielsweise ist <b> ein guter Kandidat für diese Kategorie, da das Hinzufügen in den Abschnitt »translate« Msgids erzeugen würde, die keine kompletten Sätze sind, was nicht gut wäre.

attributes
    Eine durch Leerzeichen getrennte Liste von Attributen, die nicht übersetzt werden müssen. Sie können die Attribute mit ihrem Namen (beispielsweise »lang«) angeben, aber Sie können ihnen auch eine Markierungs- (»Tag«-)Hierarchie voranstellen, um anzugeben, dass dieses Attribut nur übersetzt wird, wenn es Teil der angegebenen Markierung ist. Beispielsweise spezifiziert <bbb><aaa>lang, dass das Attribut »lang« nur übersetzt werden soll, wenn es Teil der Markierung <aaa>, die wiederum Teil der Markierung <bbb> ist. Die Namen der Markierungen sind eigentlich reguläre Ausdrücke, daher können Sie auch Formulierungen wie <aaa|bbbb>lang wählen, um das Attribut »lang« nur zu übersetzen, wenn es sich in der Markierung <aaa> oder <bbb> befindet.

qualify
    Eine durch Leerzeichen getrennte Liste von Attributen, für die die Übersetzung über den Attributnamen qualifiziert werden muss. Beachten Sie, dass diese Einstellung das angegebene Attribut auch automatisch zu der Liste »attributes« hinzufügt.

force
    Proceed even if the DTD is unknown or if onsgmls finds errors in the input file.

include-all
    Standardmäßig werden Msgids, die nur eine Entität enthalten (wie »&version;«) für angenehmeres Übersetzen übersprungen. Durch Aktivierung dieser Option wird diese Optimierung vermieden. Dies könnte nützlich sein, falls das Dokumente Konstrukte wie »<title>&Aacute;</title>« enthält, selbst wenn ich daran zweifle, dass das jemals passieren wird …

ignore-inclusion
    Space separated list of entities that won't be inlined. Use this option with caution: it may cause onsgmls (used internally) to add tags and render the output document invalid.

STATUS DIESES MODULS
Das Ergebnis ist perfekt, d.h. die erstellten Dokumente sind identisch. Aber es gibt noch ein paar Probleme:

•   The error output of onsgmls is redirected to /dev/null, which is clearly bad. I don't know how to avoid that.

    The problem is that I have to "protect" the conditional inclusions (i.e. the "<! [ %foo [" and "]]>" stuff) from onsgmls. Otherwise onsgmls eats them, and I don't know how to restore them in the final document. To prevent that, I rewrite them to "{PO4A-beg-foo}" and "{PO4A-end}".

    The problem with this is that the "{PO4A-end}" and such I add are invalid in the document (not in a <p> tag or so).

    Everything works well with onsgmls's output redirected that way, but it will prevent us from detecting that the document is badly formatted.

•   Es funktioniert nur mit der DebianDoc- und DocBook-DTD. Hinzunahme der Unterstützung für eine neue DTD sollte sehr leicht sein. Der Mechanismus ist für alle DTD identisch, Sie müssen nur eine Liste der existierenden Markierungen und einige ihrer Charakteristika angeben.

    Ich stimme zu, dass dies weitere Dokumentation benötigt, aber es wird immer noch als Beta betrachtet und ich hasse es, Zeug zu dokumentieren, dass sich noch ändern kann oder wird.

•   Warnung: Die Unterstützung für DTDs ist noch recht experimentell. Ich habe kein Referenzhandbuch gelesen, um die Definition jeder Markierung herauszufinden. Ich habe die Makierungsdefinitionen zum Modul hinzugefügt, bis es für einige Dokumente funktionierte, die ich im Netz fand. Falls Ihr Dokument mehr Markierungen verwendet als meins, wird es nicht funktionieren. Aber wie oben geschrieben, sollte das leicht zu beheben sein.

    Ich habe DocBook nur mit der SAG (System Administrator Guide) getestet, allerdings ist dieses Dokument sehr groß und sollte den Großteil der DocBook-Spezialitäten verwenden.

    Für DebianDoc habe ich einige der Handbücher vom DDP getestet, aber noch nicht alle.

•   Im Falle von Dateieinbindungen werden Zeichenkettenreferenzen von Meldungen in PO-Dateien (d.h. Zeilen der Art "#: en/titletoc.sgml:9460") falsch sein.

    This is because I preprocess the file to protect the conditional inclusion (i.e. the "<! [ %foo [" and "]]>" stuff) and some entities (like &version;) from onsgmls because I want them verbatim to the generated document. For that, I make a temp copy of the input file and do all the changes I want to this before passing it to onsgmls for parsing.

    Damit dies funktioniert, werden die Entitäten, die eine Dateieinbindung durch den Inhalt der angegebenen Datei erbitten, ersetzt (so dass auch geschützt werden kann, was in einer Unterdatei ist). Allerdings erfolgt derzeit anschließend nichts, um die Referenzen zu schützen (d.h. Dateiname und Zeilennummer). Mir ist nicht klar, was hier das beste Vorgehen ist.

AUTOREN
This module is an adapted version of sgmlspl (SGML postprocessor for the ONSGMLS parser) which was:

 Copyright (c) 1995 David Megginson <dmeggins@aix1.uottawa.ca>

Die Anpassung für Po4a wurde erledigt durch:

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

URHEBERRECHT UND LIZENZ
 Copyright (c) 1995 David Megginson <dmeggins@aix1.uottawa.ca>
 Copyright 2002, 2003, 2004, 2005 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.