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/share/menu/default (if a user runs update-menus
, it
will add ~/.menu to the front of that list). For every menu entry line in each
file it checks if the corresponding package is installed (works on file bases
for old syntax menu entry files). The menu entries of all
"installed" packages are added together in one big buffer that is
kept in memory (exception: executable menu entry files are executed, and stdout
is placed in the buffer).
Once it's read all menu entry files, update-menus
starts all
executable scripts in /etc/menu-methods/, hands the scripts the previously
created buffer 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).
Note that as an aid to debugging, one can use
update-menus --stdout > /tmp/menu-stdin
and then view the file /tmp/menu-stdin to see exactly what update-menus handed the menu-methods on their stdin.
This may also be useful 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 run update-menus
--stdout
once, and then run
/etc/menu-methods/mymethod < /tmp/menu-stdin
(and, if that also takes too long, just try editing /tmp/menu-stdin, and removing 90% or so of all entries)
The files /etc/menu-methods/$wm 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:
See /usr/share/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 an `include' like statement in their
system.*rc files (like m4
or cpp
preprocessing), they cannot read the menudefs.hook file generated
by install-menu 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
$examplercfile and $rcfile defined in the
install-menu
config file, and $path either the
$rootprefix or ${HOME}/$userprefix, depending on
whether root or user executed the file.), and replace all occurrences of
``install-menu-defs'' with the $genmenu file it just generated.
As an example, consider the following:
examplercfile=system.foo-wm-example,
rcfile=system.foo-wm, genmenu=menudefs.hook and
rootprefix=/etc/X11/foo-wm. Now, if install-menu
gets run, it will first generate the file
/etc/X11/foo-wm/menudefs.hook. Next, it will line-by-line read
the file /etc/X11/foo-wm/system.foo-wm-example and copy it's
contents to /etc/X11/foo-wm/system.foo-wm, replacing every
occurrence of the string install-menu-defs by the contents of the
file /etc/X11/foo-wm/menudefs.hook.
To activate the file copying in this way, simply define the
$examplercfile and $rcfile variables in the
install-menu
configuration file (for example, see
/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:
./wm -v < /tmp/menu-stdin
(Use -v for verbose, -d for debugging, and you'll get loads of output!)
The menu-methods in /etc/menu-methods/* are basically made up of a
lot of ``tag=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/share/doc/menu/examples/*.
This must be just after the !include "menu.h" directive
so that menu.h
can use its own compat mode.
function q($s) = "\"" esc($s,"\\\"") "\"" supported x11 =" ShowEntry(" q(title()) ", " q($command) ")" text=" ShowEntry(" q(title()) ", " q(term()) ")" endsupported
For the variable substitution (and functions, not shown above), see the next paragraph. In the above example, you'll notice that for the menu entries that "need=text", the term() function is used. This is an user-supplied function that will run $command in a X terminal emulator. Also, as x11 is higher up in the supported list above 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 \.
c : dump children of menu. m : dump this menu's $submenutitles ( : dump $startmenu ) : dump $endmenu M : dump all $submenutitles of this menu and this menu's children.
The default is "c(m)". For olvwm, one needs: "(M)"
genmenu="/subdir/" replacewith($section," ","_") "/rc.menu"
(Substitution works just like in 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).
sh
. Example:
prerun="rm -rf " prefix() "/*" postrun="killall -USR1 fvwm2"
(Substitution works just like the supported stuff, see below).
Note: NOT just like prerun etc: prerun etc start a command with /bin/sh, also_run doesn't exec any other command, just tells install-menu to also load another binary, and generate the output.
install-menus
. This command used to
be needed to get around limitations due to compatibility stuff. But that
compatibility with pre menu-1 stuff has been dropped, and isn't needed any
more.
Example:
command="cat > /tmp/menu-stdin"
Example:
hotkeyexclude="q" $section
You can add another field to the menu items, with whatever name you like, let's say it's called priority. Then add this line to /etc/menu-methods/*: sort=ifelse($priority, $priority, "9") This has the result of sorting things so items with a low priority sort to the top, and items with no priority default to priority 9 and sort to the bottom. (Note that it compares the strings alphabetically, not numerically.)
The hints actually work in a rather strange way: when hint_optimize=true then all $section elements are added to the specified $hints variable, and the order (/Apps/Editors or /Editors/Apps) of the resulting hints is completely ignored. Then, the hints for each menu entry are handed to the optimization routine, that will calculate a reasonable tree for those hints. That tree must comply with the following:
When a user looks for a program "Program" with, say, hints "Good,Bulky,Heaven", then, while walking through the tree, it should at every node visited be clear for the user what submenu to select (or the menu should have "Program" directly in it). So, the toplevel menu may look like
Good Hell Microsoft
because then a searcher for a menu entry with hints "Good,Bulky,Heaven" will know to select the submenu "Good". The toplevel menu may not look like
Good Hell Heaven
as now it isn't clear whether to visit the Good or the Heaven submenu.
That rule allows usually for many different trees, and the task of the optimization procedure is to select, in a finite amount of time, the tree that best matches the user's desire about the optimum number of menu entries.
Debian Menu System
version 1.4, 22 March 2005joostje@debian.org
joeyh@debian.org
schwarz@debian.org
ballombe@debian.org