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

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

   Usetheplainmacroset
       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

   Hidingtextfrompo4a
       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 -ogroff_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  -ogroff_code=verbatim and -ountranslated=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 -ountranslated=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…

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

       Copyright © 2002-2008 SPI, Inc.

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

perl v5.38.2                                       2024-08-28                           LOCALE::PO4A::MAN.3PM(1)

       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.

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

       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 controls 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 option is mandatory to use po4a on generated man
           pages.  Note that translating generated pages instead of sources ones is often more fragile, and thus
           a bad idea.

       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 or 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 specify the behavior of a  user-defined  macro  (with  a  .de  request),  or  of  a
       classical  macro  that is not supported by po4a.  They take as argument a comma-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.

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

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

       translate_joinedtranslate_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 as argument a list of comma-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) won't be translated.

       inline
           This option specifies a list of comma-separated macros that must not split the current paragraph. The
           string to translate will then contain foo<.barbazqux>quux, where bar is the command  that  should
           be inlined, and bazqux 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, or translate_each (see above for an explanation of these values).

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

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

       Some tests are regularly run on Linux boxes:

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

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

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

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

       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.

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

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

   Automaticcharacterstransliteration
       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'>'intranslations
       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).