LOCALE::PO4A::MAN.3PM(1) User Contributed Perl Documentation NOME Locale::Po4a::Man - converte paginas do manual de/para ficheiros files DESCRICAO O objetivo do projeto po4a (PO for anything: PO para qualquer coisa) e facilitar traducoes (e o mais interessante, a manutencao das traducoes) a usar as ferramentas do gettext em areas em que nao se esperava, como na documentacao. Locale::Po4a::Man e um modulo para ajudar na traducao de documentacao em formato nroff (a linguagem das paginas do manual) em outras linguas [humana]. TRADUZINDO COM PO4A::MAN Este modulo tenta com bastante forca tornar a vida do tradutor mais facil. Para isso, o texto apresentado aos tradutores nao e uma copia literal do texto encontrado na pagina do manual. De fato, as partes mais cruas do formato nroff estao escondidos, por isso os tradutores nao se podem atrapalhar com elas. Text envolvido Paragrafos sem recuo sao automaticamente reevolvidos para o tradutor. Isto pode levar a uma diferenca menor na saida gerada, uma vez que as regras de reenvolvimento usadas por groff nao sao muito claras. Por exemplo, dois espacos depois de um parentese as vezes sao preservados. De qualquer forma, a diferenca sera apenas sobre a posicao dos espacos extrano paragrafo envolto e acho que vale a pena. Especificacao da Font A primeira mudanca e sobre as especificacoes de mudanca de font. Em nroff, existem varias maneiras para especificar se uma determinada palavra deve ser escrita em pequeno, negrito ou italico. No texto para traduzir, so ha um caminho, emprestado do formato POD (Perl documentacao on-line): I -- texto em italico equivalente a \fItext\fP or ".I text" B -- texto em negrito equivalente a \fBtext\fP or ".B text" R -- texto romano equivalente a \fRtext\fP CW -- texto de largura constante equivalente a \f(CWtext\fP or ".CW text" Observacao: O rosto CW nao esta disponivel para todos os aparelhos groff. Nao e recomendado usa-lo. Ele e fornecido para sua conveniencia. Transliteracao automatica de carateres Po4a automaticamente translitera alguns carateres para facilitar a traducao ou revisao da traducao. Aqui esta a lista das transliteracoes: hifenes Hifens (-) e sinais de menos (\-) em paginas de manual sao todos transliterados como tracos simples (-) no ficheiro PO. Assim todos os tracos sao transliterados em sinais roff menos (\-) quando a traducao e inserida no documento de saida. Os tradutores podem forcar um hifen a usar o roff glyph '\[hy]' nas suas traducoes. espacos nao-separaveis Os tradutores podem usar espacos nao separaveis nas suas traducoes. Estes espacos nao separaveis (0xA0 em latin1) serao transliterados num roff non-breaking space ('\ '). transliteracoes citadas `` e '' sao respetivamente, transliterados em \*(lq and \*(rq. Para evitar essas transliteracoes, os tradutores podem inserir um caratere roff largura zero (ou seja, a usar `\ &` or '\&' respectivamente). Colocando '<' e '>' em traducoes Desde que estes caracteres sao utilizadas para delimitar partes sob modificacao da font, nao os pode usar na integra. Use E e E em vez (como em POD, mais uma vez). OPCOES ACEITES POR ESTE MODULO Estas sao as opcoes particulares deste modulo: debug Ativar a depuracao para alguns mecanismos internos deste modulo. Use a fonte para ver que partes podem ser depuradas. verbose Aumentar o detalhe. groff_code Esta opcao controla o comportamento do modulo quando ele encontrar uma seccao .de, .ie ou .if . Ele pode levar os valores a seguir: fail Este e o valor predefinido. O modulo ira falhar quando uma seccao .de, .ie ou .if e encontrada. verbatim Indica que as seccoes .de, .ie ou .if, devem ser copiadas como estao no original para o documento traduzido. translate Indica que as seccoes .de, .ie ou .if serao propostas para a traducao. So deve usar essa opcao se uma cadeia traduzivel esta contida numa destas seccoes. Caso contrario, verbatim deve ser preferida. generated Esta opcao especifica que o ficheiro foi gerado e que po4a nao deve tentar detetar 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 so e util para paginas mdoc. Seleciona um rigoroso suporte do formato mdoc a dizer a po4a para nao traduzir a seccao 'NOME'. Paginas mdoc cuja seccao 'NOME' e traduzida nao ira gerar qualquer cabecalho ou rodape. De acordo com a pagina groff_mdoc, as seccoes NOME, SINOPSE e DESCRICAO sao obrigatorias. Nao existem problemas conhecidos com a seccao SINOPSE traduzida ou a seccao DESCRICAO, mas tambem pode especificar estas seccoes da seguinte forma: -o mdoc=NAME,SYNOPSIS,DESCRIPTION Esta questao mdoc tambem pode ser resolvida com uma adenda como esta: Po4a-HEADER:mode=before;position=^.Dd .TH DOCUMENT_TITLE 1 " Month day, year"OS " Section Name" 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 e suportada pelo po4a e se considerar que e uma macro roff predefinido, deve envia-la ao equipa de desenvolvimento po4a. untranslated untranslated indica que esta macro (nos seus argumentos) nao tem que ser traduzida. noarg noarg e como untranslated, exceto que po4a ira verificar que nenhum argumento e adicionado a esta macro. translate_joined translate_joined indica que po4a deve propor a traducao dos argumentos da macro. translate_each Com translate_each, os argumentos tambem serao propostos para a traducao, exceto que cada um sera traduzido em separado. no_wrap Essa opcao usa como argumento uma lista de pares separados por virgula begin:End, onde begin e End sao comandos que delimitam o comecar e terminar de uma seccao que nao deve ser re-envolvida. 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 tem uma macro begin (respectivamente end) que nao possui end (respectivamente begin), Pode especificar uma end existente (como fi) ou begin (como nf) como uma contraparte. Essas macros (e os argumentos deles) nao serao traduzidos. inline Esta opcao especifica uma lista de macros separadas por virgula que nao devem dividir o paragrafo atual. A cadeia a traduzir contera entao foo <.bar baz qux> quux onde bar e o comando que deve ser 'inlined', e baz qux os argumentos dele. unknown_macros Esta opcao indica como po4a deve se comportar quando uma macro desconhecida e encontrada. Por predefinicao, po4a falha com um aviso. Ele pode tomar os seguintesvalores: failed (o valor predefinido), untranslated, noarg, translate_joined, ou translate_each (ver acima para uma explicacao destes valores). AUTORIA DAS PAGINAS DE MANUAL COMPATIVEL COM PO4A::MAN Este modulo e ainda muito limitado e, sempre vai ser, porque nao e um interprete nroff real. Seria possivel fazer um interprete nroff real, permitir que os autores usarem todas as macros existentes, ou ate mesmo para definir novas nas suas paginas, mas nao quisessemos. Seria muito dificil e pensamos que nao era necessario. Pensamos que se os autores das paginas de manual quiserem ver as suas producoes traduzidas, devem ter de se adaptar a facilitar o trabalho dos tradutores. Portanto, o analisador de manual implementado em po4a tem algumas limitacoes conhecidas que sao e nao estamos realmente inclinados a corrigir e que constituira algumas armadilhas que tem de evitar se quiser ver tradutores cuidarem da sua documentacao. Nao programe em nroff nroff e uma linguagem de programacao completa, com a definicao de macro, condicionais e assim por diante. Uma vez que este analisador esta totalmente caracterizado como interprete nroff, ira falhar em paginas que utilizam estas instalacoes (ha cerca de 200 tais paginas na minha caixa). Use o conjunto de macro simples Existem ainda alguns macros que nao sao suportadas por po4a::man. E assim porque eu nao encontrei nenhuma documentacao sobre elas. Aqui esta a lista de macros sem suporte, utilizadas na minha caixa. Note que esta lista nao e exaustiva uma vez que o programa falha no primeiro macro, que encontra sem suporte. Se tem alguma informacao sobre algumas desses macros, ficarei feliz em adicionar suporte para elas. Devido a estes macros, cerca de 250 paginas na minha caixa sao 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 Escondendo texto de po4a As vezes, o autor sabe que algumas partes nao sao traduziveis e nao devem ser extraidas por po4a. Por exemplo, uma opcao pode aceitar um argumento other e other tambem pode aparecer como o ultimo item duma lista. No primeiro caso, other nao deve ser traduzido. E, no segundo caso, other deve ser traduzido. Em tal caso, o autor pode evitar po4a para extrair algumas cadeias, a usar algumas construcoes especiais groff: .if !'po4a'hide' .B other (isto vai exigir a opcao -o groff_code=verbatim) A nova macro tambem pode ser definida para automatizar isto: .de IR_untranslated . IR \\$@ .. .IR_untranslated \-q ", " \-\-quiet (isto vai exigir as opcoes -o groff_code =verbatim e -o untranslated=IR_untranslated; com esta construcao, o .if !'po4a'hide' condicional nao e estritamente necessario uma vez que po4a nao ira analisar o interno da definicao da macro) ou a utilizar um alias: .als IR_untranslated IR .IR_untranslated \-q ", " \-\-quiet Isso vai exigir o -o untranslated=als,IR_untranslated option. Conclusao Para resumir esta seccao, manter simples e nao tente ser inteligente a quanto da autoria das suas paginas de manual. Muitas coisas sao possiveis em nroff e nao suportadas por este analisador. Por exemplo, nao tente mexer em \c para interromper o processamento de texto (como 40 paginas na minha caixa de 'a fazer'). Ou seja, certo a por os argumentos do macro na mesma linha em que o macro esta. Sei que e valido em nroff, mas iria complicar muito o analisador para ser tratado. E claro, outra possibilidade e usar outro formato, mais amigavel ao tradutor (como POD a usar 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 detetar 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. Geralmente, po4a::man vai detetar o problema e se recusar a processar a pagina, a apresentar 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 encontrar tal caso, certifique-se de relata-lo, com uma solucao, quando possivel ESTADO DESTE MODULO Este modulo pode ser usado para a maioria das paginas de manual existentes. Alguns testes sao regularmente executado em maquinas Linux: o um terco das paginas sao recusadas porque foram geradas a partir de outro formato suportado pelo po4a (por exemplo, POD ou SGML). o 10% das paginas remanescentes sao rejeitadas com um erro (por exemplo, uma macro groff nao e suportada). o Em seguida, menos de 1% das paginas sao aceites por po4a silenciosamente, mas com questoes significativas (ou seja, palavras que faltam, ou palavras novas inseridas) o As outras paginas sao geralmente tratadas sem diferencas mais importantes do que as diferencas de espacamento ou linhas reevolvidas (problemas com fontes sao menos de 10% das paginas processadas). VER TAMBEM Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7) AUTORES Denis Barbier Nicolas Francois Martin Quinson (mquinson#debian.org) DIREITOS DE AUTOR E LICENCA Copyright (C) 2002-2008 SPI, Inc. This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). perl v5.38.2 2024-06-26 LOCALE::PO4A::MAN.3PM(1)