Random changes.

2 files changed, 306 insertions, 128 deletions

diff --git a/doc/pdmenu.man b/doc/pdmenu.man
index db9b5ac..eda4e2e 100644
--- a/doc/pdmenu.man
+++ b/doc/pdmenu.man
@@ -1,12 +1,12 @@
 .\" -*- nroff -*-
-.TH PDMENU 1 "February 28 1997" "0.6.3" "Commands"
+.TH PDMENU 1 "September 30 1999" "1.2.48" "Commands"
 .SH NAME
 pdmenu \- simple full screen menu program
 .SH SYNOPSIS
-.B pdmenu [\-h] [\-c] [\-n] [\fImenufile\fP ...]
+.B pdmenu [\fIoptions\fP] [\fImenufile\fP ...]
 .SH DESCRIPTION
 .I pdmenu 
-is a simple menu program for Linux that displays a menu from which the 
+is a simple menu program that displays a menu from which the 
 user can pick programs to run. Submenus are supported.
 .PP
 When you run 
@@ -15,7 +15,9 @@ When you run
 keys to move to the program you want to run, and press Enter to run the
 program. When the program ends, you will be returned to the menu.
 .PP
-If you are running pdmenu at the linux console, and gpm is running, you can
+If you are running 
+.I pdmenu
+at the linux console, and gpm is running, you can
 move the mouse and click to navigate through the menus.
 .PP
 Some menu items are actually submenus, and will take you to another menu.
