2012/6/7 Aureliano Guedes <[email protected]>: > Assim, toda distribuição, quando o autor submete ao CPAN, tem uma > documentação. Essa documentação vai junto ao *.tar.gz?? Ela é o arquivo > README, certo?? > Tem alguma formatação especial para o arquivo README ou eu posso escrever > essa documentação da forma que eu preferir?? > Ela precisa estar em formato html ou pode ser escrito normal? >
Você quer subir uma nova distribuição para o CPAN, é isso? Peraí, tem algo errado...Essa sua mensagem só tem 1 hora, mas a sua conta no CPAN tem uma distribuição "P50Tools" que subiu a 2 dias atrás, já está na versão 0.5 e não tem README nem Changes. O ideal nessas horas é perguntar *antes* de fazer, né? Bom, enfim. Respondendo a sua pergunta: uma distribuição Perl vem com 3 arquivos essenciais de documentação: * README - dá informações genéricas da distribuição, em especial o que é, como instalar e quem procurar em caso de dúvidas. Costuma ser gerada automaticamente; * Changes - contém a lista de principais mudanças em cada versão. Recomenda-se seguir o padrão em https://metacpan.org/module/CPAN::Changes::Spec. A primeira versão deste arquivo costuma ser criada automaticamente, e depois vc incrementa ele manualmente a cada nova versão; * POD - Plain Old Documentation - documentação que você cria (ou que é criada automaticamente pra vc) sobre cada um de seus módulos, como decrição, lista de métodos, como utilizar, bugs, copyright, etc. POD é uma linguagem de marcação simples baseada em tags na forma "=NNN". Pode ficar em um arquivo separado, mas a maioria dos autores escreve no próprio módulo. Pode ser escrito "inline": ---------------------8<--------------------- package Bla; =head2 new cria o seu objeto. Recebe opcionalmente os seguintes parametros: ..... =end sub new { ... } --------------------->8--------------------- Ou, mais recomendado por alguns, no final do arquivo, após uma tag de __END__ ---------------------8<--------------------- package Bla; sub new { ... } __END__ =head2 new cria o seu objeto. Recebe opcionalmente os seguintes parametros: ..... =end --------------------->8--------------------- Mais informações sobre o formato POD vc encontra em "perldoc perlpod". Se tivesse usado o Module::Starter, um esqueleto de todos esses arquivos teria sido criado para você. O Dist::Zilla também deveria ter feito algo parecido, acho. Infelizmente não posso te ajudar nessa pq, bem... não uso o Dist::Zilla. Minha vez de perguntar: O que é o arquivo "mkf.pl" ? O que é o arquivo "make"? Parecem coisas que você colocou sem querer dentro da dist. O arquivo "MANIFEST" inclui a lista de arquivos que vão entrar no seu .tar.gz. Retirar os arquivos dessa lista significa que você pode usá-los sem se preocupar com eles entrando na sua distribuição. Muitos autores preferem usar um MANIFEST.SKIP que cria um MANIFEST automaticamente incluindo tudo menos o que vc definir no arquivo (incluindo expressões regulares para nomes de arquivos que vc não quer botar). O Dist::Zilla deve ter uma opção pra isso, sinceramente não me lembro. Mais importante: onde estão os seus testes? Não tão importante mas que me deixou muito curioso: pq uma distribuição para pentest se chama "P50Tools"? []s -b _______________________________________________ Rio-pm mailing list [email protected] http://mail.pm.org/mailman/listinfo/rio-pm
