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.