[SP-pm] Documentação com acentuação.

Adriano Ferreira a.r.ferreira em gmail.com
Sexta Janeiro 11 12:20:59 PST 2008


2008/1/11 Daniel (R) Antunes <danielrantunes at yahoo.com.br>:
>
>     Oi amigos, boa tarde...
>     Estou documentando um sistema, utilizando o POD. Até aí blzinha. (A
> propósito da discussão que está rolando sobre o assunto; eu particularmente
> utilizo POD inline).
>     Acontece que fiz com acentuação esta documentação. Meu locale padrão
> está com : pt_BR.UTF-8 e na máquina remota (onde roda o sistema) também.
>     Quando executo : perldoc Module.pm
>     Ele mostra aqueles caracteres voadores não identificados.
>     Tenho o hábito de documentar "in english", porém, este sistema precisa
> estar em bom português.
>     É possível utilizar acentuação ?

O defeito não é do POD que você escreveu, mas do processador pod2man
que não se dá bem com caracteres não ASCII.

Em um terminal utf-8, você terá uma apresentação razoável se instruir
o "perldoc" a usar o "pod2text" ao invés.

$ perldoc -otext Module

(embora possa aparecer alguns warnings sobre wide chars).

Os processadores POD estão precisando de ser melhorados. Vamos torcer
para que isto aconteça nos próximos meses, melhorando o suporte à
internacionalização da documentação Perl. Algumas coisas já podem
funcionar ok com alguns hacks (como conversores de POD para HTML se o
charset usado for utf-8).

Adriano Ferreira

>     Desde já muitíssimo obrigado.
>  Daniel (R) Antunes
> profissional de informática
> gnu/linux user #238553


>
> ----- Mensagem original ----
> De: Lucas F. Rosada <lucasrosada at gmail.com>
> Para: saopaulo-pm at mail.pm.org
> Enviadas: Sexta-feira, 11 de Janeiro de 2008 15:30:45
> Assunto: Re: [SP-pm] Documentação de cabeçalho de rotinas
>
> Otávio,
>
> Quando disse "documentar as funções e manter o POD do script em geral (com
> sinópse, autor, etc.) sem se ater às funções", eu estava me referindo a
> fazer um comentário com "#" no cabeçalho da função, explicando seus detalhes
> (para o desenvolvedor) e no POD (no fim do script) documentar estritamente o
> uso do script.
> Quanto a isso, inclusive, há um comentário no perlmonks no qual o usuário
> defende esse mecanismo de comentário acima (além de também questionar sobre
> a poluição visual que o POD Inline provoca). Acredito, sim, que a
> documentação deve ser completa e auto-explicativa, dispensando (na maior
> medida possível) a leitura do código-fonte.
>
> Agora, retomando uma das perguntas: existe algum padrão que vocês usam para
> documentar as rotinas?
> Existe algum modo bem difundido de documentação diferente do POD, que polua
> menos o script e permita, por exemplo, gerar man pages dos comentários?
>
> Desde já fico grato pelas respostas.
>
> Lucas.
>
>
> On Jan 11, 2008 1:34 PM, Otávio Fernandes <otaviof at gmail.com> wrote:
>
> > Lucas,
> >
> > Nao deveria ser ao contrario ?!
> >
> > A leitura de um fonte para saber o que o script faz eh errado, pois
> > consome muito mais tempo, e consequentemente, uma manutencao de rotina
> > tambem vai consumir. O ideal eh que somente com a documentacao do
> > script, no comeco de cada funcao e do arquivo, te deem toda a
> > informacao do que o script faz, e como ele o faz. O comentario vai ser
> > muito util na hora de alterar uma rotina, porem o excesso dele, no meu
> > ponto de vista, atrapalha.
> >
> > um abraco,
> >
> > --
> >  | --
> >  | Otávio Fernandes < otaviof | gmail | com >
> >  | FreeBSD 7.0-PRERELEASE && GNU/Linux User: 283.396
> >  | (( Especial Programação )) http://geekbr.podcastbrasil.com/ -- 0.15
> >  | --
> >
> >
> >
> > _______________________________________________
> > SaoPaulo-pm mailing list
> > SaoPaulo-pm at pm.org
> > http://mail.pm.org/mailman/listinfo/saopaulo-pm
> >
>
>
>
> --
> "O que há aí para mim?"
>
>
>  ________________________________
> Abra sua conta no Yahoo! Mail, o único sem limite de espaço para
> armazenamento!
> _______________________________________________
> SaoPaulo-pm mailing list
> SaoPaulo-pm at pm.org
> http://mail.pm.org/mailman/listinfo/saopaulo-pm
>


Mais detalhes sobre a lista de discussão SaoPaulo-pm