1Locale::Po4a::Man(3pm)            Po4a Tools            Locale::Po4a::Man(3pm)
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 permits to change the behavior of the module when it
95           encounter a .de, .ie or .if section. It can take the following
96           values:
97
98           fail
99               This is the default value.  The module will fail when a .de,
100               .ie or .if section is encountered.
101
102           verbatim
103               Indicates that the .de, .ie or .if sections must be copied as
104               is from the original to the translated document.
105
106           translate
107               Indicates that the .de, .ie or .if sections will be proposed
108               for the translation.  You should only use this option if a
109               translatable string is contained in one of these section.
110               Otherwise, verbatim should be preferred.
111
112       generated
113           This option specifies that the file was generated, and that po4a
114           should not try to detect if the man pages was generated from
115           another format.  This permits to use po4a on generated man pages.
116           This option does not take any argument.
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 permit to specify the behavior of a new macro
136       (defined with a .de request), or of a macro not supported by po4a.
137       They take as argument a comma-separated list of macros.  For example:
138
139        -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
140
141       Note: if a macro is not supported by po4a and if you consider that it
142       is a standard roff macro, you should submit it to the po4a development
143       team.
144
145       untranslated
146           untranslated indicates that this macro (at its arguments) don't
147           have to be translated.
148
149       noarg
150           noarg is like untranslated, except that po4a will verify that no
151           argument is added to this macro.
152
153       translate_joined
154           translate_joined indicates that po4a must propose to translate the
155           arguments of the macro.
156
157       translate_each
158           With translate_each, the arguments will also be proposed for the
159           translation, except that each one will be translated separately.
160
161       no_wrap
162           This option takes as argument a list of comma-separated couples
163           begin:end, where begin and end are commands that delimit the begin
164           and end of a section that should not be rewrapped.
165
166           Note: no test is done to ensure that an end command matches its
167           begin command; any ending command stop the no_wrap mode.  If you
168           have a begin (respectively end) macro that has no end (respectively
169           begin), you can specify an existing end (like fi) or begin (like
170           nf) as a counterpart.  These macros (and their arguments) wont be
171           translated.
172
173       inline
174           This option specifies a list of comma-separated macros that must
175           not split the current paragraph. The string to translate will then
176           contain foo <.bar baz qux> quux, where bar is the command that
177           should be inlined, and baz qux its arguments.
178
179       unknown_macros
180           This option indicates how po4a should behave when an unknown macro
181           is found.  By default, po4a fails with a warning.  It can take the
182           following values: failed (the default value), untranslated, noarg,
183           translate_joined, or translate_each (see above for an explanation
184           of these values).
185

AUTHORING MAN PAGES COMPLIANT WITH PO4A::MAN

