Provided by: po4a_0.69-1_all bug

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.

       Dieses Module verwendet onsgmls(1), um SGML-Dateien auszuwerten. Stellen Sie daher sicher,
       dass es installiert ist. Stellen Sie auch sicher, dass die DTD- der SGML-Dateien im System
       installiert sind.

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
           fortfahren, selbst falls die DTD unbekannt ist oder falls Onsgmls Fehler in der
           Eingabedatei findet

       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
           Durch Leerzeichen getrennte Liste, die nicht eingefügt wird. Benutzen Sie diese Option
           mit Vorsicht: Sie könnte Onsgmls (intern benutzt) veranlassen, Markierungen
           hinzuzufügen und das Ausgabedokument ungültig zu berechnen.

STATUS DIESES MODULS

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

       • Die Fehlerausgabe von Onsgmls wird standardmäßig nach /dev/null umgeleitet. Dies ist
         eindeutig schlecht. Ich weiß nicht, wie ich das vermeiden kann.

         Das Problem liegt darin, dass ich die bedingte Einbindung (d.h. das Zeug "<! [ %foo ["
         und "]]>") vor Onsgmls »schützen« muss. Andernfalls futtert Onsgmls das auf und ich weiß
         nicht, wie ich das im letztendlichen Dokument wieder herstellen kann. Um das zu
         vermeiden, schreibe ich sie in "{PO4A-beg-foo}" und "{PO4A-end}" um.

         Das Problem dabei ist, dass "{PO4A-end}" und so etwas im Dokument ungültig sind (nicht
         in einer <p>-Markierung oder so).

         Falls Sie die Onsgmls-Ausgabe sehen wollen, fügen Sie einfach Folgendes zu Ihrer
         Befehlszeile (oder der Po4a-Konfigurationszeile) hinzu:

           -o debug=onsgmls

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

         Dies rührt daher, dass die Datei vorbearbeitet wird, um die bedingten Einbindungen (d.h.
         das "<! [ %foo [" und "]]>" Zeug) und einige Entitäten (wie &version) vor Onsgmls zu
         schützen, da ich sie unverändert im automatisch erstellten Dokument bekommen möchte.
         Daher wird eine temporäre Kopie der Eingabedatei angelegt und alle Änderungen werden
         daran vorgenommen, bevor sie an Onsgmls zur Auswertung übergeben wird.

         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

       Dieses Modul ist eine angepasste Version von Sgmlspl (SGML postprocessor for the ONSGMLS
       parsers), für den galt:

        Copyright © 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 © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
        Copyright © 2002-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.