Provided by: pdmenu_1.3.4build1_amd64 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)

pdmenu                                            April 05 2018                                      PDMENURC(5)