PDMENURC(5) File formats PDMENURC(5)NAMEpdmenurc - 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.
FORMATpdmenu(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 com‐
mands, 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 com‐
mands, 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 com‐
mands 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 com‐
mands 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, "dis‐
play,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 differ‐
ently: 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 out‐
put 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', 'make‐
menu', 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 com‐
mand, 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 cur‐
rent 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
/usr/local/etc/pdmenurc
Default config file.
~/.pdmenurc
If this exists, it overrides /usr/local/etc/pdmenurc.
AUTHOR
Joey Hess, <joey@kitenet.net>.
SEE ALSOpdmenu(1)pdmenu February 19 2016 PDMENURC(5)
