Pod::Usage help formatting

Question

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 ?

Answer 1

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).

Answer 2

Two things you can try:

The -noperldoc option to make it switch to Pod::Text, which is a simpler formatter.

or

Set a different formatter

Pod::Text has several formatting options as well, such as the left margin, indent level, page width which may make it more to your liking.