1Locale::Po4a::Sgml(3) User Contributed Perl DocumentationLocale::Po4a::Sgml(3)
2
6 Locale::Po4a::Sgml - Convert sgml documents from/to PO files
7
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 Locale::Po4a::Sgml is a module to help the translation of documentation
14 in the SGML format into other [human] languages.
15
17 debug
18 Space separated list of keywords indicating which part you want to
19 debug. Possible values are: tag, generic, entities and refs.
20 verbose
22 Give more information about what's going on.
23 translate
25 Space separated list of extra tags (beside the dtd provided ones)
26 whose content should form an extra msgid.
27 section
29 Space separated list of extra tags (beside the dtd provided ones)
30 containing other tags, some of them being of category 'translate'.
31 indent
33 Space separated list of tags which increase the indentation level.
34 verbatim
36 The layout within those tags should not be changed. The paragraph
37 won't get wrapped, and no extra indentation space or new line will
38 be added for cosmetic purpose.
39 empty
41 Tags not needing to be closed.
42 ignore
44 Tags ignored and considered as plain char data by po4a. That is to
45 say that they can be part of an msgid. For example, <b> is a good
46 candidate for this category since putting it in the translate sec‐
47 tion would create msgids not being whole sentences, which is bad.
48 attributes
50 A space separated list of attributes that need to be translated.
51 You can specify the attributes by their name (for example, "lang"),
52 but you can also prefix it with a tag hierarchy, to specify that
53 this attribute will only be translated when it is into the speci‐
54 fied tag. For example: <bbb><aaa>lang specifies that the lang
55 attribute will only be translated if it is in an <aaa> tag, which
56 is in a <bbb> tag. The tag names are actually regular expressions
57 so you can also write things like <aaa⎪bbbb>lang to only translate
58 lang attributes that are in an <aaa> or a <bbb> tag.
59 qualify
61 A space separated list of attributes for which the translation must
62 be qualified by the attribute name. Note that this setting automat‐
63 ically adds the given attribute into the 'attributes' list too.
64 force
66 Proceed even if the DTD is unknown.
67 include-all
69 By default, msgids containing only one entity (like '&version;')
70 are skipped for the translator comfort. Activating this option pre‐
71 vents this optimisation. It can be useful if the document contains
72 a construction like "<title>Á</title>", even if I doubt such
73 things to ever happen...
74 ignore-inclusion
76 Space separated list of entities that won't be inlined. Use this
77 option with caution: it may cause nsgmls (used internally) to add
78 tags and render the output document invalid.
79
81 The result is perfect. I.e., the generated documents are exactly the
82 same. But there are still some problems:
83 · the error output of nsgmls is redirected to /dev/null, which is
85 clearly bad. I don't know how to avoid that.
86 The problem is that I have to "protect" the conditional inclusions
88 (ie, the "<! [ %foo [" and "]]>" stuff) from nsgmls. Otherwise nsgmls
89 eats them, and I don't know how to restore them in the final docu‐
90 ment. To prevent that, I rewrite them to "{PO4A-beg-foo}" and
91 "{PO4A-end}".
92 The problem with this is that the "{PO4A-end}" and such I add are
94 valid in the document (not in a <p> tag or so).
95 Everything works well with nsgmls's output redirected that way, but
97 it will prevent us from detecting that the document is badly format‐
98 ted.
99 · It does work only with the debiandoc and docbook dtd. Adding support
101 for a new dtd should be very easy. The mechanism is the same for
102 every dtd, you just have to give a list of the existing tags and some
103 of their characteristics.
104 I agree, this needs some more documentation, but it is still consid‐
106 ered as beta, and I hate to document stuff which may/will change.
107 · Warning, support for dtds is quite experimental. I did not read any
109 reference manual to find the definition of every tag. I did add tag
110 definition to the module 'till it works for some documents I found on
111 the net. If your document use more tags than mine, it won't work. But
112 as I said above, fixing that should be quite easy.
113 I did test docbook against the SAG (System Administrator Guide) only,
115 but this document is quite big, and should use most of the docbook
116 specificities.
117 For debiandoc, I tested some of the manuals from the DDP, but not all
119 yet.
120 · In case of file inclusion, string reference of messages in po files
122 (ie, lines like "#: en/titletoc.sgml:9460") will be wrong.
123 This is because I preprocess the file to protect the conditional
125 inclusion (ie, the "<! [ %foo [" and "]]>" stuff) and some entities
126 (like &version;) from nsgmls because I want them verbatim to the gen‐
127 erated document. For that, I make a temp copy of the input file and
128 do all the changes I want to this before passing it to nsgmls for
129 parsing.
130 So that it works, I replace the entities asking for a file inclusion
132 by the content of the given file (so that I can protect what needs to
133 in subfile also). But nothing is done so far to correct the refer‐
134 ences (i.e., filename and line number) afterward. I'm not sure what
135 the best thing to do is.
136
138 This module is an adapted version of sgmlspl (SGML postprocessor for
139 the SGMLS and NSGMLS parsers) which was:
140 Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
142 The adaptation for po4a was done by:
144 Denis Barbier <barbier@linuxfr.org>
146 Martin Quinson (mquinson#debian.org)
147
149 Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
150 Copyright 2002, 2003, 2004, 2005 by SPI, inc.
151 This program is free software; you may redistribute it and/or modify it
153 under the terms of GPL (see the COPYING file).
154perl v5.8.8 2008-06-01 Locale::Po4a::Sgml(3)