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.

Of course, another possibility is to use another format, more translator friendly (like POD using po4a::pod, or one of the XML family like SGML), but thanks to po4a::man it isn't needed anymore. That being said, if the source format of your documentation is POD, or XML, it may be clever to translate the source format and not this generated one. In most cases, po4a::man will detect generated pages and issue a warning. It will even refuse to process POD generated pages, because those pages are perfectly handled by po4a::pod, and because their nroff counterpart defines a lot of new macros I didn't want to write support for. On my box, 1432 of the 4323 pages are generated from POD and will be ignored by po4a::man.

In most cases, po4a::man will detect the problem and refuse to process the page, issuing an adapted message. In some rare cases, the program will complete without warning, but the output will be wrong. Such cases are called "bugs" ;) If you encounter such case, be sure to report this, along with a fix when possible…