Provided by: po4a_0.66-1_all 
NOME
Locale::Po4a::Man - converte páginas do manual de/para ficheiros files
DESCRIÇÃO
O objetivo do projeto po4a (PO for anything: PO para qualquer coisa) é facilitar traduções (e o mais
interessante, a manutenção das traduções) a usar as ferramentas do gettext em áreas em que não se
esperava, como na documentação.
Locale::Po4a::Man é um módulo para ajudar na tradução de documentação em formato nroff (a linguagem das
páginas do manual) em outras línguas [humana].
TRADUZINDO COM PO4A::MAN
Este módulo tenta com bastante força tornar a vida do tradutor mais fácil. Para isso, o texto apresentado
aos tradutores não é uma cópia literal do texto encontrado na página do manual. De fato, as partes mais
cruas do formato nroff estão escondidos, por isso os tradutores não se podem atrapalhar com elas.
Text envolvido
Parágrafos sem recuo são automaticamente reevolvidos para o tradutor. Isto pode levar a uma diferença
menor na saída gerada, uma vez que as regras de reenvolvimento usadas por groff não são muito claras. Por
exemplo, dois espaços depois de um parêntese às vezes são preservados.
De qualquer forma, a diferença será apenas sobre a posição dos espaços extrano parágrafo envolto e acho
que vale a pena.
Especificação da Font
A primeira mudança é sobre as especificações de mudança de font. Em nroff, existem várias maneiras para
especificar se uma determinada palavra deve ser escrita em pequeno, negrito ou itálico. No texto para
traduzir, só há um caminho, emprestado do formato POD (Perl documentação on-line):
I<text> -- texto em itálico
equivalente a \fItext\fP or ".I text"
B<text> -- texto em negrito
equivalente a \fBtext\fP or ".B text"
R<text> -- texto romano
equivalente a \fRtext\fP
CW<text> -- texto de largura constante
equivalente a \f(CWtext\fP or ".CW text"
Observação: O rosto CW não está disponível para todos os aparelhos groff. Não é recomendado usá-lo. Ele é
fornecido para sua conveniência.
Transliteração automática de carateres
Po4a automaticamente translitera alguns carateres para facilitar a tradução ou revisão da tradução. Aqui
está a lista das transliterações:
hífenes
Hífens (-) e sinais de menos (\-) em páginas de manual são todos transliterados como traços simples
(-) no ficheiro PO. Assim todos os traços são transliterados em sinais roff menos (\-) quando a
tradução é inserida no documento de saída.
Os tradutores podem forçar um hífen a usar o roff glyph '\[hy]' nas suas traduções.
espaços não-separáveis
Os tradutores podem usar espaços não separáveis nas suas traduções. Estes espaços não separáveis
(0xA0 em latin1) serão transliterados num roff non-breaking space ('\ ').
transliterações citadas
`` e '' são respetivamente, transliterados em \*(lq and \*(rq.
Para evitar essas transliterações, os tradutores podem inserir um caratere roff largura zero (ou
seja, a usar `\ &` or '\&' respectivamente).
Colocando '<' e '>' em traduções
Desde que estes carácteres são utilizadas para delimitar partes sob modificação da font, não os pode usar
na íntegra. Use E<lt> e E<gt> em vez (como em POD, mais uma vez).
OPÇÕES ACEITES POR ESTE MÓDULO
Estas são as opções particulares deste módulo:
debug
Ativar a depuração para alguns mecanismos internos deste módulo. Use a fonte para ver que partes
podem ser depuradas.
verbose
Aumentar o detalhe.
groff_code
Esta opção permite alterar o comportamento do módulo quando encontrar uma .de, .ie ou .if, o módulo
pode tomar os seguintes valores:
fail
Este é o valor predefinido. O módulo irá falhar quando uma secção .de, .ie ou .if é encontrada.
verbatim
Indica que as secções .de, .ie ou .if, devem ser copiadas como estão no original para o documento
traduzido.
translate
Indica que as secções .de, .ie ou .if serão propostas para a tradução. Só deve usar essa opção se
uma cadeia traduzível está contida numa destas secções. Caso contrário, verbatim deve ser
preferida.
generated
Esta opção especifica que o ficheiro foi gerado e que po4a não deve tentar detetar se as página do
manual foi gerada a partir de um outro formato. Isto permite usar po4a em páginas do manual geradas.
Esta opção não tem qualquerargumento.
mdoc
Esta opção só é útil para páginas mdoc.
Seleciona um rigoroso suporte do formato mdoc a dizer a po4a para não traduzir a secção 'NOME'.
Páginas mdoc cuja secção 'NOME' é traduzida não irá gerar qualquer cabeçalho ou rodapé.
De acordo com a página groff_mdoc, as secções NOME, SINOPSE e DESCRIÇÃO são obrigatórias. Não
existem problemas conhecidos com a secção SINOPSE traduzida ou a secção DESCRIÇÃO, mas também pode
especificar estas secções da seguinte forma:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION
Esta questão mdoc também pode ser resolvida com uma adenda como esta:
Po4a-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 " Month day, year"OS " Section Name"
As seguintes opções permitem especificar o comportamento de uma nova macro (definida com um pedido .de),
ou duma macro não suportada por po4a. Tomam como argumento uma lista de macros separadas por vírgula. Por
exemplo:
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Nota: se uma macro não é suportada pelo po4a e se considerar que é uma macro roff predefinido, deve
enviá-la ao equipa de desenvolvimento po4a.
untranslated
untranslated indica que esta macro (nos seus argumentos) não tem que ser traduzida.
noarg
noarg é como untranslated, exceto que po4a irá verificar que nenhum argumento é adicionado a esta
macro.
translate_joined
translate_joined indica que po4a deve propor a tradução dos 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 em separado.
no_wrap
Essa opção usa como argumento uma lista de pares separados por vírgula begin:End, onde begin e End
são comandos que delimitam o começar e terminar de uma secção que não deve ser re-envolvida.
Nota: nenhum teste é feito para garantir que um comando End corresponde ao seu comando begin;
qualquer comando termina no modo no_wrap. Se tem um macro begin (respetivamente End) que não tem End
(respetivamente begin), pode especificar um existente End (como fi) ou begin (como nf) como uma
contrapartida. Estes macros (e os argumentos) não vão ser traduzidas.
inline
Esta opção especifica uma lista de macros separadas por vírgula que não devem dividir o parágrafo
atual. A cadeia a traduzir conterá então foo <.bar baz qux> quux onde bar é o comando que deve ser
'inlined', e baz qux os argumentos dele.
unknown_macros
Esta opção indica como po4a deve se comportar quando uma macro desconhecida é encontrada. Por
predefinição, po4a falha com um aviso. Ele pode tomar os seguintesvalores: failed (o valor
predefinido), untranslated, noarg, translate_joined, ou translate_each (ver acima para uma explicação
destes valores).
AUTORIA DAS PÁGINAS DE MANUAL COMPATÍVEL COM PO4A::MAN
Este módulo é ainda muito limitado e, sempre vai ser, porque não é um intérprete nroff real. Seria
possível fazer um intérprete nroff real, permitir que os autores usarem todas as macros existentes, ou
até mesmo para definir novas nas suas páginas, mas não quiséssemos. Seria muito difícil e pensamos que
não era necessário. Pensamos que se os autores das páginas de manual quiserem ver as suas produções
traduzidas, devem ter de se adaptar a facilitar o trabalho dos tradutores.
Portanto, o analisador de manual implementado em po4a tem algumas limitações conhecidas que são e não
estamos realmente inclinados a corrigir e que constituirá algumas armadilhas que tem de evitar se quiser
ver tradutores cuidarem da sua documentação.
Não programe em nroff
nroff é uma linguagem de programação completa, com a definição de macro, condicionais e assim por diante.
Uma vez que este analisador está totalmente caracterizado como intérprete nroff, irá falhar em páginas
que utilizam estas instalações (há cerca de 200 tais páginas na minha caixa).
Use o conjunto de macro simples
Existem ainda alguns macros que não são suportadas por po4a::man. É assim porque eu não encontrei nenhuma
documentação sobre elas. Aqui está a lista de macros sem suporte, utilizadas na minha caixa. Note que
esta lista não é exaustiva uma vez que o programa falha no primeiro macro, que encontra sem suporte. Se
tem alguma informação sobre algumas desses macros, ficarei feliz em adicionar suporte para elas. Devido a
estes macros, cerca de 250 páginas na minha caixa sã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
Escondendo texto de po4a
Às vezes, o autor sabe que algumas partes não são traduzíveis e não devem ser extraídas por po4a. Por
exemplo, uma opção pode aceitar um argumento other e other também pode aparecer como o último item duma
lista. No primeiro caso, other não deve ser traduzido. E, no segundo caso, other deve ser traduzido.
Em tal caso, o autor pode evitar po4a para extrair algumas cadeias, a usar algumas construções especiais
groff:
.if !'po4a'hide' .B other
(isto vai exigir o -o groff_code = verbatimoption)
A nova macro também pode ser definida para automatizar isto:
.de IR_untranslated
. IR \\$@
..
.IR_untranslated \-q ", " \-\-quiet
(isto vai exigir as opções -o groff_code =verbatim e -o untranslated=IR_untranslated; com esta
construção, o .if !'po4a'hide' condicional não é estritamente necessário uma vez que po4a não irá
analisar o interno da definição da macro)
ou a utilizar um alias:
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
Isso vai exigir o -o untranslated=als,IR_untranslated option.
Conclusão
Para resumir esta secção, manter simples e não tente ser inteligente a quanto da autoria das suas páginas
de manual. Muitas coisas são possíveis em nroff e não suportadas por este analisador. Por exemplo, não
tente mexer em \c para interromper o processamento de texto (como 40 páginas na minha caixa de 'a
fazer'). Ou seja, certo a pôr os argumentos do macro na mesma linha em que o macro está. Sei que é válido
em nroff, mas iria complicar muito o analisador para ser tratado.
É claro, outra possibilidade é usar outro formato, mais amigável ao tradutor (como POD a usar 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 detetar 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.
Geralmente, po4a::man vai detetar o problema e se recusar a processar a página, a apresentar 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 encontrar tal caso, certifique-se de relatá-lo, com uma solução,
quando possível…
ESTADO DESTE MÓDULO
Este módulo pode ser usado para a maioria das páginas de manual existentes.
Alguns testes são regularmente executado em máquinas Linux:
• um terço das páginas são recusadas porque foram geradas a partir de outro formato suportado pelo po4a
(por exemplo, POD ou SGML).
• 10% das páginas remanescentes são rejeitadas com um erro (por exemplo, uma macro groff não é
suportada).
• Em seguida, menos de 1% das páginas são aceites por po4a silenciosamente, mas com questões
significativas (ou seja, palavras que faltam, ou palavras novas inseridas)
• As outras páginas são geralmente tratadas sem diferenças mais importantes do que as diferenças de
espaçamento ou linhas reevolvidas (problemas com fontes são menos de 10% das páginas processadas).
VER 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)
DIREITOS DE AUTOR E LICENÇA
Copyright © 2002-2008 SPI, Inc.
Este programa é software livre, pode redistribuí-lo e/ou modificá-lo sob os termos da GPL (consulte o
ficheiro CÓPIA).
Ferramentas Po4a 2022-01-02 Locale::Po4a::Man(3pm)