1LOCALE::PO4A::MAN.3PM(1U)ser Contributed Perl DocumentatiLoOnCALE::PO4A::MAN.3PM(1)
2
6 Locale::Po4a::Man - convert manual pages 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::Man is a module to help the translation of documentation
14 in the nroff format (the language of manual pages) into other [human]
15 languages.
16
18 This module tries pretty hard to make translator's life easier. For
19 that, the text presented to translators isn't a verbatim copy of the
20 text found in the man page. Indeed, the cruder parts of the nroff
21 format are hidden, so that translators can't mess up with them.
22 Text wrapping
24 Unindented paragraphs are automatically rewrapped for the translator.
25 This can lead to some minor difference in the generated output, since
26 the rewrapping rules used by groff aren't very clear. For example, two
27 spaces after a parenthesis are sometimes preserved.
28 Anyway, the difference will only be about the position of the extra
30 spaces in wrapped paragraph, and I think it's worth.
31 Font specification
33 The first change is about font change specifications. In nroff, there
34 are several ways to specify if a given word should be written in small,
35 bold or italics. In the text to translate, there is only one way,
36 borrowed from the POD (Perl online documentation) format:
37 I<text> -- italic text
39 equivalent to \fItext\fP or ".I text"
40 B<text> -- bold text
42 equivalent to \fBtext\fP or ".B text"
43 R<text> -- roman text
45 equivalent to \fRtext\fP
46 CW<text> -- constant width text
48 equivalent to \f(CWtext\fP or ".CW text"
49 Remark: The CW face is not available for all groff devices. It is not
51 recommended to use it. It is provided for your convenience.
52 Automatic characters transliteration
54 Po4a automatically transliterate some characters to ease the
55 translation or the review of the translation. Here is the list of the
56 transliterations:
57 hyphens
59 Hyphens (-) and minus signs (\-) in man pages are all
60 transliterated as simple dashes (-) in the PO file. Then all dash
61 are transliterated into roff minus signs (\-) when the translation
62 is inserted into the output document.
63 Translators can force an hyphen by using the roff glyph '\[hy]' in
65 their translations.
66 non-breaking spaces
68 Translators can use non-breaking spaces in their translations.
69 These non-breaking spaces (0xA0 in latin1) will be transliterated
70 into a roff non-breaking space ('\ ').
71 quotes transliterations
73 `` and '' are respectively tranliterated into \*(lq and \*(rq.
74 To avoid these transliterations, translators can insert a zero
76 width roff character (i.e., using `\&` or '\&' respectively).
77 Putting '<' and '>' in translations
79 Since these chars are used to delimit parts under font modification,
80 you can't use them verbatim. Use E<lt> and E<gt> instead (as in POD,
81 one more time).
82
84 These are this module's particular options:
85 debug
87 Activate debugging for some internal mechanisms of this module.
88 Use the source to see which parts can be debugged.
89 verbose
91 Increase verbosity.
92 groff_code
94 This option controls the behavior of the module when it encounter a
95 .de, .ie or .if section. It can take the following values:
96 fail
98 This is the default value. The module will fail when a .de,
99 .ie or .if section is encountered.
100 verbatim
102 Indicates that the .de, .ie or .if sections must be copied as
103 is from the original to the translated document.
104 translate
106 Indicates that the .de, .ie or .if sections will be proposed
107 for the translation. You should only use this option if a
108 translatable string is contained in one of these section.
109 Otherwise, verbatim should be preferred.
110 generated
112 This option specifies that the file was generated, and that po4a
113 should not try to detect if the man pages was generated from
114 another format. This option is mandatory to use po4a on generated
115 man pages. Note that translating generated pages instead of
116 sources ones is often more fragile, and thus a bad idea.
117 mdoc
119 This option is only useful for mdoc pages.
120 It selects a stricter support of the mdoc format by telling po4a
122 not to translate the 'NAME' section. mdoc pages whose 'NAME'
123 section is translated won't generate any header or footer.
124 According to the groff_mdoc page, the NAME, SYNOPSIS and
126 DESCRIPTION sections are mandatory. There are no known issues with
127 translated SYNOPSIS or DESCRIPTION section, but you can also
128 specify these sections this way:
129 -o mdoc=NAME,SYNOPSIS,DESCRIPTION
130 This mdoc issue can also be solved with an addendum like this one:
132 PO4A-HEADER:mode=before;position=^.Dd
133 .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
134 The following options specify the behavior of a user-defined macro
136 (with a .de request), or of a classical macro that is not supported by
137 po4a. They take as argument a comma-separated list of macros. For
138 example:
139 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
141 Note: if a macro is not supported by po4a and if you consider that it
143 is a standard roff macro, you should submit it to the po4a development
144 team.
145 untranslated
147 untranslated indicates that this macro (at its arguments) don't
148 have to be translated.
149 noarg
151 noarg is like untranslated, except that po4a will verify that no
152 argument is added to this macro.
153 translate_joined
155 translate_joined indicates that po4a must propose to translate the
156 arguments of the macro.
157 translate_each
159 With translate_each, the arguments will also be proposed for the
160 translation, except that each one will be translated separately.
161 no_wrap
163 This option takes as argument a list of comma-separated couples
164 begin:end, where begin and end are commands that delimit the begin
165 and end of a section that should not be rewrapped.
166 Note: no test is done to ensure that an end command matches its
168 begin command; any ending command stop the no_wrap mode. If you
169 have a begin (respectively end) macro that has no end (respectively
170 begin), you can specify an existing end (like fi) or begin (like
171 nf) as a counterpart. These macros (and their arguments) won't be
172 translated.
173 inline
175 This option specifies a list of comma-separated macros that must
176 not split the current paragraph. The string to translate will then
177 contain foo <.bar baz qux> quux, where bar is the command that
178 should be inlined, and baz qux its arguments.
179 unknown_macros
181 This option indicates how po4a should behave when an unknown macro
182 is found. By default, po4a fails with a warning. It can take the
183 following values: failed (the default value), untranslated, noarg,
184 translate_joined, or translate_each (see above for an explanation
185 of these values).
186
188 This module is still very limited, and will always be, because it's not
189 a real nroff interpreter. It would be possible to do a real nroff
190 interpreter, to allow authors to use all the existing macros, or even
191 to define new ones in their pages, but we didn't want to. It would be
192 too difficult, and we thought it wasn't necessary. We do think that if
193 manpages' authors want to see their productions translated, they may
194 have to adapt to ease the work of translators.
195 So, the man parser implemented in po4a have some known limitations we
197 are not really inclined to correct, and which will constitute some
198 pitfalls you'll have to avoid if you want to see translators taking
199 care of your documentation.
200 Don't program in nroff
202 nroff is a complete programming language, with macro definition,
203 conditionals and so on. Since this parser isn't a fully featured nroff
204 interpreter, it will fail on pages using these facilities (There are
205 about 200 such pages on my box).
206 Use the plain macro set
208 There are still some macros which are not supported by po4a::man. This
209 is only because I failed to find any documentation about them. Here is
210 the list of unsupported macros used on my box. Note that this list
211 isn't exhaustive since the program fails on the first encountered
212 unsupported macro. If you have any information about some of these
213 macros, I'll happily add support for them. Because of these macros,
214 about 250 pages on my box are inaccessible to po4a::man.
215 .. ." .AT .b .bank
217 .BE ..br .Bu .BUGS .BY
218 .ce .dbmmanage .do .En
219 .EP .EX .Fi .hw .i
220 .Id .l .LO .mf
221 .N .na .NF .nh .nl
222 .Nm .ns .NXR .OPTIONS .PB
223 .pp .PR .PRE .PU .REq
224 .RH .rn .S< .sh .SI
225 .splitfont .Sx .T .TF .The
226 .TT .UC .ul .Vb .zZ
227 Hiding text from po4a
229 Sometimes, the author knows that some parts are not translatable, and
230 should not be extracted by po4a. For example, an option may accept an
231 other argument, and other may also appear as the last item of a list.
232 In the first case, other should be not be translatable. And in the
233 second case, other should be translated.
234 In such case, the author can avoid po4a to extract some strings, using
236 some special groff constructs:
237 .if !'po4a'hide' .B other
239 (this will require the -o groff_code=verbatim option)
241 A new macro can also be defined to automate this:
243 .de IR_untranslated
244 . IR \\$@
245 ..
246 .IR_untranslated \-q ", " \-\-quiet
248 (this will require the options -o groff_code=verbatim and -o
250 untranslated=IR_untranslated; with this construct, the .if !'po4a'hide'
251 conditional is not strictly needed since po4a will not parse the
252 internal of the macro definition)
253 or using an alias:
255 .als IR_untranslated IR
256 .IR_untranslated \-q ", " \-\-quiet
258 This will require the -o untranslated=als,IR_untranslated option.
260 Conclusion
262 To summarise this section, keep simple, and don't try to be clever
263 while authoring your man pages. A lot of things are possible in nroff,
264 and not supported by this parser. For example, don't try to mess with
265 \c to interrupt the text processing (like 40 pages on my box do). Or,
266 be sure to put the macro arguments on the same line that the macro
267 itself. I know that it's valid in nroff, but would complicate too much
268 the parser to be handled.
269 Of course, another possibility is to use another format, more
271 translator friendly (like POD using po4a::pod, or one of the XML family
272 like SGML), but thanks to po4a::man it isn't needed anymore. That being
273 said, if the source format of your documentation is POD, or XML, it may
274 be clever to translate the source format and not this generated one. In
275 most cases, po4a::man will detect generated pages and issue a warning.
276 It will even refuse to process POD generated pages, because those pages
277 are perfectly handled by po4a::pod, and because their nroff counterpart
278 defines a lot of new macros I didn't want to write support for. On my
279 box, 1432 of the 4323 pages are generated from POD and will be ignored
280 by po4a::man.
281 In most cases, po4a::man will detect the problem and refuse to process
283 the page, issuing an adapted message. In some rare cases, the program
284 will complete without warning, but the output will be wrong. Such cases
285 are called "bugs" ;) If you encounter such case, be sure to report
286 this, along with a fix when possible…
287
289 This module can be used for most of the existing man pages.
290 Some tests are regularly run on Linux boxes:
292 • one third of the pages are refused because they were generated from
294 another format supported by po4a (e.g. POD or SGML).
295 • 10% of the remaining pages are rejected with an error (e.g. a groff
297 macro is not supported).
298 • Then, less than 1% of the pages are accepted silently by po4a, but
300 with significant issues (i.e. missing words, or new words inserted)
301 • The other pages are usually handled without differences more
303 important than spacing differences or line rewrapped (font issues
304 in less than 10% of the processed pages).
305
307 Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
308
310 Denis Barbier <barbier@linuxfr.org>
311 Nicolas François <nicolas.francois@centraliens.net>
312 Martin Quinson (mquinson#debian.org)
313
315 Copyright © 2002-2008 SPI, Inc.
316 This program is free software; you may redistribute it and/or modify it
318 under the terms of GPL (see the COPYING file).
319perl v5.36.0 2023-01-23 LOCALE::PO4A::MAN.3PM(1)