Ubuntu Manpage: Locale::Po4a::Man - converte páginas de manual de/para arquivos PO

NOME

       Locale::Po4a::Man - converte páginas de manual de/para arquivos PO

DESCRIÇÃO

       O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) é facilitar traduções (e o mais
       interessante, a manutenção das traduções) usando as ferramentas do gettext em áreas em que não se
       esperava, como documentação.

       Locale::Po4a::Man é um módulo para ajudar a tradução de documentação no formato nroff (o idioma das
       páginas de manual) para outros idiomas.

TRADUZINDO COM PO4A::MAN

Este módulo tenta com muito esforço tornar a vida do tradutor mais fácil. Para isso, o texto apresentado
para os tradutores não é uma cópia exata do texto encontrado na página de manual. Exatamente: as partes
mais cruas do formato nroff são ocultadas de forma que os tradutores não possam se complicar com elas.

Dimensionamento de texto
Parágrafos sem recuo são automaticamente redimensionados para o tradutor. Isso pode levar a alguma
pequena diferença no resultado gerado, já que regras de redimensionamento usadas pelo groff não são muito
claras. Por exemplo, dois espaços após um parêntese é mantido em alguns casos.

De qualquer forma, a diferença será apenas sobre a posição de espaços extras em parágrafos dimensionados,
e eu acho que isso vale a pena.

Especificação de fonte
A primeira alteração é sobre especificação de alteração de fontes. No nroff, há várias formas de
especificar se uma palavra fornecida deveria ser escrita diminuída, negrito ou itálico. No texto para
traduzir, há apenas uma forma, emprestada do formato POD (documentação on-line do Perl):

I<texto> -- texto em itálico
equivalente a \fItexto\fP ou ".I texto"

B<texto> -- texto em negrito
equivalente a \fBtexto\fP or ".B texto"

R<texto> -- texto em romano
equivalente a \fRtexto\fP

