Provided by: pdmenu_1.3.1_i386 bug

NAME

       pdmenurc - menu definitions file for pdmenu

SYNOPSIS

       /etc/pdmenurc

       ~/.pdmenurc

DESCRIPTION

       The  pdmenurc  file  defines  menus for pdmenu(1) to display. Each menu
       consists of one or more menu entries.  The first menu to appear in  the
       file  is  displayed  by  pdmenu(1) when it starts up, and can have menu
       entries that call up submenus.

EXAMPLES

       Here is a sample pdmenurc file:

        #Set a pleasing color scheme.
        color:desktop:blue:blue
        color:title:blue:white
        color:base:blue:white

        #this is a comment
        menu:main:Main Menu:Things to do at foobar
             show:_Games..::games
             exec:_Mail::pine
             exec:_News::slrn -C
             exec:_WWW::lynx
             exec:_Irc::irc
             exec:_Directory _Listing:display:ls -l
             exec:_Who's online?:truncate:w
             exec:_Finger:edit,truncate:finger ~finger who?:~
             nop
             exit:E_xit

        menu:games:Games:Some text-based games
            exec:_Tetris for Terminals::/usr/games/tt
            exec:_Adventure:pause:/usr/games/adventure
            exec:_Zork:pause:/usr/games/zork
            nop
            exit:_Back to main menu..

       This will display a menu, with a submenu for games.

