LOCALE:...GML.3PM(1)

📦
version 0.74 · 15 versions
, in alpine 3.23

💅 LOCALE:...GML.3PM — Locale::Po4a::Sgml 💅

okay bestie, so this is a Perl module page from the User Contributed Perl Documentation, and it's literally the Locale::Po4a::Sgml situation — converting SGML documents from/to PO files. buckle up 🎀

✨ NAME ✨

Locale::Po4a::Sgml — convert SGML documents from/to PO files 🦋

🌸 DESCRIPTION 🌸

so the whole point of the po4a (PO for anything) project is to make translations — and, honestly more interestingly, the maintenance of translations — way easier by using gettext tools in places nobody expected them, like documentation. main character energy fr 💜

Locale::Po4a::Sgml is the module that helps you translate documentation written in the SGML format into other [human] languages. 🌈

This module uses onsgmls(1) to parse the SGML files, so make sure it's installed, no cap. Also make sure that the DTDs of the SGML files are installed on the system. 👑

✨ OPTIONS ACCEPTED BY THIS MODULE ✨

  • debug — a space-separated list of keywords telling po4a which category of extra debug messages to show you. the possible values are "entities", "generic", "onsgml", "refs" and "tag". 🔍
  • verbose — gives you more info about what's going on. the way that this one just tells you stuff 💬
  • translate — a space-separated list of extra tags (on top of the ones the DTD provides) whose content should form an extra msgid, i.e. stuff that should be translated. 🌸
  • section — a space-separated list of extra tags (beside the DTD-provided ones) that contain other tags, some of which are of category translate. 🧚
  • indent — a space-separated list of tags that increase the indentation level. this affects the indentation in the resulting document. ⭐
  • verbatim — the layout within those tags should not be changed. the paragraph won't get wrapped, and no extra indentation space or new line will be added for cosmetic purposes. 🙈
  • empty — tags that don't need to be closed. 🎀
  • ignore — tags that po4a ignores and treats as plain char data. meaning: they can be part of an msgid. for example, <b> is a great candidate for this category, since putting it in the translate section would create msgids with only its content (and it's usually not a whole sentence), which is bad. 💀
  • attributes — a space-separated list of attributes that need to be translated. you can specify attributes by their name (for example, "lang"), but you can also prefix it with a tag hierarchy to say that this attribute only gets translated when it's inside the specified tag. for example: "<bbb><aaa>lang" means the lang attribute will only be translated if it's in an <aaa> tag, which is in a <bbb> tag. the tag names are actually regular expressions, so you can also write stuff like "<aaa|bbb>lang" to only translate "lang" attributes that live in an <aaa> or a <bbb> tag. 🔥
  • qualify — a space-separated list of attributes for which the translation must be qualified by the attribute name, i.e. the text extracted for translation will include both the attribute name and it's value. e.g. for a tag like <aaa lang_en="foo"> translators will be presented with the string lang_en="foo". note that this also automatically adds the given attribute into the attributes list too. 👑
  • force — proceed even if the DTD is unknown or if onsgmls finds errors in the input file. 😤
  • include-all — by default, msgids containing only one entity (like "&version;") are skipped for the translators' comfort. turning this option on prevents that optimisation. it can be useful if the document contains a construction like "<title>&Aacute;</title>", even if I doubt such things ever happen... 🙈
  • ignore-inclusion — a space-separated list of entities that won't be inlined. use this option with caution: it may cause onsgmls (which is used internally) to add tags and render the output document invalid. ⚠️

🦋 STATUS OF THIS MODULE 🦋

the result is perfect. i.e., the generated documents are exactly the same as the originals. but there are still some problems:

  • the error output of onsgmls is redirected to /dev/null by default, 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).

if you want to view the onsgmls output, just add the following to your command line (or po4a configuration line):

-o debug=onsgmls
  • it does work only with the DebianDoc and DocBook DTD. adding support for a new DTD should be very easy. the mechanism is the same for every DTD, you just have to give a list of the existing tags and some of their characteristics. 🧚

I agree, this needs some more documentation, but it's still considered beta, and I hate to document stuff which may/will change.

  • warning, support for DTDs is quite experimental. ⚠️ I did not read any reference manual to find the definition of every tag. I did add tag definitions to the module 'till it works for some documents I found on the net. if your document uses more tags than mine, it won't work. but as I said above, fixing that should be quite easy.

I did test DocBook against the SAG (System Administrator Guide) only, but this document is quite big, and should use most of the DocBook specificities. 🔥

for DebianDoc, I tested some of the manuals from the DDP, but not all yet.

  • in case of file inclusion, string reference of messages in PO files (i.e. lines like "#: en/titletoc.sgml:9460") will be wrong. 💀

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 in the generated document. for that, I make a temp copy of the input file and do all the changes I want to it before passing it to onsgmls for parsing.

so that it works, I replace the entities asking for a file inclusion by the content of the given file (so that I can protect what needs to be in a subfile also). but nothing is done so far to correct the references (i.e., filename and line number) afterward. I'm not sure what the best thing to do is.

🌈 AUTHORS 🌈

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

 Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>

the adaptation for po4a was done by:

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
 Copyright © 2002-2005 SPI, Inc.

this program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). 🫶

ok that's the whole tea bestie, no cap 💅 this page is perl v5.42.0, dated 2025-07-13 — slay, go translate some SGML 🌸✨🎀
📦 where this page comes from