Text wrapping¶

Unindented paragraphs are automatically rewrapped for the translator. This can lead to some minor difference in the generated output, since the rewrapping rules used by groff aren't very clear. For example, two spaces after a parenthesis are sometimes preserved.

Anyway, the difference will only be about the position of the extra spaces in wrapped paragraph, and I think it's worth.

Font specification¶

The first change is about font change specifications. In nroff, there are several ways to specify if a given word should be written in small, bold or italics. In the text to translate, there is only one way, borrowed from the POD (Perl online documentation) format:

I<text> -- italic text

equivalent to \fItext\fP or ".I text"

B<text> -- bold text

equivalent to \fBtext\fP or ".B text"

R<text> -- roman text

equivalent to \fRtext\fP

CW<text> -- constant width text

equivalent to \f(CWtext\fP or ".CW text"

Remark: The CW face is not available for all groff devices. It is not recommended to use it. It is provided for your convenience.

Automatic characters transliteration¶

Po4a automatically transliterate some characters to ease the translation or the review of the translation. Here is the list of the transliterations:

hyphens

Hyphens (-) and minus signs (\-) in man pages are all transliterated as simple dashes (-) in the PO file. Then all dash are transliterated into roff minus signs (\-) when the translation is inserted into the output document.

Translators can force an hyphen by using the roff glyph '\[hy]' in their translations.

non-breaking spaces

Translators can use non-breaking spaces in their translations. These non-breaking spaces (0xA0 in latin1) will be transliterated into a roff non-breaking space ('\ ').

quotes transliterations

`` and '' are respectively tranliterated into \*(lq and \*(rq.

To avoid these transliterations, translators can insert a zero width roff character (i.e., using `\&` or '\&' respectively).

Putting '<' and '>' in translations¶

Since these chars are used to delimit parts under font modification, you can't use them verbatim. Use E<lt> and E<gt> instead (as in POD, one more time).

Don't program in nroff¶

nroff is a complete programming language, with macro definition, conditionals and so on. Since this parser isn't a fully featured nroff interpreter, it will fail on pages using these facilities (There are about 200 such pages on my box).

Use the plain macro set¶

There are still some macros which are not supported by po4a::man. This is only because I failed to find any documentation about them. Here is the list of unsupported macros used on my box. Note that this list isn't exhaustive since the program fails on the first encountered unsupported macro. If you have any information about some of these macros, I'll happily add support for them. Because of these macros, about 250 pages on my box are inaccessible to po4a::man.

 ..               ."              .AT             .b              .bank
 .BE              ..br            .Bu             .BUGS           .BY
 .ce              .dbmmanage      .do                             .En
 .EP              .EX             .Fi             .hw             .i
 .Id              .l              .LO             .mf
 .N               .na             .NF             .nh             .nl
 .Nm              .ns             .NXR            .OPTIONS        .PB
 .pp              .PR             .PRE            .PU             .REq
 .RH              .rn             .S<             .sh             .SI
 .splitfont       .Sx             .T              .TF             .The
 .TT              .UC             .ul             .Vb             .zZ

Hiding text from po4a¶

Sometimes, the author knows that some parts are not translatable, and should not be extracted by po4a. For example, an option may accept an other argument, and other may also appear as the last item of a list. In the first case, other should be not be translatable. And in the second case, other should be translated.

In such case, the author can avoid po4a to extract some strings, using some special groff constructs:

 .if !'po4a'hide' .B other

(this will require the -o groff_code=verbatim option)

A new macro can also be defined to automate this:
.de IR_untranslated
. IR \\$@
..

 .IR_untranslated \-q ", " \-\-quiet

(this will require the options -o groff_code=verbatim and -o untranslated=IR_untranslated; with this construct, the .if !'po4a'hide' conditional is not strictly needed since po4a will not parse the internal of the macro definition)

or using an alias:
.als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

This will require the -o untranslated=als,IR_untranslated option.

Conclusion¶

To summarise this section, keep simple, and don't try to be clever while authoring your man pages. A lot of things are possible in nroff, and not supported by this parser. For example, don't try to mess with \c to interrupt the text processing (like 40 pages on my box do). Or, be sure to put the macro arguments on the same line that the macro itself. I know that it's valid in nroff, but would complicate too much the parser to be handled.

Of course, another possibility is to use another format, more translator friendly (like POD using po4a::pod, or one of the XML family like SGML), but thanks to po4a::man it isn't needed anymore. That being said, if the source format of your documentation is POD, or XML, it may be clever to translate the source format and not this generated one. In most cases, po4a::man will detect generated pages and issue a warning. It will even refuse to process POD generated pages, because those pages are perfectly handled by po4a::pod, and because their nroff counterpart defines a lot of new macros I didn't want to write support for. On my box, 1432 of the 4323 pages are generated from POD and will be ignored by po4a::man.

In most cases, po4a::man will detect the problem and refuse to process the page, issuing an adapted message. In some rare cases, the program will complete without warning, but the output will be wrong. Such cases are called "bugs" ;) If you encounter such case, be sure to report this, along with a fix when possible…