Debian Menu System
Chapter 1 Introduction

Before the advent of update-menus, when the sysadmin installed a package onto a debian system, they would need to edit various window manager config files to make the new program show up on, for example, fvwm's menus. The menus could easily become out of sync with what programs were actually available, with some menu items that didn't work, and other programs that lacked a menu entry. update-menus and debian's menu package aim to solve this problem.

update-menus automatically generates menus of installed programs for window managers and other menu programs. It should be run whenever a menu file or menu-method file is changed. update-menus will be ran automatically when debian packages that contain menu files are installed or removed from the system.

One problem we ran into with menu-1.x (and before) was that the number of entries in any submenu vary wildly: on my system there are only two entries in /Apps/Editors, while I'm sure that other people have more like 20 entries there. Many people complaind about the fullness of certain submenus, citing scientific studies or personal experience to explain why overfull or underfull submenus are a bad thing. To overcome this, menu-2.0 now can optimize the tree itself, possibly subdividing for example the /Apps/Editors tree in, say Editors/Beginner, Editors/Experienced, or whatever, if there are many entries in that submenu, or maybe even totally removing /Apps/Editors on systems where there are few editors installed. To be able to do this, menu follows the information supplied to it in the `hints' variables (see paragraph below, or the hints chapter).

Each package that needs to add an entry to the menu tree, includes a menu file /usr/lib/menu/package-name. In this file, it will have one line per menu entry, like this (copied from /usr/lib/menu/xbase):

        ?package(xbase):command="/usr/bin/X11/xedit" needs="X11" \
                     section="Apps/Editors" title="Xedit" \
                     hints="Beginner,Small"

This describes the type of interface Xedit needs (X11), the menu section the menu entry should be in, the menu text, and the command that should be executued. Also, it tells menu that, if /Apps/Editors is overfull, it could put Xedit in a Apps/Editors/Beginner or Apps/Editors/Small subsection.

Whenever root runs update-menus, it will check all menu files in /etc/menu and /usr/lib/menu, and run the installation scripts that display managers like fvwm2 should provide in /etc/menu-methods.

The menu package itself provides a set of default menu files, for people to get the idea, and to speed up things a bit. (These files should be incorporated into the package.)

Note, that substantial and incompatible changes took place with the menu-1.0 release, while substantial features were added by the release of menu-2.0. This document describes menu-2.0. Menu-2.0 now doesn't accept the menu-methods written for menu-0.x, but for most window managers that still have those old menu-methods, I have put new style menu-methods in /usr/doc/menu/examples. Everything written for menu-1.0 will work with menu-2.0.

Most notable changes between menu-0.x and menu-1.x are listed in the file README.changes in the menu package, the features added by menu-2.0 can be summerised here: hints, and the menu-2 compat mode. (where lines are finished by a ';' instead of a newline).