Text envolvido¶

Parágrafos sem recuo são automaticamente re-envolvidos 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çosdepois 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, eu 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 dispositivos 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 usando 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 respectivamente, transliterados em \*(lq and \*(rq.

Para evitar essas transliterações, os tradutores podem inserir um caratere roff largura zero (ou seja, usando `\ &` or '\&' respectivamente).

Colocando '<' e '>' em traduções¶

Desde que estes carateres são utilizadas para delimitar partes sob modificação da font, você não os pode usar na íntegra. Use E<lt> e E<gt> em vez (como em POD, mais uma vez).

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 algumas macros que não são suportadas por po4a::man. É assim porque eu não encontrei qualquer documentação sobre elas. Aqui está a lista de macros sem suporte utilizadas na minha caixa. Note-se que esta lista não é exaustiva uma vez que o programa falha na primeira macro sem suporte que encontra. Se você tem alguma informação sobre algumas dessas macros, ficarei feliz em adicionar suporte para elas. Devido a estas 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 sequências, usando 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 utilizando 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 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 com \c para interromper o processamento de texto (como 40 páginas na minha caixa de 'a fazer'). Ou, seja certo a colocar os argumentos da macro na mesma linha em que a macro está. Eu sei que é válido em nroff, mas iria complicar muito o analisador para ser tratado.

É claro, outra possibilidade é a utilização de outro formato, mais tradutor amigável (como POD usando po4a::pod, ou um da família XML como SGML), mas graças a po4a::man, não é mais necessário. Dito isto, se o formato fonte da sua documentação é POD, ou XML, pode ser inteligente para traduzir o formato da fonte e não este gerado. Na maioria dos casos, po4a::man irá detectar páginas geradas e emitir um aviso. Ele irá mesmo recusar processar as páginas POD geradas, porque essas páginas são perfeitamente manipulados por po4a::pod, e porque o seu homólogo nroff define um monte de macros novas, que eu não quero escrever o suporte. Na minha caixa, 1432 de 4323 páginas são geradas a partir do POD e será ignorado por po4a::man.

Na maioria dos casos, po4a::man irá detectar o problema e recusar-se a processar a página, emitindo uma mensagem adaptada. Em alguns casos raros, o programa irá completar sem avisar, mas a saída será errada. Tais casos são chamados "bugs" ;) Se você encontrar tal caso, não se esqueça de informar isso, juntamente com uma correção quando possível ...