Man Linux: Main Page and Category List

NAME

       Locale::Po4a::Man - Convert manual pages from/to PO files

DESCRIPTION

       The po4a (po for anything) project goal is to ease translations (and
       more interestingly, the maintenance of translations) using gettext
       tools on areas where they were not expected like documentation.

       Locale::Po4a::Man is a module to help the translation of documentation
       in the nroff format (the language of manual pages) into other [human]
       languages.

TRANSLATING WITH PO4A::MAN

       This module tries pretty hard to make translator's life easier. For
       that, the text presented to translators isn't a verbatim copy of the
       text found in the man page. Indeed, the cruder parts of the nroff
       format are hidden, so that translators can't mess up with them.

   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, while typographic
       rules only ask to preserve the two spaces after the period sign (ok,
       I'm not native speaker, and I'm not sure of that. If you have any other
       information, you're welcome).

       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).

OPTIONS ACCEPTED BY THIS MODULE

       These are this module's particular options:

       debug
           Activate debugging for some internal mechanisms of this module.
           Use the source to see which parts can be debugged.

       verbose
           Increase verbosity.

       groff_code
           This option permits to change the behavior of the module when it
           encounter a .de, .ie or .if section. It can take the following
           values:

           fail
               This is the default value.  The module will fail when a .de,
               .ie or .if section is encountered.

           verbatim
               Indicates that the .de, .ie or .if sections must be copied as
               is from the original to the translated document.

           translate
               Indicates that the .de, .ie or .if sections will be proposed
               for the translation.  You should only use this option if a
               translatable string is contained in one of these section.
               Otherwise, verbatim should be preferred.

       generated
           This option specifies that the file was generated, and that po4a
           should not try to detect if the man pages was generated from
           another format.  This permits to use po4a on generated man pages.
           This option does not take any argument.

       mdoc
           This option is only useful for mdoc pages.

           It selects a stricter support of the mdoc format by telling po4a
           not to translate the 'NAME' section.  mdoc pages whose 'NAME'
           section is translated won't generate any header of footer.

           According to the groff_mdoc page, the NAME, SYNOPSIS and
           DESCRIPTION sections are mandatory.  There are no known issues with
           translated SYNOPSIS or DESCRIPTION section, but you can also
           specify these sections this way:
            -o mdoc=NAME,SYNOPSIS,DESCRIPTION

           This mdoc issue can also be solved with an addendum like this one:
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

       The following options permit to specify the behavior of a new macro
       (defined with a .de request), or of a macro not supported by po4a.
       They take in argument a coma separated list of macros.  For example:

        -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

       Note: if a macro is not supported by po4a and if you consider that it
       is a standard roff macro, you should submit it to the po4a development
       team.

       untranslated
           untranslated indicates that this macro (at its arguments) don't
           have to be translated.

       noarg
           noarg is like untranslated, except that po4a will verify that no
           argument is added to this macro.

       translate_joined
           translate_joined indicates that po4a must propose to translate the
           arguments of the macro.

       translate_each
           With translate_each, the arguments will also be proposed for the
           translation, except that each one will be translated separately.

       no_wrap
           This option takes in argument a list of coma-separated couples
           begin:end, where begin and end are commands that delimit the begin
           and end of a section that should not be rewrapped.

           Note: no test is done to ensure that an end command matches its
           begin command; any ending command stop the no_wrap mode.  If you
           have a begin (respectively end) macro that has no end (respectively
           begin), you can specify an existing end (like fi) or begin (like
           nf) as a counterpart.  These macros (and their arguments) wont be
           translated.

       inline
           This option specifies a list of coma-separated macros that must not
           split the current paragraph. The string to translate will then
           contain foo <.bar baz qux> quux, where bar is the command that
           should be inlined, and baz qux its arguments.

       unknown_macros
           This option indicates how po4a should behave when an unknown macro
           is found.  By default, po4a fails with a warning.  It can take the
           following values: failed (the default value), untranslated, noarg,
           translate_joined, translate_each.

AUTHORING MAN PAGES COMPLIANT WITH PO4A::MAN

       This module is still very limited, and will always be, because it's not
       a real nroff interpreter. It would be possible to do a real nroff
       interpreter, to allow authors to use all the existing macros, or even
       to define new ones in their pages, but we didn't want to. It would be
       too difficult, and we thought it wasn't necessary. We do think that if
       manpages' authors want to see their productions translated, they may
       have to adapt to ease the work of translators.

       So, the man parser implemented in po4a have some known limitations we
       are not really inclined to correct, and which will constitute some
       pitfalls you'll have to avoid if you want to see translators taking
       care of your documentation.

   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 to 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
       familly 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...

STATUS OF THIS MODULE

       This module can be used for most of the existing man pages.

       Some tests are regularly run on Linux boxes:

       o   one third of the pages are refused because they were generated from
           another format supported by po4a (e.g. pod or SGML).

       o   10% of the remaining pages are rejected with an error (e.g. a groff
           macro is not supported).

       o   Then, less than 1% of the pages are accepted silently by po4a, but
           with significant issues (i.e. missing words, or new words inserted)

       o   The other pages are usually handled without differences more
           important than spacing differences or line rewrapped (font issues
           in less than 10% of the processed pages).

SEE ALSO

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

AUTHORS

        Denis Barbier <barbier@linuxfr.org>
        Nicolas Francois <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

COPYRIGHT AND LICENSE

       Copyright 2002-2008 by SPI, inc.

       This program is free software; you may redistribute it and/or modify it
       under the terms of GPL (see the COPYING file).