Provided by: po4a_0.47-2_all 
NOME
Locale::Po4a::Man - converte páginas de manual de/para arquivos PO
DESCRIÇÃO
A missão do projeto po4a (em inglês, PO for anything) é facilitar as traduções (e o mais
interessante, a manutenção de traduções) usando ferramentas de gettext em áreas onde elas
não eram esperadas, 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 de manual foi geral de outro formato. Isso permite usar po4a em páginas de
manual 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 DE MANUAL 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 de manual 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 de
manual. 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 de manual 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 François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
COPYRIGHT E LICENÇA
Copyright 2002-2008 por SPI, inc.
Esse programa é um software livre; você pode redistribuí-lo e/ou modificá-lo sob os termos
da GPL (veja o arquivo COPYING).