Debian Menu System - chapter 5
The internals of the menu package


5.1 The update-menus program

On startup, update-menus checks the file /var/run/update-menus.pid and the pid in it. If there's an update-menus process with that pid it kills it. If /var/lib/dpkg/lock exists, it forks to background and returns control to dpkg. The background process checks the /var/lib/dpkg/lock file approx. every second until the file's gone.

After that, update-menus reads the menu-entry-files in the following directories: /etc/menu /usr/lib/menu /usr/lib/menu/default (if a user runs update-menus, it will add ~/.menu to the front of that list). For every file it checks if the corresponding package is installed. The menuentries of all "installed" menuentryfiles are added together in one big buffer kept in memory (exception: executable menuentryfiles are executed, and stdout is placed in the buffer).

Once it's read all menuentryfiles, update-menus starts all executable scripts in /etc/menu-methods/, hands the scripts the previously created puffer via stdin. (If update-menus is ran by a user, it will first try to run the scripts in ~/.menu-methods, and only if that directory doesn't exist, it will run the scripts in /etc/menu-methods).

For compatibility with older the older install-fvwmgenmenu, (and possibly other programmes that expect older syntax) update-menus will put the menuentry information in a "compat" format if the menu-method script doesn't start with "#!/usr/sbin/install-menu". This is rather annoying, as it doesn't allow one (me) to create a test script like

#!/bin/sh
cat > /tmp/menu-stdout
so that I can take a look at the output of update-menus. To overcome that, use the following script:
#!/usr/sbin/install-menu
compat="menu-1"
command="cat > /tmp/menu-stdin"
(this script also lives in /usr/doc/menu/examples/cat). Now why am I telling this? Because it may also be usefull for people writing /etc/menu-method/* scripts: Running update-menus every time you changed something in the script may be quite time-consuming. So, it's much easier to install the above script in /etc/menu-methods/, run update-menus once, and then run
  /etc/menu-methods/mymethod < /tmp/menu-stdin

5.2 The install-menu program

The files /etc/menu-methods/fvwm* are ``executable'' config files that start with the line
  #!/usr/sbin/install-menu
and thus start that program, handing it the configuration file for the specific window manager in the first command line argument. This configuration consists of:
  1. the compatibility mode ("menu-1").

  2. where the various files should be stored/read.

  3. what "needs" are supported, and what wrapper files should be used for each "type".

See /usr/doc/menu/examples/ of the menu package for more comments.

Options to install-menu:

  -v              be verbose
  -d              Produce loads of debugging output

Some window managers don't support m4 or cpp preprocessing, and cannot read the menudefs.hook file from their system.*rc config file. To still be able to use them, install-menu will copy the file $path$examplercfile/ to $path$rcfile/ (with $path, $examplercfile and $rcfile defined in the install-menu config file), and replace all occurences of ``install-menu-defs'' with the $genmenu file it just generated. Although this approach looks quite clumsy, it does allow for one $path/$examplercfile on the system. (The m4/cpp approach puts a "include(/etc/X11/*/menudefs.hook)" in the system.*rc file, so users will never load their menudefs.hook file).

To activate the file copying in this way, simply define the $examplercfile and $rcfile variables in the install-fvwmgenmenu configuration file (/etc/menu-methods/fvwm*), and make sure there is a $path/$examplercfile ($path being either $rootprefix, or $userprefix.)

