Locale::Po4a::Man

Section: Po4a Tools (3pm)
Updated: 2024-01-29
Index Return to Main Contents

NOM

Locale::Po4a::Man - Converteix pàgines de manual des de/a fitxers PO

DESCRIPCIÓ

L'objectiu del projecte po4a (PO per a tot) és facilitar la traducció (i sobretot el manteniment de les traduccions) utilitzant les eines de gettext en àrees on no eren d'esperar, com ara en la documentació.

Locale::Po4a::Man és un mòdul per ajudar en la traducció de documentació en el format nroff (el llenguatge de les pàgines de manual) a altres llenguatges [humans].

TRADUINT AMB PO4A::MAN

Aquest mòdul s'esmera per facilitar la vida dels traductors. Per aconseguir-ho, el text presentat als traductors no és una còpia exacta del text que hi ha a les pàgines de manual. De fet, s'oculten les parts més crues del format nroff, de forma que els traductors no s'hi puguin embolicar.

Justificat de text

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.

De totes maneres, la diferència tan sols serà en la posició dels espais extra del paràgraf justificat, i crec que val la pena.

Especificació de fonts

El primer canvi és sobre l'especificació de canvis de font. A nroff hi ha diverses maneres d'especificar si una paraula s'ha d'escriure amb lletra petita, en negreta o en cursiva. En el text a traduir només hi ha una forma, copiada del format POD (la documentació en línia de Perl):

I<text> --- text en cursiva: equival a \fItext\fP o ``.I text''
B<text> --- text en negreta: equival a \fBtext\fP o ``.B text''
R<text> --- text normal: equival a \fRtext\fP
CW<text> --- text d'ample constant: equival a \f(CWtext\fP o ``.CW text''

Nota: La font CW no està disponible per a tots els dispositius de groff. Es recomana no utilitzar-la. Es proporciona només per a la seva comoditat.

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

Posant '<' i '>' a les traduccions

Com que aquests caràcters s'utilitzen per delimitar parts de modificació de fonts, no podeu utilitzar-los directament. Utilitzeu E<lt> i E<gt> en el seu lloc (una vegada més, igual que en POD).

OPCIONS QUE ACCEPTA AQUEST MÒDUL

Aquestes són les opcions particulars d'aquest mòdul:

debug

Activa la depuració d'alguns mecanismes interns d'aquest mòdul. Mireu el codi per veure quines parts es poden depurar.

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.

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 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 <.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, or translate_each (see above for an explanation of these values).

ESCRIVINT PÀGINES DE MANUAL COMPATIBLES AMB PO4A::MAN

Aquest mòdul encara és molt limitat, i sempre ho serà, ja que no és un intèrpret real de nroff. Seria possible fer un intèrpret real de nroff, i permetre que els autors utilitzin totes les macros existents, o fins i tot que en defineixin de noves a les seves pàgines, però no és el què volem. Això seria massa difícil, i vam pensar que no era necessari. Creiem que si els autors de pàgines de manual volen veure les seves produccions traduïdes, han d'adaptar-se per facilitar la feina dels traductors.

Per tant, l'analitzador de man implementat a po4a té algunes limitacions conegudes que no estem predisposats a arreglar, i que constitueixen alguns esvorancs que haureu d'evitar si voleu que els traductors es preocupin de la vostra documentació.

No programeu en nroff

nroff és un llenguatge de programació complet, amb definicions de macros, condicionals i molt més. Com que aquest analitzador no és un intèrpret complet de nroff, fallarà en pàgines que utilitzin aquestes característiques (hi ha unes 200 pàgines d'aquestes a la meva màquina).

Utilitzeu el joc de macros estàndards

Encara hi ha algunes macros no suportades per po4a::man. Això és perquè no he aconseguit trobar-ne documentació. Aquí hi ha una llista de macros no suportades que hi ha a la meva màquina. Tingueu en compte que això no és una llista exhaustiva, ja que el programa falla en la primera macro no suportada. Si teniu informació sobre algunes d'aquestes macros, intentaré afegir-ne suport. Degut a aquestes macros, hi ha unes 250 pàgines de la meva màquina que són inaccessibles per a 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.

Conclusió

Per concloure aquesta secció, no us compliqueu, i no intenteu demostrar la vostra inteligència a l'hora d'escriure les vostres pàgines de manual. Es poden fer moltes coses amb nroff, i no estan suportades per aquest analitzador. Per exemple, no us compliqueu amb \c per interrompre el processat de text (com fan 40 pàgines de la meva màquina). O assegureu-vos de posar els paràmetres de les macros a la mateixa línia que la macro. Ja sé que és vàlid a nroff, però si ho volguéssim tractar, es complicaria molt l'analitzador.

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…

ESTAT D'AQUEST MÒDUL

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

CONSULTEU TAMBÉ

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

AUTORS

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

TRADUCCIÓ

 Carme Cirera <menxu@hotmail.com>
 Jordi Vilalta <jvprat@gmail.com>

DRET DE CÒPIA I LLICÈNCIA

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

Index

NOM

DESCRIPCIÓ

TRADUINT AMB PO4A::MAN

Justificat de text
Especificació de fonts
Automatic characters transliteration
Posant '<' i '>' a les traduccions

OPCIONS QUE ACCEPTA AQUEST MÒDUL

ESCRIVINT PÀGINES DE MANUAL COMPATIBLES AMB PO4A::MAN

No programeu en nroff
Utilitzeu el joc de macros estàndards
Hiding text from po4a
Conclusió

ESTAT D'AQUEST MÒDUL

CONSULTEU TAMBÉ

AUTORS

TRADUCCIÓ

DRET DE CÒPIA I LLICÈNCIA

This document was created by using the manual pages.
Time: 00:28:40 GMT, January 29, 2024

po4av0.70