CW<texto> -- texto com largura fixa
equivalente a \f(CWtexto\fP ou ".CW texto"

Observação: A opção CW não está disponível para todos os dispositivos groff. Não é recomendável usá-lo.
Ele é fornecido para sua conveniência.

Transliteração automática de caracteres
Po4a translitera automaticamente alguns caracteres para facilitar a tradução ou a revisão da tradução.
Aqui está a lista de transliterações:

hífenes
Sinais de hífenes (-) e de menos (\-) em páginas de manual são todas transliteradas como traços
simples (-) nos arquivos PO. Então, todos os traços são transliterados em sinais roff de menos (\-)
quando a tradução é inserida no documento de saída.

Tradutores podem forçar um hífen usando o glifo "\[hy]" do roff em suas traduções.

espaço rígido
Tradutores podem usar espaços rígidos (também conhecidos como "espaços fixos") em suas traduções.
Esses espaços rígidos (0xA0 em latin1) será transliterado para um espaço rígido ("\ ").

transliterações de aspas
`` e '' são transliteradas, respectivamente, para \*(lq e \*(rq.

Para evitar essas transliterações, os tradutores podem inserir um caractere roff com zero de largura
(isto é, usando `\&` ou '\&', respectivamente).

Colocando "<" e ">" nas traduções
Já que esses caracteres são usados para delimitar partes sob modificação de fonte, você não pode usá-los
literalmente. Use E<lt> e E<gt> em vez disso (como em POD, novamente).

OPÇÕES ACEITAS POR ESTE MÓDULO

       Estas são as opções específicas deste módulo:

       debug
           Ativa depuração em alguns mecanismos internos deste módulo. Use a fonte para saber quais partes podem
           ser depuradas.

       verbose
           Aumenta o nível de detalhamento.

       groff_code
           Esta opção permite alterar o comportamento do módulo quando ele encontrar uma seção .de, .ie ou .if .
           Ele pode levar os valores a seguir:

           fail
               Esse é o valor de padrão. O módulo vai falhar quando uma seção .de, .ie ou .if for encontrada.

           verbatim
               Indica que as seções .de, .ie ou .if devem ser copiadas como estão do original para  o  documento
               traduzido.

           translate
               Indica  que as seções .de, .ie ou .if vão ser propostas para a tradução. Você deveria apenas usar
               esta opção se uma string de tradução contiver uma dessas seções. Do contrário, verbatim deve  ser
               preferido.

       generated
           Esta  opção especifica que o arquivo foi gerado e que po4a não deve tentar detectar se as páginas man
           foi geral de outro formato. Isso permite usar po4a em  páginas  man  geradas.  Esta  opção  não  leva
           argumento algum.

       mdoc
           Esta opção é apenas útil para páginas mdoc.

           Ela  seleciona um suporte mais estrito ao formato mdoc ao informar po4a que não deve traduzir a seção
           "NAME". Páginas mdoc cuja seção "NAME" está traduzida não vão  gerar  cabeçalho  ou  nota  de  rodapé
           algum.

           De acordo com as páginas do groff_mdoc, as seções NAME, SYNOPSIS e DESCRIPTION são obrigatórias.  Não
           há  problemas  conhecidos  com  seções  SYNOPSIS  ou  DESCRIPTION  traduzidas,  mas  você também pode
           especificar essas seções desta forma:
            -o mdoc=NAME,SYNOPSIS,DESCRIPTION

           Esse problema pode ser resolvido com um adendo como este aqui:
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "dia mês, ano" OS "Nome da seção"

       As opções a seguir permitem especificar o comportamento de uma nova macro (definida  com  uma  requisição
       .de)  ou  de uma macro sem suporte pelo po4a. Elas levam como argumento uma lista separada por vírgula de
       macros. Por exemplo:

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

       Nota: se uma macro não tem suporte no po4a e se você considera que é uma macro roff padrão, você  deveria
       enviá-la para a equipe de desenvolvimento do po4a.

       untranslated
           untranslated indica que esta macro (em seus argumentos) não deveria ser traduzida.

       noarg
           noarg  é  como  untranslated,  exceto  que po4a vai verificar que nenhum argumento é adicionar a esta
           macro.

       translate_joined
           translate_joined indica que po4a deve propor a tradução de argumentos da macro.

       translate_each
           Com translate_each, os argumentos também serão propostos para a tradução, exceto  que  cada  um  será
           traduzido separadamente.

       no_wrap
           Esta  opção  leva  como argumento uma lista de pares de begin:end separados por vírgula, onde begin e
           end são comandos que delimitam o início e fim de uma seção que não deveria ser redimensionada.

           Nota: nenhum teste é feito para assegurar que um  comando  end  corresponde  ao  seu  comando  begin;
           qualquer  comando de finalização termina o modo no_wrap. Se você tem uma macro begin (respectivamente
           end) que não possui end (respectivamente begin), você pode especificar uma end existente (como fi) ou
           begin (como nf) como uma contraparte. Essas macros (e seus argumentos) não serão traduzidos.

       inline
           Esta opção especifica uma lista de macros separadas por vírgula que não  podem  dividir  o  parágrafo
           atual.  A  string a ser traduzida vai, então, conter foo <.bar baz qux> quux, sendo bar o comando que
           deveria ser embutido, e baz qux seus argumentos.

       unknown_macros
           Esta opção indica como po4a deveria se comportar quando uma  macro  desconhecida  é  encontrada.  Por
           padrão,  po4a  falha  com  um  aviso.  Ele  pode  levar os valores a seguir: failed (o valor padrão),
           untranslated, noarg, translate_joined ou translate_each (veja  acima  uma  explicação  para  cada  um
           desses valores).

CRIAÇÃO DE PÁGINAS MAN COMPATÍVEIS COM PO4A::MAN

Este módulo ainda é bem limitado, e sempre será, pois ele não é um interpretador nroff de verdade. Seria
possível criar um interpretador nroff para permitir que autores usem todas as macros existentes ou até
mesmo definir novas em suas páginas, mas nós não queríamos. Seria muito difícil e nós entendemos não
haver necessidade. Nós pensamos que se os autores de páginas man desejam ver seus produtos traduzidos,
eles podem ter que adaptar para facilitar o trabalho dos tradutores.

Então, o analisador de manuais implementado no po4a possui algumas limitações conhecidas que nós não
exatamente estamos podendo corrigir e que podem ser buracos a serem evitados se você não quiser ver
tradutores tomando conta da sua documentação.

Não programe em nroff
nroff é uma linguagem de programação completa, com definição de macros, condicionais e por aí vai. Já que
este analisador não é um interpretador nroff com todas suas funcionalidades, ela vai falhar em páginas
usando essas capacidades (Há cerca de 200 de tais páginas no meu computador).

Uso o conjunto de macros simples
Há ainda algumas macros que não encontram suporte no po4a::man. Isso porque eu não consegui encontrar
qualquer documentação sobre elas. Aqui está a lista de macros sem suporte, usadas na minha máquina. Note
que essa lista não é exaustiva, já que o programa falha na primeira macro sem suporte encontrada. Se você
não possui qualquer informação sobre algumas dessas macros, ficarei feliz em adicionar suporte a elas.
Por causa dessas macros, cerca de 250 páginas estão inacessíveis para 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

Ocultando texto dopo4a
Algumas vezes, o autor sabe que algumas partes não são traduzíveis e, portanto, não deveriam ser
extraídas pelo po4a. Por exemplo, uma opção pode aceitar um argumento other e other também pode aparecer
como o último item de uma lista. No primeiro caso, other não deveria ser traduzível. e no segundo caso,
other deveria ser traduzido.

Neste aso, o autor pode evitar que po4a extraia algumas strings usando alguns constructs especiais do
groff:

.if !'po4a'hide' .B other

(isto vai exibir a opção -o groff_code=verbatim)

Uma nova macro também pode ser definida para automatizar isso:
.de IR_untranslated
. IR \\$@
..

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

(Isto vai exigir as opções -o groff_code=verbatim e -o untranslated=IR_untranslated; com este construct,
a condicional .if !'po4a'hide' não é estritamente necessária já que po4a não vai analisar o interno da
definição de macro)

ou usando o alias:
.als IR_untranslated IR

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

Isto vai exigir a opção -o untranslated=als,IR_untranslated.

Conclusão
Para resumir esta seção, mantenha simples e não tente ser esperto ao criar suas páginas man. Muitas
coisas são possível no nroff, mas que não têm suporte neste analisador. Por exemplo, não tente bagunçar o
\c interrompendo o processamento de texto (como 40 páginas na minha máquina fazem). Ou, certifique-se de
que colocar os argumentos de macros na mesma linha da própria macro. Eu se que é válido no nroff, mas
complicado demais para o analisador lidar.

É claro, outra possibilidade é usar outro formato, mais amigável ao tradutor (como POD usando po4a::pod
ou um da família XML como o SGML), mas graças ao po4a::man isso não é mais necessário. Tendo dito isso,
se o formato fonte da documentação é POD, ou XML, pode ser inteligente traduzir o formato fonte e não
este gerado. Na maioria dos casos, po4a::man vai detectar páginas geradas e mostrar um aviso. El vai até
mesmo recusar processar páginas geradas no POD porque tais páginas são lidadas perfeitamente pelo
po4a::pod, e porque sua contraparte nroff define um monte de novas macros que eu não desejo dar suporte.
Na minha máquina, 1432 das 4323 página são geradas de POD e vão ser ignoradas pelo po4a::man.

Na maioria dos casos, po4a::man vai detectar o problema e se recusar a processar a página, apresentando
uma mensagem adaptada. Em alguns casos raros, o programa vai completar sem avisos, mas a saída estará
errada. Tais casos são chamados de "bugs" ;) Se você encontrar tal caso, certifique-se de relatá-lo,
junto com uma solução, quando possível…

ESTADO DESTE MÓDULO

       Este módulo pode ser usado para a maioria das páginas man existentes.

       Alguns testes são executados frequentemente em máquinas Linux:

       •   um terço das páginas são recusadas porque foram geradas a partir de outro formato com suporte no po4a
           (ex: POD ou SGML).

       •   10% das páginas remanescentes são rejeitadas com um erro (ex: uma macro groff não tem suporte).

       •   Então, menos de 1% das páginas são aceitas silenciosamente pelo po4a, mas com problemas significantes
           (isto é, palavras faltando ou novas palavras inseridas)

       •   As  outras  páginas  são  normalmente  lidadas  sem  diferenças mais importantes do que diferenças de
           espaçamento ou linha redimensionada (problemas de fontes em menos de 10% das páginas processadas).

VEJA TAMBÉM

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

AUTORES

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

COPYRIGHT E LICENÇA

       Copyright © 2002-2008 SPI, Inc.

       Esse programa é um software livre; você pode redistribuí-lo e/ou modificá-lo sob os termos da GPL (veja o
       arquivo COPYING).

Ferramentas do Po4a                                2022-01-02                             Locale::Po4a::Man(3pm)