I would like to correctly format my help message for my Perl scripts and if possible by using a standard module such as Pod::Usage. Unfortunately I do not really like the output format of pod2usage. For instance, with grep I get the following help structure:
$ grep --help
Usage: grep [OPTION]... PATTERN [FILE]...
Search for PATTERN in each FILE or standard input.
PATTERN is, by default, a basic regular expression (BRE).
Example: grep -i 'hello world' menu.h main.c
Regexp selection and interpretation:
-E, --extended-regexp PATTERN is an extended regular expression (ERE)
-F, --fixed-strings PATTERN is a set of newline-separated fixed strings
-G, --basic-regexp PATTERN is a basic regular expression (BRE)
-P, --perl-regexp PATTERN is a Perl regular expression
But this is very different with Pod::Usage and I get unwanted \n and \t:
$ ./sample.pl --help
Usage:
sample [options] [file ...]
This program will read the given input file(s) and do something useful
with the contents thereof.
Options:
--help
Print a brief help message and exits.
--man
Prints the manual page and exits.
I would like to modify the format of my help in the traditional way i.e. without \n and without leading \t. In fact, I am looking to solution that allows me to write this:
__END__
=head1 SYNOPSIS
sample [options] [file ...]
B<This program> will read the given input file(s) and do something
useful with the contents thereof.
=head1 OPTIONS
=item B<-h,--help>
Print a brief help message and exits.
=item B<-v,--version>
Prints the version and exits.
=cut
And get this:
Usage: sample [options] [file ...]
This program will read the given input file(s) and do something useful
with the contents thereof.
Options:
-h, --help Print a brief help message and exits.
-v, --version Prints the version and exits.
Not this:
Usage:
sample [options] [file ...]
This program will read the given input file(s) and do something useful
with the contents thereof.
Options:
-h,--help Print a brief help message and exits.
-v,--version Prints the version and exits.
Any clue ?
When you use =item, you should prefix it with an =over x where x is how far you want to move over. After you finish your items, you need to use =back. If =over x is far enough over, the paragraph for that item will print on the same line as the =item. I played around and found =over 20 looks pretty good:
use strict;
use warnings;
use Pod::Usage;
pod2usage( -verbose => 1);
=pod
=head1 SYNOPSIS
sample [options] [file ...]
B<This program> will read the given input file(s) and do something
useful with the contents thereof.
=head1 OPTIONS
=over 20
=item B<-h>, B<--help>
Print a brief help message and exits.
=item B<-v>, B<--version>
Prints the version and exits.
=back
=cut
This prints out:
Usage:
sample [options] [file ...]
This program will read the given input file(s) and do something useful
with the contents thereof.
Options:
-h, --help Print a brief help message and exits.
-v, --version Prints the version and exits.
There's not much you can do with the v, --version stuff in POD to get it to print in pretty three column format. What you can do is give a bit more space between the -h and --help like I did above in order to improve readability.
Remember, the important stuff is the data in your POD and not the absolute formatting. Use the formatting to make it easy to read, but don't sweat the details too much.
I highly recommend you use the old standard Man page layout (which Pod2Usage assumes).