.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Man 3pm"
.TH Locale::Po4a::Man 3pm "2023-01-03" "Ferramentas Po4a" "Ferramentas Po4a"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NOME"
.IX Header "NOME"
Locale::Po4a::Man \- converte páginas do manual de/para ficheiros files
.SH "DESCRIÇÃO"
.IX Header "DESCRIÇÃO"
O objetivo do projeto po4a (\s-1PO\s0 for anything: \s-1PO\s0 para qualquer coisa) é facilitar traduções (e o mais interessante, a manutenção das traduções) a usar as ferramentas do gettext em áreas em que não se esperava, como na documentação.
.PP
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].
.SH "TRADUZINDO COM PO4A::MAN"
.IX Header "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.
.SS "Text envolvido"
.IX Subsection "Text envolvido"
Parágrafos sem recuo são automaticamente reevolvidos 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ços depois de um parêntese às vezes são preservados.
.PP
De qualquer forma, a diferença será apenas sobre a posição dos espaços extrano parágrafo envolto e acho que vale a pena.
.SS "Especificação da Font"
.IX Subsection "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 \s-1POD\s0 (Perl documentação on-line):
.IP "I<text> \*(-- texto em itálico" 4
.IX Item "I<text> texto em itálico"
equivalente a \efItext\efP or \*(L".I text\*(R"
.IP "B<text> \*(-- texto em negrito" 4
.IX Item "B<text> texto em negrito"
equivalente a \efBtext\efP or \*(L".B text\*(R"
.IP "R<text> \*(-- texto romano" 4
.IX Item "R<text> texto romano"
equivalente a \efRtext\efP
.IP "CW<text> \*(-- texto de largura constante" 4
.IX Item "CW<text> texto de largura constante"
equivalente a \ef(CWtext\efP or \*(L".CW text\*(R"
.PP
Observação: O rosto \s-1CW\s0 não está disponível para todos os aparelhos groff. Não é recomendado usá\-lo. Ele é fornecido para sua conveniência.
.SS "Transliteração automática de carateres"
.IX Subsection "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:
.IP "hífenes" 4
.IX Item "hífenes"
Hífens (\-) e sinais de menos (\e\-) em páginas de manual são todos transliterados como traços simples (\-) no ficheiro \s-1PO.\s0 Assim todos os traços são transliterados em sinais roff menos (\e\-) quando a tradução é inserida no documento de saída.
.Sp
Os tradutores podem forçar um hífen a usar o roff glyph '\e[hy]' nas suas traduções.
.IP "espaços não\-separáveis" 4
.IX Item "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 ('\e ').
.IP "transliterações citadas" 4
.IX Item "transliterações citadas"
`` e '' são respetivamente, transliterados em \e*(lq and \e*(rq.
.Sp
Para evitar essas transliterações, os tradutores podem inserir um caratere roff largura zero (ou seja, a usar `\e &` or '\e&' respectivamente).
.SS "Colocando '<' e '>' em traduções"
.IX Subsection "Colocando '<' e '>' em traduções"
Desde que estes carácteres são utilizadas para delimitar partes sob modificação da font, não os pode usar na íntegra. Use E<lt> e E<gt> em vez (como em \s-1POD,\s0 mais uma vez).
.SH "OPÇÕES ACEITES POR ESTE MÓDULO"
.IX Header "OPÇÕES ACEITES POR ESTE MÓDULO"
Estas são as opções particulares deste módulo:
.IP "\fBdebug\fR" 4
.IX Item "debug"
Ativar a depuração para alguns mecanismos internos deste módulo. Use a fonte para ver que partes podem ser depuradas.
.IP "\fBverbose\fR" 4
.IX Item "verbose"
Aumentar o detalhe.
.IP "\fBgroff_code\fR" 4
.IX Item "groff_code"
This option controls the behavior of the module when it encounter a .de, .ie or .if section. It can take the following values:
.RS 4
.IP "\fIfail\fR" 4
.IX Item "fail"
Este é o valor predefinido. O módulo irá falhar quando uma secção .de, .ie ou .if é encontrada.
.IP "\fIverbatim\fR" 4
.IX Item "verbatim"
Indica que as secções .de, .ie ou .if, devem ser copiadas como estão no original para o documento traduzido.
.IP "\fItranslate\fR" 4
.IX Item "translate"
Indica que as secções .de, .ie ou .if serão propostas para a tradução. Só deve usar essa opção se uma cadeia traduzível está contida numa destas secções. Caso contrário, \fIverbatim\fR deve ser preferida.
.RE
.RS 4
.RE
.IP "\fBgenerated\fR" 4
.IX Item "generated"
This option specifies that the file was generated, and that po4a should not try to detect if the man pages was generated from another format.  This option is mandatory to use po4a on generated man pages.  Note that translating generated pages instead of sources ones is often more fragile, and thus a bad idea.
.IP "\fBmdoc\fR" 4
.IX Item "mdoc"
Esta opção só é útil para páginas mdoc.
.Sp
Seleciona um rigoroso suporte do formato mdoc a dizer a po4a para não traduzir a secção '\s-1NOME\s0'. Páginas mdoc cuja secção '\s-1NOME\s0' é traduzida não irá gerar qualquer cabeçalho ou rodapé.
.Sp
De acordo com a página groff_mdoc, as secções \s-1NOME, SINOPSE\s0 e DESCRIÇÃO
são obrigatórias.
Não existem problemas conhecidos com a secção \s-1SINOPSE\s0 traduzida ou a secção DESCRIÇÃO,
mas também pode especificar estas secções da seguinte forma:
 \-o mdoc=NAME,SYNOPSIS,DESCRIPTION
.Sp
Esta questão mdoc também pode ser resolvida com uma adenda como esta:
 Po4a\-HEADER:mode=before;position=^.Dd
 .TH \s-1DOCUMENT_TITLE 1 \*(L"\s0 Month day, year\*(R"\s-1OS \*(L"\s0 Section Name\*(R"
.PP
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:
.PP
.Vb 1
\& \-o noarg=FO,OB,AR \-o translate_joined=BA,ZQ,UX
.Ve
.PP
Nota: se uma macro não é suportada pelo po4a e se considerar que é uma macro roff predefinido, deve enviá\-la ao equipa de desenvolvimento po4a.
.IP "\fBuntranslated\fR" 4
.IX Item "untranslated"
\&\fBuntranslated\fR indica que esta macro (nos seus argumentos) não tem que ser traduzida.
.IP "\fBnoarg\fR" 4
.IX Item "noarg"
\&\fBnoarg\fR é como \fBuntranslated\fR, exceto que po4a irá verificar que nenhum argumento é adicionado a esta macro.
.IP "\fBtranslate_joined\fR" 4
.IX Item "translate_joined"
\&\fBtranslate_joined\fR indica que po4a deve propor a tradução dos argumentos da macro.
.IP "\fBtranslate_each\fR" 4
.IX Item "translate_each"
Com \fBtranslate_each\fR, os argumentos também serão propostos para a tradução, exceto que cada um será traduzido em separado.
.IP "\fBno_wrap\fR" 4
.IX Item "no_wrap"
Essa opção usa como argumento uma lista de pares separados por vírgula \fIbegin\fR:\fIEnd\fR, onde \fIbegin\fR e \fIEnd\fR são comandos que delimitam o começar e terminar de uma secção que não deve ser re-envolvida.
.Sp
Note: no test is done to ensure that an \fIend\fR command matches its \fIbegin\fR command; any ending command stop the no_wrap mode.  If you have a \fIbegin\fR (respectively \fIend\fR) macro that has no \fIend\fR (respectively \fIbegin\fR), you can specify an existing \fIend\fR (like fi) or \fIbegin\fR (like nf) as a counterpart.  These macros (and their arguments) won't be translated.
.IP "\fBinline\fR" 4
.IX Item "inline"
Esta opção especifica uma lista de macros separadas por vírgula que não devem dividir o parágrafo atual. A cadeia a traduzir conterá então \fIfoo <.bar baz qux> quux\fR onde \fIbar\fR é o comando que deve ser 'inlined', e \fIbaz qux\fR os argumentos dele.
.IP "\fBunknown_macros\fR" 4
.IX Item "unknown_macros"
Esta opção indica como po4a deve se comportar quando uma macro desconhecida é encontrada. Por predefinição, po4a falha com um aviso. Ele pode tomar os seguintesvalores: \fBfailed\fR (o valor predefinido), \fBuntranslated\fR, \fBnoarg\fR, \fBtranslate_joined\fR, ou \fBtranslate_each\fR (ver acima para uma explicação destes valores).
.SH "AUTORIA DAS PÁGINAS DE MANUAL COMPATÍVEL COM PO4A::MAN"
.IX Header "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 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.
.PP
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.
.SS "Não programe em nroff"
.IX Subsection "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).
.SS "Use o conjunto de macro simples"
.IX Subsection "Use o conjunto de macro simples"
Existem ainda alguns macros que não são suportadas por po4a::man. É assim porque eu não encontrei nenhuma documentação sobre elas. Aqui está a lista de macros sem suporte, utilizadas na minha caixa. Note que esta lista não é exaustiva uma vez que o programa falha no primeiro macro, que encontra sem suporte. Se tem alguma informação sobre algumas desses macros, ficarei feliz em adicionar suporte para elas. Devido a estes macros, cerca de 250 páginas na minha caixa são inacessíveis para po4a::man.
.PP
.Vb 11
\& ..               ."              .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
.Ve
.SS "Escondendo texto de po4a"
.IX Subsection "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 \fIother\fR e \fIother\fR também pode aparecer como o último item duma lista. No primeiro caso, \fIother\fR não deve ser traduzido. E, no segundo caso, \fIother\fR deve ser traduzido.
.PP
Em tal caso, o autor pode evitar po4a para extrair algumas cadeias, a usar algumas construções especiais groff:
.PP
.Vb 1
\& .if !\*(Aqpo4a\*(Aqhide\*(Aq .B other
.Ve
.PP
(isto vai exigir o \fB\-o groff_code = verbatim\fRoption)
.PP
A nova macro também pode ser definida para automatizar isto:
 .de IR_untranslated
 .    \s-1IR\s0 \e\e$@
 ..
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
(isto vai exigir as opções \fB\-o groff_code =verbatim\fR e \fB\-o untranslated=IR_untranslated\fR; com esta construção, o \fB.if !'po4a'hide'\fR condicional não é estritamente necessário uma vez que po4a não irá analisar o interno da definição da macro)
.PP
ou a utilizar um alias: 
 .als IR_untranslated \s-1IR\s0
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
Isso vai exigir o \fB\-o untranslated=als,IR_untranslated\fR option.
.SS "Conclusão"
.IX Subsection "Conclusão"
Para resumir esta secção, manter simples e não tente ser inteligente a quanto da autoria das 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 em \ec para interromper o processamento de texto (como 40 páginas na minha caixa de 'a fazer'). Ou seja, certo a pôr os argumentos do macro na mesma linha em que o macro está. Sei que é válido em nroff, mas iria complicar muito o analisador para ser tratado.
.PP
É claro, outra possibilidade é usar outro formato, mais amigável ao tradutor (como \s-1POD\s0 a usar po4a::pod ou um da família \s-1XML\s0 como o \s-1SGML\s0), mas graças ao po4a::man isso não é mais necessário. Tendo dito isso, se o formato fonte da documentação é \s-1POD,\s0 ou \s-1XML,\s0 pode ser inteligente traduzir o formato fonte e não este gerado. Na maioria dos casos, po4a::man vai detetar páginas geradas e mostrar um aviso. El vai até mesmo recusar processar páginas geradas no \s-1POD\s0 porque tais páginas são lidadas perfeitamente pelo po4a::pod, e porque sua contraparte nroff define um monte de novas macros que eu não desejo dar suporte. Na minha máquina, 1432 das 4323 página são geradas de \s-1POD\s0 e vão ser ignoradas pelo po4a::man.
.PP
Geralmente, po4a::man vai detetar o problema e se recusar a processar a página, a apresentar uma mensagem adaptada. Em alguns casos raros, o programa vai completar sem avisos, mas a saída estará errada. Tais casos são chamados de \*(L"bugs\*(R" ;) Se encontrar tal caso, certifique-se de relatá\-lo, com uma solução, quando possível…
.SH "ESTADO DESTE MÓDULO"
.IX Header "ESTADO DESTE MÓDULO"
Este módulo pode ser usado para a maioria das páginas de manual existentes.
.PP
Alguns testes são regularmente executado em máquinas Linux:
.IP "\(bu" 4
um terço das páginas são recusadas porque foram geradas a partir de outro formato suportado pelo po4a (por exemplo, \s-1POD\s0 ou \s-1SGML\s0).
.IP "\(bu" 4
10% das páginas remanescentes são rejeitadas com um erro (por exemplo, uma macro groff não é suportada).
.IP "\(bu" 4
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)
.IP "\(bu" 4
As outras páginas são geralmente tratadas sem diferenças mais importantes do que as diferenças de espaçamento ou linhas reevolvidas (problemas com fontes são menos de 10% das páginas processadas).
.SH "VER TAMBÉM"
.IX Header "VER TAMBÉM"
\&\fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7)
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "DIREITOS DE AUTOR E LICENÇA"
.IX Header "DIREITOS DE AUTOR E LICENÇA"
Copyright © 2002\-2008 \s-1SPI,\s0 Inc.
.PP
Este programa é software livre, pode redistribuí\-lo e/ou modificá\-lo sob os termos da \s-1GPL\s0 (consulte o ficheiro CÓPIA).