If you are wringing a menu method, you can use the following to debug it somewhat easier:

  1. use the "cat" menu-method in /usr/doc/menu/examples/cat to create a list of menuentries in /tmp/menu-stdin (put it in ~/.menu-methods, and run update-menus), and then

  2. you can run just your menu-method with (if it's called wm):
      ./wm -v < /tmp/menu-stdin
    (Use -v for verbose, -d for debugging, and you'll get loads of output!)


5.3 The install-menu config script definitions

The menu-methods in /etc/menu-methods/* are basically made up of a lot of ``section=string'' definitions, explaining install-menu how to generate a system.$wmrc script. This way you can tune the look of generated system.$wmrc to your needs.

In the following, something like

  treewalk="c(m)"
means that the treewalk variable by default has the value "c(m)".

For examples of what these scripts can look like, see /usr/doc/menu/examples/*.

compat="menu-1"
Should always be "menu-1". Please, make this the first non-comment line in the script.

supported
endsupported
Between the supported and endsupported keywords you define what "needs" are supported by this window manager. So, the following is an example for a wm that supports both needs=x11 and needs=text:
  supported
    x11=" ShowEntry("title=\"" $title "\", command=\"" $command "\"")
    text=" ShowEntry("title=\"" $title "\", command=\""\
             "xterm -T " $title " -e " $command "\"")
  endsupported
For the variable substitution (and functions, not shown above), see the next paragraph. In the above example, you'll notice that for the menuentries that "need=text", an xterm is spawned for the command to run in. Also, as x11 is higher up in the supported list than text, a package that supplies both a "needs=x11" and a "needs=text" entry will have the needs=x11 entry installed, in favour of the needs=text entry. You can continue lines on the next line with a \, but do make sure you don't add any spaces after the \.

startmenu=""
endmenu=""
submenutitle=""
These define what to print for the beginning/end of a menu, and how to the print a menuentry that pops up another menuentry. They are subsituted the same way as the "supported" stuff is. (see next paragraph).

treewalk="c(m)"
This string defines in what order to dump the $startmenu, $endmenu, and $submenutitle (and its children). Each char in the string refers to:
    c  : dump children of menu.
    m  : dump this menu's $submenutitles
    (  : dump $startmenu
    )  : dump $endmenu
    M  : dump all $sumbmenutitles of this menu and this menu's children.
The default is "c(m)". For olvwm, one needs: "(M)"

genmenu=""
The menufile to generate (usually something like system."$wm"rc). The file itself may depend on the level or title that is currently being work on, like
    genmenu="/subdir/" replacewith($section," ","_") "/rc.menu"
(Substitution works just like the supported stuff, see above). Note that the files made this way are truncated upon opening, so if you have a genmenu like the example above, then your endmenu= will override the startmenu stuff (but you probably only need one of the two anyway).

rootsection="/Debian"
the prefix, every $section variable gets.

prerun=""
postrun=""
The commands to run before resp. after the actual generation of the menudefs.hook (genmenu) file. Commands will be executed by sh. Example:
  prerun="rm -rf " prefix() "/*"
  postrun="killall -USR1 fvwm2"
(Substitution works just like the supported stuff, see above).

preoutput="#Automatically generated file. Do not edit (see /usr/doc/menu/html)\n\n"
postoutput=""
Text to put at the beginning resp. end of the generated file ($genmenu).

command=""
A command to run instead of install-menus. This command will receive the menu entries install-menus would have received on stdin. This option is necessary, as there is otherwise (apart from replacing /usr/sbin/install-menus with a sh script) no way to write the "new-format" stdin to a file, for debugging or other purposes. (Just replacing the first line in the /etc/menu-methods script with #!/bin/bash will not work, as the script will get old-format input then.)

Example:

  command="cat > /tmp/menu-stdin"

hotkeyexclude=""
Keys not to use for hotkey generation. You can use the same variables and functions here as in for example the startmenu sections.

Example:

  hotkeyexclude="q" $section

hotkeycase="insensitive"
can be either "insensitive" or "sensitive". Determines whether the hotkeys can be of mixed case (fvwm2 reads the hotkeys case-insensitive, pdmenu case-sensitive). In case of the titles "Xa" and "xb", hotkey will generate "X" and "b", whereas sensitive would generate "X" and "x".

rcfile=""
If the window manager doesn't support an "include filename" or "read(filename)" statement in it's config file, you can rename the wm's config file to system."$wm"rc-menu, and insert a "install-menu-defs" line (without the quotes, or whitespace around it, and "install-menu-defs" must be the only thing on the line) in the system."$wm"rc-menu file. This will then get replaced by the $genmenu file that wasrcfile="" just created (see also $examplercfile).

examplercfile=""
if needed (see rcfile), this is the system.rc"$wm"-menu file. In that case, make rcfile=system.rc"$wm".

rootprefix=""
The prefix to use when running as root (applies to $genmenu, $rcfile, $examplercfile and other old cache files)

userprefix=""
see rootprefix, but when running as user.


5.4 Variables and functions in the install-menu scripts

The supported "needs" definitions and "startmenu=", "endmenu=" and "submenutitle=" are interpreted as follows:
String constants:
  Anything inside double quotes ("") is interpreted as a string, and
  is written verbatim to the output file.
  Stuff like \n, \t, ... will be substituted for their C expansions 
  (But not \0xx, currently).

Variables:
  Anything matching $[a-z,A-Z,_]* is interpreted as a variable, and
  the corresponding definition from the menuentry is substituted. So,
  for a menuentry.
  
  Special variables:
    The following variables are treated in a special way by install-menus,
    either because they are used for other purposes too, or because they
    are modified by install-menus (the ones marked with a "!" are modified
    by install-menus).
    
    needs:   used to determine whether the window manager supports this
             menuentry.
    command: If this is undefined, this menuentry is taken as defining
             a submenu. (this way you can specify icons of submenus).
    title!:  Used for sorting (see section).
             For submenuentries (those with empty command), this
	     is initialised to the last part of the section.
	     Please, keep the title short (two words at maximum).
	     The title is for people who already know what programme
	     they want to start. See "longtitle" and "description" below
	     for longer descriptions.
    sort:    used for sorting (see section).
    section!:Used to determine the section of the menuentry.
             The menuentries that have a empty $command, have their
	     $section changed to modify the current level.	     
             The menuentries that have a non-empty $command have their
	     $section modified to $section/$title, or $section/$sort:$title
	     if $sort is defined. The menuentries within one section
	     are sorted according to $section.
    hotkey!: Modified to reflect what install-menus thinks is the
             most suitable hotkey for this menuentry. The hotkey=
	     in the menuentry file is taken as a suggestion, that could
	     be overwritten if there is another entry with the same hotkey=.
	     To suggest two possible hotkeys for an entry use
	     hotkey="ab", with "a" being the most prefered hotkey.

  Preferred variables:
    The following aren't special for install-menus, but it's nice 
    (read: essential) to use the same variables for the same things.
    So, I'll suggest some here. If you want to invent new ones, please
    do so and mail them to me so that I can include them here.

    icon:    The location of the iconfile for this menuentry.
             If you don't have an iconfile, just leave out the icon=
	     in the menuentry.
    longtitle: For people that like descriptive titles (about one line)
             It is probably best to include this in your menuentries,
	     while the window-managers don't (by default) put it in the
	     menus. That way, people who want descriptive titles can
	     turn them on, but others don't need to use them.
    description:An even longer description (about 5 lines).
             For example, a description of the documentation in
	     the dwww generated html pages.

  Suggested variables:
    The following variables probably shouldn't appear often (or at
    all) in the menu files supplied with packages. They are mostly
    intended for use by local system managers. Nevertheless, it is
    adviced that all debian systems use the following variable names:    
    
    visable: Some apps add entries to utmp the utmp file, so that
             "who" and friends know they are running (this is
	     especially true for xterms etc). If $visable set
	     (to anything other than "" or "none"), xterms etc will
	     not write logging info to utmp. (may not work for
	     your window manager).
    geometry: For X apps, this will be the size of the (main) window
             that will be created (units in eighter chars or pixels,
	     depending on type of main window (xterm or graphic)).
	     If you as package maintainer want to use this, you should
	     probably think about setting this variable somewhere
	     in an Xresources file.
             

Functions:
  Anything matching [a-z,A-Z,_] is taken as a function (and an error
  is generated if the function doesn't exist). The arguments of the
  functions can be other functions, string contsants or variables.
  
  prefix()
     returns the current prefix dir: either $rootprefix, or
     $HOME/$userprefix, depending on who runs install-menu

  ifroot($rootarg, $userarg)
     if(getuid()==0) print $rootarg, else print $userarg

  print($arg)    
     Same as just $arg; if $arg is empty, generate an error.

  esc($arg1,$arg2)
     Print $arg1, but escape all occurences of characters in $arg2
     with a \. (thus, if arg1="hello", arg2="lo", print "he\l\l\o").

  escwith($arg1, $arg2, $arg3)
     Same as esc, but use $arg3 as escape sequence.

  escfirst($arg1, $arg2, $arg3)
     Same as escwith, but only escapes thirst occurence of $arg2.

  tolower($arg)
  toupper($arg)
     Returns the argument set in lowercases resp uppercases. 

  replacewith($s, $replace, $with)
     Search s for occurences of characters from string replace, and
     replace them by the corresponding character in $with.
     Example:
      replacewith_string("hello $world, %dir", "$% ", "123")
      returns:   "hello31world,32dir"

  ifempty($arg1, $arg2)
     If $arg1 is empty, print $arg2, otherwise print nothing.
     For compatibility, the string "none" is seen as empty.

  ifnempty($arg1, $arg2)     
     If $arg1 is not empty, print $arg2.
     For compatibility, the string "none" is seen as empty.

  ifelse($arg1,$arg2,$arg3)
     If $arg1 is non-empty, print $arg2, otherwise $arg3.
     For compatibility, the string "none" is seen as empty.

  ifeq($arg1, $arg2, $arg3)
     If ($arg1==$arg2) then print $arg3
  ifneq($arg1, $arg2, $arg3)
     If ($arg1!=$arg2) then print $arg3
  ifeqelse($arg1, $arg2, $arg3, $arg4)
     If ($arg1==$arg2) then print $arg3 else print $arg4

  cond_surr($arg1, $arg2, $arg3)
     If $arg1 is non-empty print $arg2$arg1$arg3, otherwise print nothing.
     For compatibilty, $arg1="none" is interpreted as empty.

  iffile($arg1, $arg2)
     If file $arg1 exists, and can be opened for reading by whoever
     started the current process, return $arg2, otherwise return nothing.


  ifelsefile($arg1, $arg2,$arg3)
     If file $arg1 exists, and can be opened for reading by whoever
     started the current process, return $arg2, otherwise return $arg3.

  catfile($arg1)
     Return the contents of file $arg1.
  
  parent($arg)
     for arg a "directory", return parent directory:
     parent("/Debian/Apps/Editors") = "/Debian/Apps".

  basename($arg)
     return the last part of the parent direcotry:
     basename("/Debian/Apps/Editors") = "Apps".


  entrycount()
     the number of entries in this menu.
 
  entryindex()
     returns relative position of this entry

  
  add($arg1,$arg2)
  sub($arg1,$arg2)
  mult($arg1,$arg2)
  div($arg1,$arg2)
     returns the sum, difference, product or quotient of $arg1 and
     $arg2. Note that the arguments are strings, that are converted
     to integers.
     example: mult("24", entryindex())
     
     
String constants, variables and functions can be concatenated 
by placing them after each other with a space inbetween, like

"hello" $ifelse($comma, $comma, "sorry" $period " no comma def") " world"

Debian Menu System - Copyright ©1997 Joost Witteveen, Joey Hess, Christian Schwarz.
Contents; abstract; back.
version 1.3, 20 October 1998
Joost Witteveen joostje@debian.org
Joey Hess joey@kite.ml.org
Christian Schwarz schwarz@debian.org