1Locale::Po4a::Sgml(3pm)           Po4a Tools           Locale::Po4a::Sgml(3pm)
2
3
4

NAME

6       Locale::Po4a::Sgml - convert SGML documents from/to PO files
7

DESCRIPTION

9       The po4a (PO for anything) project goal is to ease translations (and
10       more interestingly, the maintenance of translations) using gettext
11       tools on areas where they were not expected like documentation.
12
13       Locale::Po4a::Sgml is a module to help the translation of documentation
14       in the SGML format into other [human] languages.
15
16       This module uses onsgmls(1) to parse the SGML files. Make sure it is
17       installed.  Also make sure that the DTD of the SGML files are installed
18       in the system.
19

OPTIONS ACCEPTED BY THIS MODULE

21       debug
22           Space separated list of keywords indicating which part you want to
23           debug. Possible values are: tag, generic, entities and refs.
24
25       verbose
26           Give more information about what's going on.
27
28       translate
29           Space separated list of extra tags (beside the DTD provided ones)
30           whose content should form an extra msgid.
31
32       section
33           Space separated list of extra tags (beside the DTD provided ones)
34           containing other tags, some of them being of category translate.
35
36       indent
37           Space separated list of tags which increase the indentation level.
38
39       verbatim
40           The layout within those tags should not be changed. The paragraph
41           won't get wrapped, and no extra indentation space or new line will
42           be added for cosmetic purpose.
43
44       empty
45           Tags not needing to be closed.
46
47       ignore
48           Tags ignored and considered as plain char data by po4a. That is to
49           say that they can be part of an msgid. For example, <b> is a good
50           candidate for this category since putting it in the translate
51           section would create msgids not being whole sentences, which is
52           bad.
53
54       attributes
55           A space separated list of attributes that need to be translated.
56           You can specify the attributes by their name (for example, "lang"),
57           but you can also prefix it with a tag hierarchy, to specify that
58           this attribute will only be translated when it is into the
59           specified tag. For example: <bbb><aaa>lang specifies that the lang
60           attribute will only be translated if it is in an <aaa> tag, which
61           is in a <bbb> tag.  The tag names are actually regular expressions
62           so you can also write things like <aaa|bbbb>lang to only translate
63           lang attributes that are in an <aaa> or a <bbb> tag.
64
65       qualify
66           A space separated list of attributes for which the translation must
67           be qualified by the attribute name. Note that this setting
68           automatically adds the given attribute into the 'attributes' list
69           too.
70
71       force
72           Proceed even if the DTD is unknown or if onsgmls finds errors in
73           the input file.
74
75       include-all
76           By default, msgids containing only one entity (like '&version;')
77           are skipped for the translator comfort. Activating this option
78           prevents this optimisation. It can be useful if the document
79           contains a construction like "<title>&Aacute;</title>", even if I
80           doubt such things to ever happen...
81
82       ignore-inclusion
83           Space separated list of entities that won't be inlined.  Use this
84           option with caution: it may cause onsgmls (used internally) to add
85           tags and render the output document invalid.
86

STATUS OF THIS MODULE

88       The result is perfect. I.e., the generated documents are exactly the
89       same. But there are still some problems:
90
91       • The error output of onsgmls is redirected to /dev/null by default,
92         which is clearly bad. I don't know how to avoid that.
93
94         The problem is that I have to "protect" the conditional inclusions
95         (i.e. the "<! [ %foo [" and "]]>" stuff) from onsgmls. Otherwise
96         onsgmls eats them, and I don't know how to restore them in the final
97         document. To prevent that, I rewrite them to "{PO4A-beg-foo}" and
98         "{PO4A-end}".
99
100         The problem with this is that the "{PO4A-end}" and such I add are
101         invalid in the document (not in a <p> tag or so).
102
103         If you want to view the onsgmls output, just add the following to
104         your command line (or po4a configuration line):
105
106           -o debug=onsgmls
107
108       • It does work only with the DebianDoc and DocBook DTD. Adding support
109         for a new DTD should be very easy. The mechanism is the same for
110         every DTD, you just have to give a list of the existing tags and some
111         of their characteristics.
112
113         I agree, this needs some more documentation, but it is still
114         considered as beta, and I hate to document stuff which may/will
115         change.
116
117       • Warning, support for DTDs is quite experimental. I did not read any
118         reference manual to find the definition of every tag. I did add tag
119         definition to the module 'till it works for some documents I found on
120         the net. If your document use more tags than mine, it won't work. But
121         as I said above, fixing that should be quite easy.
122
123         I did test DocBook against the SAG (System Administrator Guide) only,
124         but this document is quite big, and should use most of the DocBook
125         specificities.
126
127         For DebianDoc, I tested some of the manuals from the DDP, but not all
128         yet.
129
130       • In case of file inclusion, string reference of messages in PO files
131         (i.e. lines like "#: en/titletoc.sgml:9460") will be wrong.
132
133         This is because I preprocess the file to protect the conditional
134         inclusion (i.e. the "<! [ %foo [" and "]]>" stuff) and some entities
135         (like &version;) from onsgmls because I want them verbatim to the
136         generated document. For that, I make a temp copy of the input file
137         and do all the changes I want to this before passing it to onsgmls
138         for parsing.
139
140         So that it works, I replace the entities asking for a file inclusion
141         by the content of the given file (so that I can protect what needs to
142         be in a subfile also). But nothing is done so far to correct the
143         references (i.e., filename and line number) afterward. I'm not sure
144         what the best thing to do is.
145

AUTHORS

147       This module is an adapted version of sgmlspl (SGML postprocessor for
148       the ONSGMLS parser) which was:
149
150        Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>
151
152       The adaptation for po4a was done by:
153
154        Denis Barbier <barbier@linuxfr.org>
155        Martin Quinson (mquinson#debian.org)
156
158        Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
159        Copyright © 2002-2005 SPI, Inc.
160
161       This program is free software; you may redistribute it and/or modify it
162       under the terms of GPL (see the COPYING file).
163
164
165
166Po4a Tools                        2023-01-23           Locale::Po4a::Sgml(3pm)
Impressum