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

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…