1LOCALE::PO4A::MAN.3PM(1U)ser Contributed Perl DocumentatiLoOnCALE::PO4A::MAN.3PM(1)
2
3
4

NAME

6       Locale::Po4a::Man - convert manual pages 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::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

TRANSLATING WITH PO4A::MAN

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
23   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
29       Anyway, the difference will only be about the position of the extra
30       spaces in wrapped paragraph, and I think it's worth.
31
32   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
38       I<text> -- italic text
39           equivalent to \fItext\fP or ".I text"
40
41       B<text> -- bold text
42           equivalent to \fBtext\fP or ".B text"
43
44       R<text> -- roman text
45           equivalent to \fRtext\fP
46
47       CW<text> -- constant width text
48           equivalent to \f(CWtext\fP or ".CW text"
49
50       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
53   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
58       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
64           Translators can force an hyphen by using the roff glyph '\[hy]' in
65           their translations.
66
67       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
72       quotes transliterations
73           `` and '' are respectively tranliterated into \*(lq and \*(rq.
74
75           To avoid these transliterations, translators can insert a zero
76           width roff character (i.e., using `\&` or '\&' respectively).
77
78   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

OPTIONS ACCEPTED BY THIS MODULE

84       These are this module's particular options:
85
86       debug
87           Activate debugging for some internal mechanisms of this module.
88           Use the source to see which parts can be debugged.
89
90       verbose
91           Increase verbosity.
92
93       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
97           fail
98               This is the default value.  The module will fail when a .de,
99               .ie or .if section is encountered.
100
101           verbatim
102               Indicates that the .de, .ie or .if sections must be copied as
103               is from the original to the translated document.
104
105           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
111       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
118       mdoc
119           This option is only useful for mdoc pages.
120
121           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
125           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
131           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
135       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
140        -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
141
142       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
146       untranslated
147           untranslated indicates that this macro (at its arguments) don't
148           have to be translated.
149
150       noarg
151           noarg is like untranslated, except that po4a will verify that no
152           argument is added to this macro.
153
154       translate_joined
155           translate_joined indicates that po4a must propose to translate the
156           arguments of the macro.
157
158       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
162       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
167           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
174       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
180       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

AUTHORING MAN PAGES COMPLIANT WITH PO4A::MAN

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
196       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
201   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
207   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
216        ..               ."              .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
228   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
235       In such case, the author can avoid po4a to extract some strings, using
236       some special groff constructs:
237
238        .if !'po4a'hide' .B other
239
240       (this will require the -o groff_code=verbatim option)
241
242       A new macro can also be defined to automate this:
243        .de IR_untranslated
244        .    IR \\$@
245        ..
246
247        .IR_untranslated \-q ", " \-\-quiet
248
249       (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
254       or using an alias:
255        .als IR_untranslated IR
256
257        .IR_untranslated \-q ", " \-\-quiet
258
259       This will require the -o untranslated=als,IR_untranslated option.
260
261   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
270       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
282       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

STATUS OF THIS MODULE

289       This module can be used for most of the existing man pages.
290
291       Some tests are regularly run on Linux boxes:
292
293       •   one third of the pages are refused because they were generated from
294           another format supported by po4a (e.g. POD or SGML).
295
296       •   10% of the remaining pages are rejected with an error (e.g. a groff
297           macro is not supported).
298
299       •   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
302       •   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

SEE ALSO

307       Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
308

AUTHORS

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
317       This program is free software; you may redistribute it and/or modify it
318       under the terms of GPL (see the COPYING file).
319
320
321
322perl v5.36.0                      2023-01-23          LOCALE::PO4A::MAN.3PM(1)
Impressum