187       This module is still very limited, and will always be, because it's not
188       a real nroff interpreter. It would be possible to do a real nroff
189       interpreter, to allow authors to use all the existing macros, or even
190       to define new ones in their pages, but we didn't want to. It would be
191       too difficult, and we thought it wasn't necessary. We do think that if
192       manpages' authors want to see their productions translated, they may
193       have to adapt to ease the work of translators.
194
195       So, the man parser implemented in po4a have some known limitations we
196       are not really inclined to correct, and which will constitute some
197       pitfalls you'll have to avoid if you want to see translators taking
198       care of your documentation.
199
200   Don't program in nroff
201       nroff is a complete programming language, with macro definition,
202       conditionals and so on. Since this parser isn't a fully featured nroff
203       interpreter, it will fail on pages using these facilities (There are
204       about 200 such pages on my box).
205
206   Use the plain macro set
207       There are still some macros which are not supported by po4a::man. This
208       is only because I failed to find any documentation about them. Here is
209       the list of unsupported macros used on my box. Note that this list
210       isn't exhaustive since the program fails on the first encountered
211       unsupported macro. If you have any information about some of these
212       macros, I'll happily add support for them. Because of these macros,
213       about 250 pages on my box are inaccessible to po4a::man.
214
215        ..               ."              .AT             .b              .bank
216        .BE              ..br            .Bu             .BUGS           .BY
217        .ce              .dbmmanage      .do                             .En
218        .EP              .EX             .Fi             .hw             .i
219        .Id              .l              .LO             .mf
220        .N               .na             .NF             .nh             .nl
221        .Nm              .ns             .NXR            .OPTIONS        .PB
222        .pp              .PR             .PRE            .PU             .REq
223        .RH              .rn             .S<             .sh             .SI
224        .splitfont       .Sx             .T              .TF             .The
225        .TT              .UC             .ul             .Vb             .zZ
226
227   Hiding text from po4a
228       Sometimes, the author knows that some parts are not translatable, and
229       should not be extracted by po4a. For example, an option may accept an
230       other argument, and other may also appear as the last item of a list.
231       In the first case, other should be not be translatable. And in the
232       second case, other should be translated.
233
234       In such case, the author can avoid po4a to extract some strings, using
235       some special groff constructs:
236
237        .if !'po4a'hide' .B other
238
239       (this will require the -o groff_code=verbatim option)
240
241       A new macro can also be defined to automate this:
242        .de IR_untranslated
243        .    IR \\$@
244        ..
245
246        .IR_untranslated \-q ", " \-\-quiet
247
248       (this will require the options -o groff_code=verbatim and -o
249       untranslated=IR_untranslated; with this construct, the .if !'po4a'hide'
250       conditional is not strictly needed since po4a will not parse the
251       internal of the macro definition)
252
253       or using an alias:
254        .als IR_untranslated IR
255
256        .IR_untranslated \-q ", " \-\-quiet
257
258       This will require the -o untranslated=als,IR_untranslated option.
259
260   Conclusion
261       To summarise this section, keep simple, and don't try to be clever
262       while authoring your man pages. A lot of things are possible in nroff,
263       and not supported by this parser. For example, don't try to mess with
264       \c to interrupt the text processing (like 40 pages on my box do). Or,
265       be sure to put the macro arguments on the same line that the macro
266       itself. I know that it's valid in nroff, but would complicate too much
267       the parser to be handled.
268
269       Of course, another possibility is to use another format, more
270       translator friendly (like POD using po4a::pod, or one of the XML family
271       like SGML), but thanks to po4a::man it isn't needed anymore. That being
272       said, if the source format of your documentation is POD, or XML, it may
273       be clever to translate the source format and not this generated one. In
274       most cases, po4a::man will detect generated pages and issue a warning.
275       It will even refuse to process POD generated pages, because those pages
276       are perfectly handled by po4a::pod, and because their nroff counterpart
277       defines a lot of new macros I didn't want to write support for. On my
278       box, 1432 of the 4323 pages are generated from POD and will be ignored
279       by po4a::man.
280
281       In most cases, po4a::man will detect the problem and refuse to process
282       the page, issuing an adapted message. In some rare cases, the program
283       will complete without warning, but the output will be wrong. Such cases
284       are called "bugs" ;) If you encounter such case, be sure to report
285       this, along with a fix when possible…
286

STATUS OF THIS MODULE

288       This module can be used for most of the existing man pages.
289
290       Some tests are regularly run on Linux boxes:
291
292       ·   one third of the pages are refused because they were generated from
293           another format supported by po4a (e.g. POD or SGML).
294
295       ·   10% of the remaining pages are rejected with an error (e.g. a groff
296           macro is not supported).
297
298       ·   Then, less than 1% of the pages are accepted silently by po4a, but
299           with significant issues (i.e. missing words, or new words inserted)
300
301       ·   The other pages are usually handled without differences more
302           important than spacing differences or line rewrapped (font issues
303           in less than 10% of the processed pages).
304

SEE ALSO

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

AUTHORS

309        Denis Barbier <barbier@linuxfr.org>
310        Nicolas François <nicolas.francois@centraliens.net>
311        Martin Quinson (mquinson#debian.org)
312
314       Copyright © 2002-2008 SPI, Inc.
315
316       This program is free software; you may redistribute it and/or modify it
317       under the terms of GPL (see the COPYING file).
318
319
320
321Po4a Tools                        2021-02-23            Locale::Po4a::Man(3pm)
Impressum