mdunnbass has asked for the wisdom of the Perl Monks concerning the following question:

Hi all. I'm writing a command-line program, and I'm including a set of instruction on how to use it. At the main menu, I have something like "To RTFM, please enter 9."

I also have 

print << RTFM
...5 or 6 pages of long winded explanations

RTFM
print "\n\n";

[download]
As it stands, the people using this program will all be Mac users, using Terminal to run it. Is there a way to determine the # of rows in the terminal window they have running, and return the RTFM text block in a man-page style, where #rows-1 are printed to the screen, with a 'Press any key to continue' prompt at the bottom, awaiting <STDIN>?

I've tried googling and the archives here, but I think I must not be searching very well, as I am not finding anything nearly like what I want...

Thanks,
Matt

Replies are listed 'Best First'.
Re: print # of lines in window?
by derby (Abbot) on Oct 30, 2006 at 20:30 UTC
[reply]
Re: print # of lines in window?
by graff (Chancellor) on Oct 30, 2006 at 23:05 UTC
    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.

[reply]
[d/l]
      IO::Prompt is pretty helpful if you need to prompt the user for input
[reply]

Back to Seekers of Perl Wisdom