NOME

       Locale::Po4a::Man - converte páginas do manual de/para ficheiros files

DESCRIÇÃO

       O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a
       manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados
       como 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 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).

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 padrão. 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. Você só
               deve usar essa opção se uma sequência 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 detectar
           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 dizendo 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 você considerar que é uma macro roff
       padrão, deve enviá-la para a 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 você tem uma macro begin
           (respectivamente End) que não tem End (respectivamente begin),pode especificar um
           existente End (como fi) ou begin (como nf) como uma contrapartida. Estas macros (e
           seus 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 sequência a traduzir conterá então foo <.bar baz qux> quux onde
           bar é o comando que deve ser 'inlined', e baz qux seus argumentos.

       unknown_macros
           Esta opção indica como po4a deve se comportar quando uma macro desconhecida é
           encontrada. Por padrão, po4a falha com um aviso. Ele pode tomar os seguintesvalores:
           failed (o valor padrão), 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 nós 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 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 ...

STATUS 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 um 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 re-envolvidas (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 François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

DIREITOS DE AUTOR E LICENÇA

       Direitos de autor 2002-2008 por SPI, inc.

       Este programa é software livre, você pode redistribuí-lo e/ou modificá-lo sob os termos da
       GPL (consulte o ficheiro CÓPIA).