[Israel.pm] Perl documentation: to pod or not to pod

[Shlomi Fish]

Hi Yossi!

On Mon, Apr 14, 2008 at 12:52 PM, Yossi Itzkovich
<Yossi.Itzkovich at ecitele.com> wrote:
> Hi,
>
>  I have a big script (that used few of my modules) that I must document
>  :-(, so other non-perl people can understand.
>  I never documented my Perl code using a standard way.  Should I use POD
>  ?  Is there a different (better?) way ?
>
>  (I find pod easy to others, because on unix they can just "man" it ,
>  just like for every other command around.)
>

POD would be a fine choice for many things. Also see the Pod::Usage
idiomatic use:

http://perldoc.perl.org/Pod/Usage.html

For simple stuff POD does very well. Probably not for you, but there
are also other document formats:

http://www.shlomifish.org/philosophy/computers/web/choice-of-docs-formats/

You may consider a literate programming (
http://en.wikipedia.org/wiki/Literate_programming ) approach to
maintain the documentation markup and the code itself together. Note
that POD is not Literate programming:

http://www.perl.com/pub/a/tchrist/litprog.html

Regards,

          Shlomi Fish

>  Yossi
>  _______________________________________________
>  Perl mailing list
>  Perl at perl.org.il
>  http://perl.org.il/mailman/listinfo/perl
>



-- 
------------------------------------------
Shlomi Fish http://www.shlomifish.org/

Electrical Engineering studies. In the Technion. Been there. Done
that. Forgot a lot. Remember too much.