FORMAT

       pdmenu(1) doesn't care how the pdmenurc is indented; all whitespace  is
       ignored.   However,  each command must be on its own line. The commands
       are grouped into two classes: those that  appear  only  in  menus,  and
       those that can appear anywhere in the file.

   COMMANDS THAT MAY BE USED ANYWHERE
       These  commands  may  appear in a menu, or outside of a menu. They take
       effect as soon as pdmenu(1) sees them.

       menu   This starts a menu. All items between this menu command and  the
              next  will  comprise  one  menu.  If a menu with the same id has
              already been defined earlier, then all items between  this  menu
              command and the next will be added to the menu.  The syntax is:

              menu:menuid:title[:helptext]

              menuid The id of the menu (each menu must have a unique id).

              title  The title of the menu.

              helptext
                     Text to be displayed at the bottom of the screen when the
                     menu is active.

       title  This overrides the default title at the top of the  screen.  The
              syntax is:

              title:text

       color  This  changes  the  color of a part of the display.  Later color
              commands override earlier color commands that would  affect  the
              same part of the display. The syntax is:

              color:screenpart:foreground[:background]

              screenpart
                     The  area of the screen which takes on the selected color
                     scheme.  Areas of the screen that can be set are:

                     desktop
                            The space over which the menus appear.

                     title  The line at the top of the screen.

                     base   The line at the bottom of the screen.

                     menu   The normal color of text in a menu.

                     selbar The selection bar in the menu,  when  over  normal
                            text.

                     shadow The shadow of a window

                     menuhot
                            The color of text in a menu that is a hotkey.

                     selbarhot
                            The  color  of  a hotkey when the selection bar is
                            over it.

                     unselmenu
                            The color of a menu window that is  not  currently
                            active.

              foreground
                     The color to use in the foreground. Valid colors are:
                      black           gray
                      red             brightred
                      green           brightgreen
                      brown           yellow
                      blue            brightblue
                      magenta         brightmagenta
                      cyan            brightcyan
                      lightgray       white

              background
                     The  color  to use in the background.  On most terminals,
                     the background color can only be one of the colors listed
                     in the first column above.

       read   This  causes  another  menu  definitions  file to be read in and
              replace the read command.  This is quite similar to #include  in
              a c program. The syntax is:

              read:rcfile

              Note  that  no  checking  is  done  to  prevent  recursive  read
              commands, and that such a recursive command can crash pdmenu.

       preproc
              This runs a command, and uses its output  as  a  pdmenurc  file,
              which  is  read in and replaces the preproc command. Typically a
              preprocessor such as m4 or cpp will be used. The syntax is:

              preproc:command [args]

              Note that no checking  is  done  to  prevent  recursive  preproc
              commands, and that such a recursive command can crash pdmenu.

   COMMANDS THAT MUST APPEAR INSIDE MENUS
       These commands must always appear within a menu. They are only executed
       if the user selects them from the menu.

       show   This displays a submenu. The syntax is:

              show:desc:flags:menuid

              menuid The id of the menu to show, corresponding to  the  menuid
                     given in the menu's definition.

              desc   The  description  of  the submenu to appear in the parent
                     window.

                     To place a hotkey in the description, put  a  '_'  before
                     the character you want to become the hotkey. It is a good
                     idea to differentiate submenus from commands  in  a  menu
                     by, for example, appending ".." to their descriptions.

              flags  Currently ignored.

       nop    This  does  nothing  but  place  a  blank  line in the menu. Nop
              commands may not appear as the first command in a menu.  Syntax:

              nop[:text]

              text   If this is present, it will appear in the menu where  the
                     nop  is.  Otherwise,  the nop in the menu will be a blank
                     line.

       helptext
              This changes the helptext of the currently displayed  menu.  The
              syntax is:

              helptext:desc:flags:help text

              desc   The text to appear on the menu.

              flags  Currently  the  only  available  flag is "command", which
                     makes the help text be read in from a command in the help
                     text  field,  instead  of  using the literal value of the
                     field. The first line the command outputs becomes the new
                     help text.

       exit   If  only  one  menu is on the screen when this is selected, then
              pdmenu(1) will quit. Otherwise, this will take the user back  to
              the  parent menu of the menu they are currently in. Selecting an
              exit command in a menu is equivalent to pressing 'q', unless you
              have ran pdmenu(1) with the -q switch. The syntax is:

              exit:desc

              desc   The description of the menu item.

                     To  place  a  hotkey in the description, put a '_' before
                     the character you want to become the hotkey.

       group  This creates a menu entry that can run multiple commands at  the
              same  time. After the group command, list the commands that make
              up the group.  Close the group with the endgroup  command.  When
              the  group  is selected from the menu, each command in the group
              will be run, in turn. Note that if a  group  caintains  an  exit
              command,  processing  will  stop  there  even  if there are more
              commands in the group. Group commands may  not  be  nested.  The
              syntax is:

              group:desc

              desc   The description of the menu item.

                     To  place  a  hotkey in the description, put a '_' before
                     the character you want to become the hotkey.

       endgroup
              This closes a group command. Every command between  the  opening
              group command and the endgroup comprises a group of commands.

       exec   This runs a command. The syntax is:

              exec:desc:flags:command

              command
                     The actual command to run when this item is selected.

                     Normally,  pdmenu(1)  passes the command to system(3) for
                     exacution.  However, if the first token of the command is
                     "exec",  then  the  command is executed directly with the
                     execvp(3) system call.  As such, the pdmenu(1) process is
                     wholly replaced by the command.

              desc   The description of the command that appears in the menu.

                     To  place  a  hotkey in the description, put a '_' before
                     the character you want to become the hotkey.

              flags  How to run this command, and what to do with its  output.
                     Any  number  of  the following flags can be specified, in
                     any  order,   separated   by   commas.    (for   example,
                     "display,edit")

                     Some  of  the flags conflict with each over, for example,
                     'display' and 'pause' cannot both be  used  at  the  same
                     time.  If  conflicting  flags  are specified, Pdmenu will
                     just pick one of them and use it.

                     Note that to maintain  backward  compatability  with  old
                     versions   of   Pdmenu,   the   flags  can  be  formatted
                     differently: as a sequence of characters, each  character
                     a  flag  and  corrisponding to the first character of the
                     long flag name, and nothing  separating  the  characters.
                     However,  this format is obsolete and hard to understand,
                     and should no longer be used.

                     noclear
                            By default the screen is cleared and the  terminal
                            is reset to normal before pdmenu(1) runs a command
                            from the menu, and after the  command  exits,  the
                            screen is redrawn. If this flag is set, the screen
                            is not cleared or redrawn. Use it if  you  have  a
                            command  on  the  menu  that  does not produce any
                            output to the screen. (Conflicts with: 'pause')

                     pause  Pause after the command exits.  Use  this  if  you
                            need  to see the output of the command. (Conflicts
                            with:    'noclear',     'display',     'truncate',
                            'makemenu', and 'setenv')

                     display
                            Display  the output of the command in a window. If
                            this flag is set, the 'pause'  flag  is  disabled,
                            and  the  'noclear' flag is automatically set.  If
                            the command outputs lines that are too long,  they
                            will  be  wrapped  inside  the  window. (Conflicts
                            with: 'pause', 'truncate', 'makemenu', 'setenv')

                     truncate
                            Like 'display', except the output of  the  command
                            is  truncated  to  fit in the window, not wrapped.
                            (Conflicts with: 'pause', 'display',  'mmakemenu',
                            'setenv')

                     edit   Edit the command interactively.

                            When  this  flag  is set, the command to be run is
                            scanned   for   any    tags    of    the    format
                            ~title:default~.  For  each  that is found, a text
                            entry window is displayed, with the title equal to
                            the  contents  of the title field, and the default
                            text equal to the contents of the default field.

                            To use the '~' or ':' characters  in  the  command
                            without having them interpreted as tag delimiters,
                            escape them with a '\' character.  (Ie,  '\~'  and
                            '\:')

                            Security  warning!  Any exec command that uses the
                            'edit' flag will be a security hole. The user need
                            only  to enter text with a ';' in it, and they can
                            run an arbitrary command after the semicolon!

                            There is no fix for this security problem at  this
                            time.  If  the  user  running  pdmenu(1)  is not a
                            trusted user (if they are a guest user,  say),  do
                            not  allow  them  access to any exec commands that
                            have the 'edit' flag set.

                     makemenu
                            This flag lets you generate menus on  the  fly  as
                            pdmenu(1)  is  running.  It runs the command, then
                            processes the output of the command as if it  were
                            a pdmenurc file.

                            Here  is  a  sample use of this flag. It creates a
                            menu of people who are logged  on,  and  lets  you
                            talk  to  one of them. Notice the use of remove to
                            clear the menu after we use it.

                              group:_Talk
                                exec::makemenu: \
                                  echo "menu:talk:Talk"; \
                                  for u in `users`; do \
                                    echo "exec:$u::talk $u"; \
                                  done
                                show:::talk
                                remove:::talk
                              endgroup

                            (Conflicts with: 'display',  'truncate',  'pause',
                            'display', 'setenv')

                     setenv Set an environment variable.

                            This  flag  causes  pdmenu(1) to set a variable in
                            its own  environment.   pdmenu(1)  runs  the  exec
                            command,  and  looks  at the command's output. The
                            first line should be in the format
                                   VAR=value
                            Where VAR is the environment variable to set,  and
                            value is the new value for the variable.

                            For  example,  use  "echo  PWD=/tmp"  to  set  the
                            current  working  directory  to  /tmp.  (Conflicts
                            with:   'makemenu',   'display',  'truncate',  and
                            'pause')

       remove This removes a menu from Pdmenu's  list  of  menus.  You  should
              never attempt to remove a menu that is currently being displayed
              on screen. The syntax is:

              remove:desc:flags:menuid

              desc   The description of the command that appears in the menu.

                     To place a hotkey in the description, put  a  '_'  before
                     the character you want to become the hotkey.

              flags  Currently ignored.

              menuid The  id  of the menu to remove. If the menu wih id menuid
                     does not exist, no error is reported.

              This command is typically used after creating and  using  a  new
              menu via the
               'makemenu'  flag  to  exec,  to remove a menu that is no longer
              needed.  For example, if you have the followng pdmenurc:

               menu:main:Main Menu
                 group:_Test
                   exec::makemenu: \
                     echo menu:sample:Dir; \
                     echo exec:_Directory:pause:ls
                   show:::sample
                 endgroup

              Each time the user selects "Test" from the Main Menu,  the  menu
              that  appears  has another Directory command on it. If you don't
              want this to happen, and you want only one Directory command  to
              be  on  the  menu,  add a command to remove the menu after it is
              used, like this:

               menu:main:Main Menu
                 group:_Test
                   exec::makemenu: \
                     echo menu:sample:Dir; \
                     echo exec:_Directory:pause:ls
                   show:::sample
                   remove:::sample
                 endgroup

NOTES

       If a line ends with '\', pdmenu(1) will read in the next line  as  part
       of the same logical line.

       If  you want the ':' character to appear in a field, you may escape out
       the ':' character by placing '\' before it. You don't need to  do  this
       if the field is the last field in a line.

FILES

       /etc/pdmenurc
              Default config file.
       ~/.pdmenurc
              If this exists, it overrides /etc/pdmenurc.

AUTHOR

       Joey Hess, <joey@kitenet.net>.

SEE ALSO

       pdmenu(1)