I would put all the long-winded stuff into POD, and have just a short usage message -- a synopsis -- displayed in response to "-h" or "--help", or when required args are lacking, or when args are not compatible with allowed usage. The synposis simply lists the expected args and the allowed options in a nice, brief, easy-to-read format, and can end with something like "run perldoc $0 for full documentation".

For mac users running the script in a Terminal (or X-windows xterm), perldoc will automatically put the POD man page through the default paging program (usually "more" or "less"), and will make it look very polished and professional. Here's a typical template that I use for just about every perl script that I write:

#!/usr/bin/perl

# fill in paragraphs between the "=head1" lines:

=head1 NAME



=head1 SYNOPSIS



=head1 DESCRIPTION



=cut

use strict;

my $Usage = "$0 ";  # fill in synopsis here, as well as above
[download]

The perlpod man page explains how to put your "man page" documentation into your script. Also, the man page for Getopt::Long (you are using that module, aren't you?) has a section on "Documentation and help texts" which explains how to avoid having to duplicate your synopsis string.

(Note that my suggested template above requires the synopsis to be in two places -- that's because I haven't memorized that portion of the Getopt::Long man page yet...)

Update: If you are writing a command-line tool, and are intending that the user carry on a keyboard dialog with the script while it is running, I would offer the following suggestions:

• Think about what information is required from the user in order for the script to complete its task; if it's not a lot of things (some file names, a few parameter values, a boolean or two...) and all of it is knowable by the user at start-up, you really should get all that from @ARGV (i.e. command line args), and not ask for anything from the user once the script has started running. Providing keyboard input to a script while it is running is intensely inefficient, error-prone and annoying for the user.

• If the script really does need user input after it has started running (this is very rare, but can happen when the user's input depends on things that can only be known after some processing is done), then you need to look at the Term:: modules mentioned in the first reply, so that the user has some hope of correcting typos when providing keyboard input to the script while it's running.

If the script needs a lot of input from the user, but all of it is knowable in advance, then you're talking about "input data", which should be read from a file that the user provides (in @ARGV) -- the less keyboarding, the better.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.