                                   menu.pl
                                 Perl Menus
                                 Version 3.2
                                June 1, 1995

                               Steven L. Kunz
                           Networked Applications
                  Iowa State University Computation Center
                            Iowa State University
                                 Ames,  Iowa
                  

Copyright (C) 1992-95  Iowa State University Computation Center
                       Ames, Iowa (USA)

menu.pl is free software; you can redistribute it and/or modify it under the 
terms of the GNU General Public License as published by the Free Software 
Foundation; either version 1, or (at your option) any later version.  

menu.pl is distributed in the hope that it will be useful, but WITHOUT ANY 
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more 
details.  

You should have received a copy of the GNU General Public License along with
menu.pl; see the file COPYING.  If not, write to: 
  
  The Free Software Foundation
  675 Mass Ave
  Cambridge, MA 02139, USA 

Distribution Contents:
----------------------

This is "menu.pl" - a set of perl routines that will perform full screen
menu functions using "curseperl".  What you should have after unpacking 
this package is the following:

  ARTISTIC       Artistic License

  COPYING        GNU Public License

  README         (this file)

  RELEASE_NOTES  Differences between this version and previous versions.

  MENU_DOC       A user's guide to the menu.pl routines.

  MENU_DOC       A user's guide to the menuutil.pl routines.

  TO_DO          List of things on my "to do" sheet.

  demo           A simple menu demo showing all several types of menu
                 selection capabilities (simple single-page, simple
                 multiple-page, radio-button, and multiple-selection).

  demo_getstr    A simple menu demo using the "menu_getstr" routine.

  demo_template  A demo using the "menu_load_template" and
                 "menu_display_template" routines.

  demo_top       A simple menu demo with "top" menus.

  demo_util      A simple demo of the routines in "menuutil.pl".

  ezpasswd       A more involved demo showing how menu_getstr, menuutil.pl,
                 and templates can be used to display full-screen formatted
                 entries from a BSD-style /etc/password file.

  ezreg          A more involved demo showing how menu template routines 
                 can be used in a full-screen user registration panel that
                 a multiple required fields.

  ezview         A more involved demo showing how menus can be used to call
                 routines, select files, etc.

  menu.pl        The perl menu subroutines in a package (usually placed 
                 somewhere like /usr/local/lib/perl/menu.pl)

  menuutil.pl    Some curses subroutines useful in constructing curseperl
                 transactions which use "menu.pl".  These are purely optional
                 and are not needed for using perl menus ("menu.pl").

  paint_text     A sample file used by "demo" to display bottom-titles
                 loaded from a file.

  template_data  A sample full-screen input template used by "demo_template"
                 to input name/address/phone data records.

  template_ezp   The display template used by ezpasswd.

  template_reg   The display template used by ezreg.

  ultpatch       Patches I had to apply to the bsdcurses.mus file to make 
                 it work on an ULTRIX (BSD based) system.

Installation:
-------------

  1) If you are using Perl version 4, you need to have "curseperl".
     If you are using Perl version 5, proceed to step 2.

     If you don't have curseperl working and installed somewhere, go into
     your perl.4.36 distribution (in the "usub" directory) and construct it
     following the instructions there.  Be forewarned that when I put it 
     together it didn't work on my ULTRIX 4.2a system - I had to install some
     patches I got off comp.lang.perl (posted by drw@nevanlinna.mit.edu)
     and some changes I had to add myself.  The file "ultpatch" is the
     diffs between what I run and what is distributed with perl.  Patch
     your original bsdcurses.mus with this if you are having trouble
     getting curseperl to work with ULTRIX.  These patches mainly involve
     commenting out routine calls absent in the ULTRIX curses package.

     Install your "curseperl" in the same location as your normal "perl"
     binary.

     You may need to modify the first line of the demo scripts ("demo",
     "demo_top" "demo_getstr", "demo_template", "demo_util", and "ezview")
     to point to where your "curseperl" is installed.  They are distributed
     assuming curseperl lives in "/usr/local/bin".

  2) If you are using Perl version 5, you need to have William Setzer's
     "Curses" extension built into Perl5.  This package is available via
     anonymous FTP at:

       ftp://ftp.ncsu.edu/pub/math/wsetzer/Curses-a8.tar.gz

     You will need to modify the first line of the demo scripts ("demo",
     "demo_top" "demo_getstr", "demo_template", "demo_util", and "ezview")
     to point to where your "perl5" is installed.  They are distributed
     assuming perl4 "curseperl" is being used.  Also, you will need to 
     uncomment the lines at the beginning of each demo script to set the
     "$Curses::OldCurses = 1;" flag (so lookups to routines like "wgetch"
     begin to be resolved) and "use" the Curses package.

  3) If the demo script fails with the following message:

        Undefined subroutine "main'getcap" called at ./menu.pl line ...

     If you are using Perl5 with the Curses extension:
       - Edit the menu.pl and scan for "getcap".  You will find a section
         of commented code that indicates '# PERL5 ONLY -- Uncomment these
         statements if you DON'T have "getcap()"'.  Uncomment the statements
         and try again.  It should work.

     If you are using Perl4 (curseperl):
       - Your system may use "tigetstr" instead of "getcap".  Edit the
         menu.pl file, comment the "getcap" lines, uncomment the "tigetstr"
         lines, and try again.
       _ If you don't have "tigetstr" or "getcap", you will have to hardcode
         the values needed (bad, because they are terminal specific) or
         find out how your system retrieves termcap or terminfo capabilities
         (and how you get that info via Perl).

  4) Put "menu.pl" with the rest of your perl packages (usually in something
     like "/usr/local/lib/perl").  The demo programs will work by just leaving
     a copy of "menu.pl" in the same directory as the demo scripts.

  5) Note that if you move the demo programs into a public area (and out of
     the distribution library), you should change the 'require "./menu.pl";'
     statements in all the demos to 'require "menu.pl";' (after moving the
     menu.pl package as outlined in the previous step).

---
Steven L. Kunz
Networked Applications
Iowa State University Computation Center, Iowa State University, Ames  IA
INET: skunz@iastate.edu
