1Locale::Po4a::Man(3) User Contributed Perl Documentation Locale::Po4a::Man(3)
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 for‐
21 mat are hidden, so that translators can't mess up with them.
22 Text wrapping
24 Unindented paragraphs are automatically rewrapped for the translator.
26 This can lead to some minor difference in the generated output, since
27 the rewrapping rules used by groff aren't very clear. For example, two
28 spaces after a parenthesis are sometimes preserved, while typographic
29 rules only ask to preserve the two spaces after the period sign (ok,
30 I'm not native speaker, and I'm not sure of that. If you have any other
31 information, you're welcome).
32 Anyway, the difference will only be about the position of the extra
34 spaces in wrapped paragraph, and I think it's worth.
35 Font specification
37 The first change is about font change specifications. In nroff, there
39 are several ways to specify if a given word should be written in small,
40 bold or italics. In the text to translate, there is only one way, bor‐
41 rowed from the pod (perl online documentation) format:
42 I<text> -- italic text
44 equivalent to \fItext\fP or ".I text"
45 B<text> -- bold text
47 equivalent to \fBtext\fP or ".B text"
48 R<text> -- roman text
50 equivalent to \fRtext\fP
51 CW<text> -- constant width text
53 equivalent to \f(CWtext\fP or ".CW text"
54 Remark: The CW face is not available for all groff devices. It is not
56 recommended to use it. It is provided for your convenience.
57 Automatic characters transliteration
59 Po4a automatically transliterate some characters to ease the transla‐
61 tion or the review of the translation. Here is the list of the
62 transliterations:
63 hyphens
65 Hyphens (-) and minus signs (\-) in man pages are all transliter‐
66 ated as simple dashes (-) in the PO file. Then all dash are
67 transliterated into roff minus signs (\-) when the translation is
68 inserted into the output document.
69 Translators can force an hyphen by using the roff glyph '\[hy]' in
71 their translations.
72 non-breaking spaces
74 Translators can use non-breaking spaces in their translations.
75 These non-breaking spaces (0xA0 in latin1) will be transliterated
76 into a roff non-breaking space ('\ ').
77 quotes transliterations
79 `` and '' are respectively tranliterated into \*(lq and \*(rq.
80 To avoid these transliterations, translators can insert a zero
82 width roff character (i.e., using `\&` or '\&' respectively).
83 Putting '<' and '>' in translations
85 Since these chars are used to delimit parts under font modification,
87 you can't use them verbatim. Use E<lt> and E<gt> instead (as in pod,
88 one more time).
89
91 These are this module's particular options:
92 debug
94 Activate debugging for some internal mechanisms of this module.
95 Use the source to see which parts can be debugged.
96 verbose
98 Increase verbosity.
99 groff_code
101 This option permits to change the behavior of the module when it
102 encounter a .de, .ie or .if section. It can take the following val‐
103 ues:
104 fail
106 This is the default value. The module will fail when a .de,
107 .ie or .if section is encountered.
108 verbatim
110 Indicates that the .de, .ie or .if sections must be copied as
111 is from the original to the translated document.
112 translate
114 Indicates that the .de, .ie or .if sections will be proposed
115 for the translation. You should only use this option if a
116 translatable string is contained in one of these section. Oth‐
117 erwise, verbatim should be preferred.
118 generated
120 This option specifies that the file was generated, and that po4a
121 should not try to detect if the man pages was generated from
122 another format. This permits to use po4a on generated man pages.
123 This option does not take any argument.
124 mdoc
126 This option is only useful for mdoc pages.
127 It selects a stricter support of the mdoc format by telling po4a
129 not to translate the 'NAME' section. mdoc pages whose 'NAME' sec‐
130 tion is translated won't generate any header of footer.
131 According to the groff_mdoc page, the NAME, SYNOPSIS and DESCRIP‐
133 TION sections are mandatory. There are no known issues with trans‐
134 lated SYNOPSIS or DESCRIPTION section, but you can also specify
135 these sections this way:
136 -o mdoc=NAME,SYNOPSIS,DESCRIPTION
137 This mdoc issue can also be solved with an addendum like this one:
139 PO4A-HEADER:mode=before;position=^.Dd
140 .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
141 The following options permit to specify the behavior of a new macro
143 (defined with a .de request), or of a macro not supported by po4a.
144 They take in argument a coma separated list of macros. For example:
145 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
147 Note: if a macro is not supported by po4a and if you consider that it
149 is a standard roff macro, you should submit it to the po4a development
150 team.
151 untranslated
153 untranslated indicates that this macro (at its arguments) don't
154 have to be translated.
155 noarg
157 noarg is like untranslated, except that po4a will verify that no
158 argument is added to this macro.
159 translate_joined
161 translate_joined indicates that po4a must propose to translate the
162 arguments of the macro.
163 translate_each
165 With translate_each, the arguments will also be proposed for the
166 translation, except that each one will be translated separately.
167 no_wrap
169 This option takes in argument a list of coma-separated couples
170 begin:end, where begin and end are commands that delimit the begin
171 and end of a section that should not be rewrapped.
172 Note: no test is done to ensure that an end command matches its
174 begin command; any ending command stop the no_wrap mode. If you
175 have a begin (respectively end) macro that has no end (respectively
176 begin), you can specify an existing end (like fi) or begin (like
177 nf) as a counterpart. These macros (and their arguments) wont be
178 translated.
179 inline
181 This option specifies a list of coma-separated macros that must not
182 split the current paragraph. The string to translate will then con‐
183 tain foo <.bar baz qux> quux, where bar is the command that should
184 be inlined, and baz qux its arguments.
185 unknown_macros
187 This option indicates how po4a should behave when an unknown macro
188 is found. By default, po4a fails with a warning. It can take the
189 following values: failed (the default value), untranslated, noarg,
190 translate_joined, translate_each.
191
193 This module is still very limited, and will always be, because it's not
194 a real nroff interpreter. It would be possible to do a real nroff
195 interpreter, to allow authors to use all the existing macros, or even
196 to define new ones in their pages, but we didn't want to. It would be
197 too difficult, and we thought it wasn't necessary. We do think that if
198 manpages' authors want to see their productions translated, they may
199 have to adapt to ease the work of translators.
200 So, the man parser implemented in po4a have some known limitations we
202 are not really inclined to correct, and which will constitute some pit‐
203 falls you'll have to avoid if you want to see translators taking care
204 of your documentation.
205 Don't program in nroff
207 nroff is a complete programming language, with macro definition, condi‐
209 tionals and so on. Since this parser isn't a fully featured nroff
210 interpreter, it will fail on pages using these facilities (There are
211 about 200 such pages on my box).
212 Use the plain macro set
214 There are still some macros which are not supported by po4a::man. This
216 is only because I failed to find any documentation about them. Here is
217 the list of unsupported macros used on my box. Note that this list
218 isn't exhaustive since the program fails on the first encountered
219 unsupported macro. If you have any information about some of these
220 macros, I'll happily add support for them. Because of these macros,
221 about 250 pages on my box are inaccessible to po4a::man.
222 .. ." .AT .b .bank
224 .BE ..br .Bu .BUGS .BY
225 .ce .dbmmanage .do .En
226 .EP .EX .Fi .hw .i
227 .Id .l .LO .mf
228 .N .na .NF .nh .nl
229 .Nm .ns .NXR .OPTIONS .PB
230 .pp .PR .PRE .PU .REq
231 .RH .rn .S< .sh .SI
232 .splitfont .Sx .T .TF .The
233 .TT .UC .ul .Vb .zZ
234 Conclusion
236 To summarise this section, keep simple, and don't try to be clever
238 while authoring your man pages. A lot of things are possible in nroff,
239 and not supported by this parser. For example, don't try to mess with
240 \c to interrupt the text processing (like 40 pages on my box do). Or,
241 be sure to put the macro arguments on the same line that the macro
242 itself. I know that it's valid in nroff, but would complicate too much
243 the parser to be handled.
244 Of course, another possibility is to use another format, more transla‐
246 tor friendly (like pod using po4a::pod, or one of the xml familly like
247 sgml), but thanks to po4a::man it isn't needed anymore. That being
248 said, if the source format of your documentation is pod, or xml, it may
249 be clever to translate the source format and not this generated one. In
250 most cases, po4a::man will detect generated pages and issue a warning.
251 It will even refuse to process Pod generated pages, because those pages
252 are perfectly handled by po4a::pod, and because their nroff counterpart
253 defines a lot of new macros I didn't want to write support for. On my
254 box, 1432 of the 4323 pages are generated from pod and will be ignored
255 by po4a::man.
256 In most cases, po4a::man will detect the problem and refuse to process
258 the page, issuing an adapted message. In some rare cases, the program
259 will complete without warning, but the output will be wrong. Such cases
260 are called "bugs" ;) If you encounter such case, be sure to report
261 this, along with a fix when possible...
262
264 This module can be used for most of the existing man pages.
265 Some tests are regularly run on Linux boxes:
267 · one third of the pages are refused because they were generated from
269 another format supported by po4a (e.g. pod or SGML).
270 · 10% of the remaining pages are rejected with an error (e.g. a groff
272 macro is not supported).
273 · Then, less than 1% of the pages are accepted silently by po4a, but
275 with significant issues (i.e. missing words, or new words inserted)
276 · The other pages are usually handled without differences more impor‐
278 tant than spacing differences or line rewrapped (font issues in
279 less than 10% of the processed pages).
280
282 po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm).
283
285 Denis Barbier <barbier@linuxfr.org>
286 Nicolas François <nicolas.francois@centraliens.net>
287 Martin Quinson (mquinson#debian.org)
288
290 Copyright 2002, 2003, 2004, 2005, 2006 by SPI, inc.
291 This program is free software; you may redistribute it and/or modify it
293 under the terms of GPL (see the COPYING file).
294perl v5.8.8 2008-06-01 Locale::Po4a::Man(3)