@@ -43,7 +45,10 @@ if used on the first menu. Does not
 work in the text edit windows. (This will not work if there is also a hotkey 
 set up for \*(L'q\*(R', the hotkey takes precedence.)
 .IP "ESC"
-Close the currently active window, and return to the perious window.
+Close the currently active window, and return to the previous window, or
+exit 
+.I pdmenu
+if used on the first menu.
 .IP "[ctrl-c]"
 Exit 
 .I pdmenu
@@ -65,6 +70,16 @@ Use color. By default,
 .I pdmenu 
 will display in black and white mode. If your 
 terminal supports color, use this switch.
+.IP "-u, --unpark"
+"Unparks" the cursor from the bottom of the screen. When this option is
+selected, the cursor moves to be on the line of the menu that is currently
+selected. This makes 
+.I pdmenu
+more useable with speech synthesis systems that
+need to know what line is the current line on the screen.
+.IP "-mmenuid, --menu=menuid"
+Instead of displaying the first menu from the menufile, select the menu
+with the id "menuid" and display it.
 .IP "-q, --quit"
 By default, at the opening menu, 'q' will exit \fIpdmenu\fP.
 If the \-q switch is
@@ -73,14 +88,34 @@ the user from ever exiting \fIpdmenu\fP.
 .SP
 This also disables control-c and the right mouse button from exiting
 \fIpdmenu\fP.
+.IP "-r, --retro"
+This makes
+.I pdmenu
+use an old style for displaying menus. Menus in the background don't change
+color, or lose their hotkeys. Note that this will also be a little bit
+faster than the default on slow terminals and the like.
+.IP "-l, --lowbit"
+By default, 
+.I pdmenu
+will use nice high bit line drawing characters if it
+thinks your terminal is capable. Sometimes it gets this wrong and you get
+borders that look all messed up. Then you should use this --lowbit switch to
+force it to use low bit line draing characters.
+.IP "-n, --numeric"
+Disables the use of the keys 2 and 8 for moving up and down. This is useful
+if you want to use numbered hotkeys.
 .IP "menufile ..."
 Specify a menu definition file or files to use. If you specify multiple
-files, they will all be loaded in together.
+files, they will all be loaded in together. By default, the first menu in
+the first menufile will be displayed when 
+.I pdmenu
+starts, but this can be overridden by the --menu= option.
+If menufile is "-", pdmenu will read standard input as a menu file.
 .SH NOTES
 To use the mouse to cut and paste as usual, hold down on the shift key when
 you use the mouse.
 .SH FILES
-.I /etc/pdmenurc
+.I /usr/local/etc/pdmenurc
 .RS
 Default config file. See
 .BR pdmenurc (5)
@@ -88,7 +123,7 @@ for details.
 .RE
 .I ~/.pdmenurc
 .RS
-If this exists, it overrides /etc/pdmenurc. See
+If this exists, it overrides /usr/local/etc/pdmenurc. See
 .BR pdmenurc (5)
 for details.
 .SH ENVIRONMENT
@@ -99,8 +134,10 @@ to use color by default.
 .SH DISTRIBUTION
 Redistribution is subject to the GNU public license.
 .SH BUGS
-No important bugs are known at this time.
+See the file BUGS that came with 
+.I pdmenu
+for the current buglist.
 .SH AUTHOR 
-Joey Hess, <joey@kite.ml.org>.
+Joey Hess, <joey@kitenet.net>.
 .SH "SEE ALSO"
 .BR pdmenurc (5)
diff --git a/doc/pdmenurc.man b/doc/pdmenurc.man
index 4b732b3..f8ca174 100644
--- a/doc/pdmenurc.man
+++ b/doc/pdmenurc.man
@@ -1,5 +1,5 @@
 .\" -*- nroff -*-
-.TH PDMENURC 5 "February 28 1997" "pdmenu" "File formats"
+.TH PDMENURC 5 "September 30 1999" "pdmenu" "File formats"
 .SH NAME
 pdmenurc \- menu definitions file for pdmenu
 .SH SYNOPSIS
@@ -28,15 +28,16 @@ Here is a sample pdmenurc file:
       exec:_News::slrn -C
       exec:_WWW::lynx
       exec:_Irc::irc
-      exec:_Directory _Listing:dn:ls -l
-      exec:_Who's online?:d:w
-      exec:_Finger:ed:finger ~finger who?:~
+      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::/usr/games/adventure
-     exec:_Zork::/usr/games/zork
+     exec:_Adventure:pause:/usr/games/adventure
+     exec:_Zork:pause:/usr/games/zork
      nop
      exit:_Back to main menu..
 
@@ -44,33 +45,27 @@ This will display a menu, with a submenu for games.
 .SH FORMAT
 .BR pdmenu (1)
 doesn't care how the pdmenurc is indented; all whitespace is ignored.
-However, each command must be on its own line.
-.TP 
-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:
-.RS
-.PP
-\fInop[:text]\fR
-.TP
-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.
-.RE
+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.
+.SS COMMANDS THAT MAY BE USED ANYWHERE
+These commands may appear in a menu, or outside of a menu. They take effect
+as soon as 
+.BR pdmenu (1)
+sees them.
 .TP
 menu
 This starts a menu. All items between this menu command and the next will
-comprise one menu. If a menu by the same name has already been defined
+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. It is illegal to have a menu without any commands in it.
+to the menu.
 The syntax is:
 .RS
 .PP
-\fImenu:menuname:title[:helptext]\fR
+\fImenu:menuid:title[:helptext]\fR
 .TP
-menuname
-The name of the menu (each menu must have a unique name).
+menuid
+The id of the menu (each menu must have a unique id).
 .TP
 title
 The title of the menu.
@@ -79,14 +74,103 @@ helptext
 Text to be displayed at the bottom of the screen when the menu is active.
 .RE
 .TP
+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:
+.RS
+.PP
+\fIcolor:screenpart:foreground[:background]\fR
+.TP
+screenpart
+The area of the screen which takes on the selected color scheme.
+Areas of the screen that can be set are:
+.RS
+.TP
+desktop
+The space over which the menus appear.
+.TP
+title
+The line at the top of the screen.
+.TP
+base
+The line at the bottom of the screen.
+.TP
+menu
+The normal color of text in a menu.
+.TP
+selbar
+The selection bar in the menu, when over normal text.
+.TP
+shadow
+The shadow of a window
+.TP
+menuhot
+The color of text in a menu that is a hotkey.
+.TP
+selbarhot
+The color of a hotkey when the selection bar is over it.
+.TP
+unselmenu
+The color of a menu window that is not currently active.
+.RE
+.TP
+foreground
+The color to use in the foreground. Valid colors are:
+.RS
+ black           gray
+ red             brightred
+ green           brightgreen
+ brown           yellow
+ blue            brightblue
+ magenta         brightmagenta
+ cyan            brightcyan
+ lightgray       white
+.RE
+.PP
+.TP
+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.
+.RE
+.TP
+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:
+.RS
+.PP
+\fIread:rcfile\fR
+.PP
+Note that no checking is done to prevent recursive read commands, and that
+such a recursive command can crash pdmenu.
+.RE
+.TP
+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:
+.RS
+.PP
+\fIpreproc:command [args]\fR
+.PP
+Note that no checking is done to prevent recursive preproc commands, and
+that
+such a recursive command can crash pdmenu.
+.RE
+.SS 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.
+.TP
 show
 This displays a submenu. The syntax is:
 .RS
 .PP
-\fIshow:desc:flags:menuname\fR
+\fIshow:desc:flags:menuid\fR
 .TP
-menuname
-The name of the menu to show, corresponding to the menuname given in the 
+menuid
+The id of the menu to show, corresponding to the menuid given in the 
 menu's definition.
 .TP
 desc
@@ -103,6 +187,19 @@ Currently ignored.
 .IP
 .RE
 .TP
+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:
+.RS
+.PP
+\fInop[:text]\fR
+.TP
+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.
+.RE
+.TP
 exit
 If only one menu is on the screen when this is selected, then 
 .BR pdmenu (1)
@@ -124,6 +221,31 @@ a '_' before the character you want to become the hotkey.
 .RE
 .RE
 .TP
+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 \fIendgroup\fP 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:
+.RS
+.PP
+\fIgroup:desc\fR
+.TP
+desc
+The description of the menu item.
+.RS
+.PP
+To place a hotkey in the description, put
+a '_' before the character you want to become the hotkey.
+.RE
+.RE
+.TP
+endgroup
+This closes a \fIgroup\fP command. Every command between the opening group
+command and the endgroup comprises a group of commands.
+.TP
 exec
 This runs a command. The syntax is:
 .RS
@@ -143,26 +265,45 @@ you want to become the hotkey.
 .TP
 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.
+the following flags can be specified, in any order, separated by commas.
+(for example, "display,edit")
 .RS
+.PP
+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.
+.PP
+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.
 .TP
-n
+noclear
 By default the screen is cleared and the terminal is reset to normal before
 .BR pdmenu (1)
 runs a command from the menu, and after the command exits, the screen is 
-redrawn. If this 'n' flag is set, the screen is not cleared or
+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.
+output to the screen. (Conflicts with: 'pause')
 .TP
-p
+pause
 Pause after the command exits. Use this if you need to see the output of the
-command.
+command. (Conflicts with: 'noclear', 'display', 'truncate', 'makemenu',
+'setenv')
+.TP
+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')
 .TP
-d
-Display the output of the command in a window. If this flag is set, the 'p'
-flag is disabled, and the 'n' flag is automatically set.
+truncate
+Like 'display', except the output of the command is truncated to fit in the
+window, not wrapped.
+(Conflicts with: 'pause', 'display', 'mmakemenu', 'setenv')
 .TP
-e
+edit
 Edit the command interactively.
 .RS
 .PP
@@ -175,17 +316,42 @@ To use the '~' or ':' characters in the command without having them
 interpreted as tag delimiters, escape them with a '\e' character. 
 (Ie, '\e~' and '\e:')
 .PP
-\fISecurity warning!\fR Any exec command that uses the 'e' flag will be
+\fISecurity warning!\fR 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!
 .PP
 There is no fix for this security problem at this time. If the user running
 .BR 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 'e' flag set. 
+them access to any exec commands that have the 'edit' flag set. 
+.RE
+.TP
+makemenu
+This flag lets you generate menus on the fly as 
+.BR pdmenu (1)
+is running. It runs
+the command, then processes the output of the command as if it were a
+pdmenurc file.
+.RS
+.PP
+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 
+\fIremove\fP to clear the menu after we use it.
+.PP
+  group:_Talk
+    exec::makemenu: \\
+      echo "menu:talk:Talk"; \\
+      for u in `users`; do \\
+        echo "exec:$u::talk $u"; \\
+      done
+    show:::talk
+    remove:::talk
+  endgroup
+.PP
+(Conflicts with: 'display', 'truncate', 'pause', 'display', 'setenv')
 .RE
 .TP
-s
+setenv
 Set an environment variable.
 .RS
 .PP
@@ -202,103 +368,78 @@ Where VAR is the environment variable to set, and value is the new value
 for the variable. 
 .PP
 For example, use "echo PWD=/tmp" to set the current working
-directory to /tmp.
-.PP
-\fISecurity warning!\fR This flag could be a serious security hole. Use with 
-caution.
+directory to /tmp. (Conflicts with: 'makemenu', 'display', 'truncate',
+'pause')
 .RE
 .RE
 .RE
 .TP
-color
-This changes the color of a part of the display. Color commands are read in
-and executed when the menu file is loaded. Later color commands override earlier
-color commands that would affect the same part of the display. The syntax is:
+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:
 .RS
 .PP
-\fIcolor:screenpart:foreground[:background]\fR
-.TP
-screenpart
-The area of the screen which takes on the selected color scheme.
-Areas of the screen that can be set are:
-.RS
-.TP
-desktop
-The space over which the menus appear.
-.TP
-title
-The line at the top of the screen.
-.TP
-base
-The line at the bottom of the screen.
-.TP
-menu
-The normal color of text in a menu.
-.TP
-selbar
-The selection bar in the menu, when over normal text.
-.TP
-shadow
-The shadow of a window
-.TP
-menuhot
-The color of text in a menu that is a hotkey.
-.TP
-selbarhot
-The color of a hotkey when the selection bar is over it.
-.RE
-.TP
-foreground
-The color to use in the foreground. Valid colors are:
-.RS
- black           gray
- red             brightred
- green           brightgreen
- brown           yellow
- blue            brightblue
- magenta         brightmagenta
- cyan            brightcyan
- lightgray       white
-.RE
+\fIremove:desc:flags:menuid\fR
 .PP
 .TP
-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.
-.RE
-.TP
-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:
+desc
+The description of the command that appears in the menu.
 .RS
 .PP
-\fIread:rcfile\fR
-.PP
-Note that no checking is done to prevent recursive read commands, and that
-such a recursive command can crash pdmenu.
+To place a hotkey in the description, put a '_' before the character
+you want to become the hotkey.
 .RE
 .TP
-preproc
-This runs a command, and uses it's output as a rc file, which is read in and
-replaces the preproc command. Typically a preprocessor such as m4 or cpp
-will be used. The syntax is:
-.RS
+flags
+Currently ignored.
+.TP
+menuid
+The id of the menu to remove. If the menu wih id \fImenuid\fR does not exist,
+no error is reported.
 .PP
-\fIpreproc:command [args]\fR
+This command is typically used after creating and using a new menu via the 
+'makemenu' flag to \fIexec\fR, 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
+
+.SH NOTES
+If a line ends with '\\', 
+.BR pdmenu (1)
+will read in the next line as part of the same logical line.
 .PP
-Note that no checking is done to prevent recursive preproc commands, and that
-such a recursive command can crash pdmenu.
+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.
 .SH FILES
-.I /etc/pdmenurc
+.I /usr/local/etc/pdmenurc
 .RS
 Default config file.
 .RE
 .I ~/.pdmenurc
 .RS
-If this exists, it overrides /etc/pdmenurc.
+If this exists, it overrides /usr/local/etc/pdmenurc.
 .SH AUTHOR
-Joey Hess, <joey@kite.ml.org>.
+Joey Hess, <joey@kitenet.net>.
 .SH "SEE ALSO"
 .BR pdmenu (1)