This note is intended to be a brief introduction to the workings of
vmsgetmail.  vmsgetmail is really intended to be run from GNU Emacs, but
it has enough functionality to be useful for other things as well.  It
even allows you to subvert the VMS mail system and peak at your mail
while leaving your newmail count unchanged---and the system really does
think the messages are still unseen :-)

The general syntax is (more below):

    $ vmsgetmail [-adnvV] [-f FILE] [-F FOLDER] [-u USER]

In order to use it in this fashion you must define a symbol to point to
the executable.  Normally, this would be:

    $ vmsgetmail :== $emacs_library:[etc]vmsgetmail

You do *NOT* need to do this for Emacs to find the program.  Emacs uses
the variable exec-path, which includes the [etc] directory, to find its
programs.  You only need to do the above if you want to use the program
outside of Emacs.

vmsgetmail takes several options.  Internally, it uses the GNU getopt
routines (getopt_long) to accept both long- and short-named options.
Here is a list of options, with required arguments (if any), and their
function:

    --append  -a         append to FILE (specified by --file)
    --count   -c         return the mail count only
    --delete  -d         delete messages after reading
    --file    -f FILE    output to FILE
    --folder  -F FOLDER  select mail from FOLDER
    --help    -h         display brief help message and exit
    --newmail -n         select new messages
    --user    -u USER    read mail for USER (not implemented!)
    --version -v         return version information
    --verbose -V         talk to me

You should be aware that VMS is a bit weird with respect to case
sensitivity.  VMS, in general, does not care about case, or rather, it
puts everything in uppercase.  However, it is possible to have VMS Mail
folder names which contain mixed case.  "Emacs" is a legal folder name,
and it is distinct from "EMACS", or any other folder with the same
spelling but different combinations of upper and lower case.  As a
consequence, you *must* enclose the folder name in double quotes if you
want to select a mail folder which contains any uppercase letters.  (For
most people, this means all folders.)  For example, to look at your old
mail, in the default folder MAIL,

    $ vmsgetmail --folder "MAIL"

while put everything on the screen (SYS$OUTPUT).

Filenames are not case sensitive.

I don't know if usernames are case sensitive or not.  The -u option is
not implemented anyway.

--append  -a         append to FILE (specified by --file)

  If the --file option is not specified, the output is "appended" to
  SYS$OUTPUT 

--count   -c         return the mail count only

  No messages will be read with this option.  If specified, all options
  except --version will be ignored.

--delete  -d         delete messages after reading

  The messages are marked for delete.  Note that vmsgetmail *alway* does
  a full close on the mail file, i.e., purge and reclaim operations are
  performed, so if you specify --delete the message will be gone.
  The default is to *NOT* delete.

--file    -f FILE    output to FILE

  Opens FILE and puts the message there.  If --append was specified,
  FILE is opened appropriately.

--folder  -F FOLDER  select mail from FOLDER

  Select FOLDER (e.g. --folder "NEWMAIL") for input.

--help    -h         display brief help message and exit

  This displays a brief synopsis of the command usage.  If this is
  specified, all options except --version will be ignored.

--newmail -n         select new messages

  Select new message in folder NEWMAIL.  This is the default.  Note that
  if you specifiy --fold "NEWMAIL", the program assumes --newmail as
  well.  You can (from within VMS Mail) move messages into the NEWMAIL
  folder so that the number in the folder is greater than your new mail
  count, but this like a rather silly thing to do, so the program
  doesn't allow for reading old messages in the NEWMAIL folder.

--user    -u USER    read mail for USER (not implemented!)

--version -v         return version information

  Returns a string indicating what version of vmsgetmail this is.  No
  other options are affected.

--verbose -V         talk to me

  Displays a running monologue of what is happening.  The output goes to
  stdout (SYS$OUTPUT), so unless you also specify --file, mail and
  diagnostics will be mixed together.