LOCALE::PO4A::MAN.3PM(1) User Contributed Perl Documentation NOME Locale::Po4a::Man - converte paginas de manual de/para arquivos PO DESCRICAO O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) e facilitar traducoes (e o mais interessante, a manutencao das traducoes) usando as ferramentas do gettext em areas em que nao se esperava, como documentacao. Locale::Po4a::Man e um modulo para ajudar a traducao de documentacao no formato nroff (o idioma das paginas de manual) para outros idiomas. TRADUZINDO COM PO4A::MAN Este modulo tenta com muito esforco tornar a vida do tradutor mais facil. Para isso, o texto apresentado para os tradutores nao e uma copia literal do texto encontrado na pagina man. De fato, as partes mais cruas do formato nroff sao ocultadas de forma que os tradutores nao possam se complicar com elas. Dimensionamento de texto Paragrafos sem recuo sao automaticamente redimensionados para o tradutor. Isso pode levar a alguma pequena diferenca no resultado gerado, ja que regras de redimensionamento usadas pelo groff nao sao muito claras. Por exemplo, dois espacos apos um parentese e mantido em alguns casos. De qualquer forma, a diferenca sera apenas sobre a posicao de espacos extras em paragrafos dimensionados, e eu acho que isso vale a pena. Especificacao de fonte A primeira alteracao e sobre especificacao de alteracao de fontes. No nroff, ha varias formas de especificar se uma palavra fornecida deveria ser escrita diminuida, negrito ou italico. No texto para traduzir, ha apenas uma forma, emprestada do formato POD (documentacao on-line do Perl): I -- texto em italico equivalente a \fItexto\fP ou ".I texto" B -- texto em negrito equivalente a \fBtexto\fP or ".B texto" R -- texto em romano equivalente a \fRtexto\fP CW -- texto com largura fixa equivalente a \f(CWtexto\fP ou ".CW texto" Observacao: A opcao CW nao esta disponivel para todos os dispositivos groff. Nao e recomendavel usa-lo. Ele e fornecido para sua conveniencia. Transliteracao automatica de caracteres Po4a translitera automaticamente alguns caracteres para facilitar a traducao ou a revisao da traducao. Aqui esta a lista de transliteracoes: hifenes Sinais de hifenes (-) e de menos (\-) em paginas de manual sao todas transliteradas como tracos simples (-) nos arquivos PO. Entao, todos os tracos sao transliterados em sinais roff de menos (\-) quando a traducao e inserida no documento de saida. Tradutores podem forcar um hifen usando o glifo "\[hy]" do roff em suas traducoes. espaco rigido Tradutores podem usar espacos rigidos (tambem conhecidos como "espacos fixos") em suas traducoes. Esses espacos rigidos (0xA0 em latin1) sera transliterado para um espaco rigido ("\ "). transliteracoes de aspas `` e '' sao transliteradas, respectivamente, para \*(lq e \*(rq. Para evitar essas transliteracoes, os tradutores podem inserir um caractere roff com zero de largura (isto e, usando `\&` ou '\&', respectivamente). Colocando "<" e ">" nas traducoes Ja que esses caracteres sao usados para delimitar partes sob modificacao de fonte, voce nao pode usa-los de forma literal. Use E e E em vez disso (como em POD, novamente). OPCOES ACEITAS POR ESTE MODULO Estas sao as opcoes especificas deste modulo: debug Ativa depuracao em alguns mecanismos internos deste modulo. Use a fonte para saber quais partes podem ser depuradas. verbose Aumenta o nivel de detalhamento. groff_code Esta opcao controla o comportamento do modulo quando ele encontrar uma secao .de, .ie ou .if . Ele pode levar os valores a seguir: fail Esse e o valor de padrao. O modulo vai falhar quando uma secao .de, .ie ou .if for encontrada. verbatim Indica que as secoes .de, .ie ou .if devem ser copiadas como estao do original para o documento traduzido. translate Indica que as secoes .de, .ie ou .if vao ser propostas para a traducao. Voce deveria apenas usar esta opcao se uma string de traducao contiver uma dessas secoes. Do contrario, verbatim deve ser preferido. generated Esta opcao especifica que o arquivo foi gerado e que po4a nao deve tentar detectar se as paginas man foi geral de outro formato. Wata opcao e obrigatoria para usar po4a em paginas man geradas. Note que traduzir paginas geradas em vez das paginas fonte e geralmente um mais suscetivel a erro e, portanto, uma ma ideia. mdoc Esta opcao e apenas util para paginas mdoc. Ela seleciona um suporte mais estrito ao formato mdoc ao informar po4a que nao deve traduzir a secao "NAME". Paginas mdoc cuja secao "NAME" esta traduzida nao vao gerar cabecalho ou nota de rodape algum. De acordo com as paginas do groff_mdoc, as secoes NAME, SYNOPSIS e DESCRIPTION sao obrigatorias. Nao ha problemas conhecidos com secoes SYNOPSIS ou DESCRIPTION traduzidas, mas voce tambem pode especificar essas secoes 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 mes, ano" OS "Nome da secao" The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a. They take as argument a comma-separated list of macros. For example: -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX Nota: se uma macro nao tem suporte no po4a e se voce considera que e uma macro roff padrao, voce deveria envia-la para a equipe de desenvolvimento do po4a. untranslated untranslated indica que esta macro (em seus argumentos) nao deveria ser traduzida. noarg noarg e como untranslated, exceto que po4a vai verificar que nenhum argumento e adicionar a esta macro. translate_joined translate_joined indica que po4a deve propor a traducao de argumentos da macro. translate_each Com translate_each, os argumentos tambem serao propostos para a traducao, exceto que cada um sera traduzido separadamente. no_wrap Esta opcao leva como argumento uma lista de pares de begin:end separados por virgula, onde begin e end sao comandos que delimitam o inicio e fim de uma secao que nao deveria ser redimensionada. Nota: nenhum teste e feito para assegurar que um comando end corresponde ao seu comando begin; qualquer comando de finalizacao termina o modo no_wrap. Se voce tem uma macro begin (respectivamente end) que nao possui end (respectivamente begin), voce pode especificar uma end existente (como fi) ou begin (como nf) como uma contraparte. Essas macros (e seus argumentos) nao serao traduzidos. inline Esta opcao especifica uma lista de macros separadas por virgula que nao podem dividir o paragrafo atual. A string a ser traduzida vai, entao, conter foo <.bar baz qux> quux, sendo bar o comando que deveria ser embutido, e baz qux seus argumentos. unknown_macros Esta opcao indica como po4a deveria se comportar quando uma macro desconhecida e encontrada. Por padrao, po4a falha com um aviso. Ele pode levar os valores a seguir: failed (o valor padrao), untranslated, noarg, translate_joined ou translate_each (veja acima uma explicacao para cada um desses valores). CRIACAO DE PAGINAS MAN COMPATIVEIS COM PO4A::MAN Este modulo ainda e bem limitado, e sempre sera, pois ele nao e um interpretador nroff de verdade. Seria possivel criar um interpretador nroff para permitir que autores usem todas as macros existentes ou ate mesmo definir novas em suas paginas, mas nos nao queriamos. Seria muito dificil e nos entendemos nao haver necessidade. Nos pensamos que se os autores de paginas man desejam ver seus produtos traduzidos, eles podem ter que adaptar para facilitar o trabalho dos tradutores. Entao, o analisador de manuais implementado no po4a possui algumas limitacoes conhecidas que nos nao exatamente estamos podendo corrigir e que podem ser buracos a serem evitados se voce nao quiser ver tradutores tomando conta da sua documentacao. Nao programe em nroff nroff e uma linguagem de programacao completa, com definicao de macros, condicionais e por ai vai. Ja que este analisador nao e um interpretador nroff com todas suas funcionalidades, ela vai falhar em paginas usando essas capacidades (Ha cerca de 200 de tais paginas no meu computador). Uso o conjunto de macros simples Ha ainda algumas macros que nao encontram suporte no po4a::man. Isso porque eu nao consegui encontrar qualquer documentacao sobre elas. Aqui esta a lista de macros sem suporte, usadas na minha maquina. Note que essa lista nao e exaustiva, ja que o programa falha na primeira macro sem suporte encontrada. Se voce nao possui qualquer informacao sobre algumas dessas macros, ficarei feliz em adicionar suporte a elas. Por causa dessas macros, cerca de 250 paginas estao inacessiveis 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 nao sao traduziveis e, portanto, nao deveriam ser extraidas pelo po4a. Por exemplo, uma opcao pode aceitar um argumento other e other tambem pode aparecer como o ultimo item de uma lista. No primeiro caso, other nao deveria ser traduzivel. 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 opcao -o groff_code=verbatim) Uma nova macro tambem pode ser definida para automatizar isso: .de IR_untranslated . IR \\$@ .. .IR_untranslated \-q ", " \-\-quiet (Isto vai exigir as opcoes -o groff_code=verbatim e -o untranslated=IR_untranslated; com este construct, a condicional .if !'po4a'hide' nao e estritamente necessaria ja que po4a nao vai analisar o interno da definicao de macro) ou usando o alias: .als IR_untranslated IR .IR_untranslated \-q ", " \-\-quiet Isto vai exigir a opcao -o untranslated=als,IR_untranslated. Conclusao Para resumir esta secao, mantenha simples e nao tente ser esperto ao criar suas paginas man. Muitas coisas sao possivel no nroff, mas que nao tem suporte neste analisador. Por exemplo, nao tente baguncar o \c interrompendo o processamento de texto (como 40 paginas na minha maquina fazem). Ou, certifique-se de que colocar os argumentos de macros na mesma linha da propria macro. Eu se que e valido no nroff, mas complicado demais para o analisador lidar. E claro, outra possibilidade e usar outro formato, mais amigavel ao tradutor (como POD usando po4a::pod ou um da familia XML como o SGML), mas gracas ao po4a::man isso nao e mais necessario. Tendo dito isso, se o formato fonte da documentacao e POD, ou XML, pode ser inteligente traduzir o formato fonte e nao este gerado. Na maioria dos casos, po4a::man vai detectar paginas geradas e mostrar um aviso. El vai ate mesmo recusar processar paginas geradas no POD porque tais paginas sao lidadas perfeitamente pelo po4a::pod, e porque sua contraparte nroff define um monte de novas macros que eu nao desejo dar suporte. Na minha maquina, 1432 das 4323 pagina sao geradas de POD e vao ser ignoradas pelo po4a::man. Na maioria dos casos, po4a::man vai detectar o problema e se recusar a processar a pagina, apresentando uma mensagem adaptada. Em alguns casos raros, o programa vai completar sem avisos, mas a saida estara errada. Tais casos sao chamados de "bugs" ;) Se voce encontrar tal caso, certifique-se de relata-lo, junto com uma solucao, quando possivel ESTADO DESTE MODULO Este modulo pode ser usado para a maioria das paginas man existentes. Alguns testes sao executados frequentemente em maquinas Linux: o um terco das paginas sao recusadas porque foram geradas a partir de outro formato com suporte no po4a (ex: POD ou SGML). o 10% das paginas remanescentes sao rejeitadas com um erro (ex: uma macro groff nao tem suporte). o Entao, menos de 1% das paginas sao aceitas silenciosamente pelo po4a, mas com problemas significantes (isto e, palavras faltando ou novas palavras inseridas) o As outras paginas sao normalmente lidadas sem diferencas mais importantes do que diferencas de espacamento ou linha redimensionada (problemas de fontes em menos de 10% das paginas processadas). VEJA TAMBEM Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7) AUTORES Denis Barbier Nicolas Francois Martin Quinson (mquinson#debian.org) COPYRIGHT E LICENCA Copyright (C) 2002-2008 SPI, Inc. Esse programa e um software livre; voce pode redistribui-lo e/ou modifica-lo sob os termos da GPL v2.0 ou posterior (veja o arquivo COPYING). perl v5.38.2 2024-06-26 LOCALE::PO4A::MAN.3PM(1)