How to write script usage section

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

Replies are listed 'Best First'.
Re: How to write script usage section by reasonablekeith (Deacon) on Sep 07, 2005 at 13:26 UTC
the Getopt::Long module's own documentation has this to say on the matter... "Getopt::Long encourages the use of Pod::Usage to produce help messages. For example:" use Getopt::Long; use Pod::Usage; my $man = 0; my $help = 0; GetOptions('help\|?' => \$help, man => \$man) or pod2usage(2); pod2usage(1) if $help; pod2usage(-exitstatus => 0, -verbose => 2) if $man; __END__ =head1 NAME sample - Using Getopt::Long and Pod::Usage =head1 SYNOPSIS sample [options] [file ...] Options: -help brief help message -man full documentation =head1 OPTIONS =over 8 =item B<-help> Print a brief help message and exits. =item B<-man> Prints the manual page and exits. =back =head1 DESCRIPTION B<This program> will read the given input file(s) and do someting useful with the contents thereof. =cut [download] --- my name's not Keith, and I'm not reasonable.	[reply] [d/l]
Re^2: How to write script usage section by perl@newbie (Novice) on Sep 08, 2005 at 14:33 UTC
what does "=over 8" and "=item B<-help>" signify. And what does "cut" do. I can see "cut" in the man page documentation for my script. Whats it for. How can i put a new line while writing the pod usage ie New line should appear in the man page else the man page looks quite cluttered Pardon me but im absolutely new to the whole word of scripting.	[reply]
Re^3: How to write script usage section by philcrow (Priest) on Sep 08, 2005 at 14:40 UTC
=over some_number begins a list =back ends it. All pod commands begin at the left margin with =. Pod thinks in paragraphs, where paragraph is defined as a group of lines separated from other groups by one or more blank lines. See perlpod for details on pod, it is quite simple, but highly effective. Phil	[reply]
Re^3: How to write script usage section by gellyfish (Monsignor) on Sep 08, 2005 at 14:38 UTC
Read perlpod in the first instance. /J\	[reply]
Re: How to write script usage section by Random_Walk (Prior) on Sep 07, 2005 at 13:27 UTC
I asked a similar question recently at deriving usage from Getopts::Long and got some nice answers on mixing usage in POD so you get your usage 'for free' in your POD documentation This node The Dynamic Duo was the solution I went with in the end. I have now made a standard framework for starting a script based on this idea and the client loved the HTML man pages and being able to `my_script.pl -man` Cheers, R. Pereant, qui ante nos nostra dixerunt!	[reply] [d/l] [select]
Re: How to write script usage section by gellyfish (Monsignor) on Sep 07, 2005 at 13:27 UTC
You might want to consider using Pod::Usage as this makes it easier to keep your usage instructions consistent with your documentation. /J\	[reply]
Re: How to write script usage section by pbeckingham (Parson) on Sep 07, 2005 at 13:31 UTC
Consider Getopt::Declare as an alternative. It's worth reading about - it basically combines both the usage statement and the `Getopt` call. pbeckingham - typist, perishable vertebrate.	[reply] [d/l]
Re: How to write script usage section by pg (Canon) on Sep 07, 2005 at 13:35 UTC
Give enough examples! I think you'll agree that, a long document without (enough) examples, is difficult to understand, or difficult for the readers to believe that they actully got it.	[reply]