perl::scribe has asked for the wisdom of the Perl Monks concerning the following question:

Dear brethren,

I am interested in using POD to document my perl programs. In fact, I've already done so in the past.
The thing is, however, that I turn most of my programs into executables, since they are meant to be used on systems that do not have and by people who are unfamiliar with perl.
To my knowledge, you cannot use perldoc to display the POD within these programs. Is this true or is it just a figment of my imagination?
Until now I've just used print or die to display a program's documentation, but this system is far less versatile than POD, nor does it allow for the use of inline documentation.

I'm probably just missing something here.
Any thoughts? How do you document perl executables?

Thanks in advance.
May Larry be with you!

my $name = Perl::scribe->new();

Replies are listed 'Best First'.
Re: Documenting executables
by joefission (Monk) on Aug 17, 2001 at 17:38 UTC
    You should be able to use options (--help) and/or a combination of Getopt and POD::Usage to provide documentation.
[reply]
      > You should be able to use options (--help) and/or a combination of Getopt and POD::Usage to provide documentation.

      Thanks for the tip, joefission. Indeed, I have used options (Getopt::Long) before, but not in combination with Pod::Usage.
      What I do now is: if there's an option or a lack of arguments, I run a sub usage() that prints or dies up to a certain terminating string, e.g. EOT.
      What I'm missing, though, is the ability to markup your documentation, like you can with POD.
      Any other ideas?

      Thanks
      May Larry be with you

      my $name = Perl::scribe->new();
[reply]
[d/l]
[select]

        Did you really take a close look at POD::Usage as suggested by joefission?? I think this module does what you want, namely extract (part of) the pod of your script and print it out. This can be used instead of a usage sub. Take especially a look at the example at the end of the documentation - I think that does exactly what you were looking for.

        Please correct me if I misunderstood what you are trying to do ...

        -- Hofmator

[reply]
Re: Documenting executables
by chipmunk (Parson) on Aug 17, 2001 at 21:06 UTC
    Heh. People who do not have or are unfamiliar with perl also will not have or will not be familiar with perldoc. If you want to go this route, you could use perldoc or some other POD parser to grab the documentation from your script, format it, and save it to a file, which you can distribute with the executable.
[reply]

Back to Seekers of Perl Wisdom