NAME

       gspl-pmenu - prompt user for selection from list

SYNOPSIS

       gspl-pmenu [ -h header ] [ -d delim ] [ -s start ] [ -f file ] [ -N num ] [ -F ] [ -n ] [ -m ]

DESCRIPTION

       gspl-pmenu is a simple curses-based program to select one (or more) of a list of options from within a
       shell script.

       The options are supplied on standard input, typically in the form:

        item1<tab>Description1
        item2<tab>Description2

       in multiple columns if possible, with one of the items (often the first) highlighted and the user is
       invited to move the highlight to a selected item if appropriate using the cursor keys and then press
       ENTER.

       The selected row is then output on standard output.

       When the options are displayed on the screen, the cursor keys, together with h, l, k and <j> may be used
       to move left, right, up and down respectively. The numeric keypad in numeric mode may also be used.

       If available, Next page, Previous page or N and P may be used to select the next column or screenful. Any
       other character may be used to select the next row starting with that character.

       When the correct entry has been selected, press ENTER to select it. Alternatively press q to quit with no
       output.

       The behaviour of gspl-pmenu may be modified by means of various options.

OPTIONS

       -h text Display  a  heading  to be centred at the top of the screen. The heading may consist of more than
               one line, each of which is centred separately. When gspl-pmenu is invoked  from  the  shell,  the
               heading should be enclosed in quotes.

               As  an  alternative,  the header may be provided in the standard input. To signify this, the text
               should be a single = sign thus:

                -h =

               The standard input will be read up to  the  first  blank  line  to  constitute  the  header,  and
               thereafter the selection rows.

       -d char Use the specified char as a delimiter rather than tab.

       -s num  Initialise the display to select the given item rather than the first on entry.

       -f file Take input from the specified file rather than standard input.

       -N num  Enables multiple selection menus to be provided for in one file. The standard input is read up to
               the  first  line  consisting  of  the  given  number  (possibly  negative)  and a colon. Input is
               terminated by a blank line. Thus the input file might look like:

                1:
                optiona1       description1
                optiona2       description2
                options3       description3

                2:
                optionb1       description4
                optionb2       description5
                optionb3       description6

               With the appropriate set of options and descriptions selected by

                -N 1

               or

                -N 2

               If headers are to be supplied in the file using "-h =", then these should follow the numbers with
               a blank line, thus:

                1:
                Header for first group
                of selections

                optiona1       description1
                optiona2       description2
                options3       description3

                2:
                Header for second group

                optionb1       description4
                optionb2       description5
                optionb3       description6

       -F      Just return the first field of the selection "the option" on exit, not the whole line.

       -n      Return the number (starting at 1) of the row selected on exit, rather than the text of the line.

       -m      Enable multi-selection mode. In this mode several lines may be selected, by moving to  each  line
               and  pressing  space.  Pressing  space again deselects the line. A plus sign appears against each
               choice to indicate selection.

               When all have been selected, press q to quit.

               The ENTER key behaves slightly differently. If the last action  was  to  select  or  deselect  an
               entry,  then  the  program exits as if q had been pressed. If the last character was not a space,
               then the current line is selected or deselected.

   Help files
       Help files may be provided for each item in a list by providing text files in the  directory  from  which
       gspl-pmenu is run with names:

        item1.menuhelp
        item2/Menuhelp

       where "item1" etc are the first field in each choice.

       To provide a "catch all" for items without help files, a help file named

        Menu-summary

       may be provided.

COPYRIGHT

       Copyright  (c) 2009 Free Software Foundation, Inc.  This is free software. You may redistribute copies of
       it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.  There is NO
       WARRANTY, to the extent permitted by law.

AUTHOR

       John M Collins, Xi Software Ltd.

GNUspool Release 1                                 2010-02-01                                      GSPL-PMENU(1)