Perl tutorial : usage() and here dcuments

I tend to write many Perl utilities. Some are just a few hundred lines. But the user needs to know how to use it. As is usual, written documentation is not well maintained and rarely read. But if the default behavior of a application is to print a small man page when there is an invalid parameter, then you have useful and used documentation.

I make this a feature of everything I expect to be used by others. If it is that complex, I put it in anyway so I do not have to read the code. Just run

myscript -help

Actually any invalid option will work. I usually don't have a specific test for "-help".

Here documents like in shell scripts are handled like double quoted strings. Variables are interpreted.

So instead of

sub usage
{
print "fobar() -dir DIR\n";
print " -dir DIR is the directory to ...\n";
exit(); //yes I always assume that usage() is an exit point.
}

do

sub usage
{
print <<endodcs
fobar() -dir DIR
-dir DIR is the directory to ...
enddocs
; #end of print statement
exit();
}