This "package" is inspired by the install-fvwm2-menu from the debian fvwm2, but it tries to provide a somewhat more general interface for menu-building. With the update-menus command from this package, (and the /usr/lib/menu/$package files), no package needs to be modified for every X window manager again, and it provides a unified interface for both text- and X-oriented programmes. ************************ *It works like this: Each package includes a file in /usr/lib/menu/package-name. In this file, it will have one line per menu-entry, like this (from /usr/lib/menu/xpuzzles): X11 Apps/Games/Puzzles xtriangle none "Xtriangle" /usr/games/xtriangles This describes the type of interface the package needs (X11), the menu section the menu entry should be in, an id, possibly an icon, the menu text, and the command that should be executed. Whenever root runs update-menus, it will check all new or changed menufiles in /etc/menu and /usr/lib/menu, and run the installation scripts display managers like fvwm2 should provide in /etc/menu-methods on them. The menu package itself provides a set of default menu files, for people to get the idea, and to speed things up a bit (These files should be incorporated into the package). ************************ * (User-) Configuring the menu's A user can specify her/his own menu entries in the ~/.menu directory. the files in that directory should have names of installed packages, or "local.name", as update-menus assumes any "package" who's name starts with "local" is installed. A system admin should place system-wide menuentries in /etc/menu, (not in /usr/lib/menu/package, those will be overridden after an upgrade of package). Again, filenames must have a name of an installed package, or starting with "local". ************************ * Specifying "No-menu-entry" If a user wants to remove an entry from the system menu (in /etc/menu), then this will do the trick: echo -n > ~/.menu/package The zero-size file will tell update-menus that the corresponding package should not have any menu-entries listed. ************************ * What should the each package do to use this: -Include a conffile file in /etc/menu/$package. The name of the file should be $package, with $package the package name of the binary package the menufile will be distributed in. (in the case of single source packages that build many binary packages). This file should contain, for each programme it likes to make available in a menu: text Math gnuplot none "Gnuplot" /usr/bin/gnuplot ^ ^ ^ ^ ^ ^ | | | | | The binary to be executed | | | | The menu-entry-name | | | The pixmap in the menu entry | | Some ID for this menu entry. .Please make this | | ${package}/someid, where ${package} is the package name of the | | package the menu file will be distributed in, as | | we may require this later. | The section in which the menu entry should appear Type: X11 if this programme only runs on X11 displays text if it only runs on text-oriented terminals; (the window manager should spawn an xterm or rxvt in this case) vc if the program only runs at the Linux console (i.e.: svgalib) A programme like gnuplot should NOT have an extra entry for X11 like this: X11 Apps/Math gnuplot none "Gnuplot" "xterm -e /usr/bin/gnuplot" because it will then be next to impossible to configure the window mangers to spawn rxvt instead. If, on the other hand, a programme can both run like a real X application, and on a terminal (like emacs), then two entries should be listed (otherwise, emacs will also be run in an xterm). -In your postinst and postrm script, add a line like: if test -x /usr/bin/update-menus; then update-menus; fi -Do not make your package depend on the menu package. ************************ * The preferred layout of the menu (currently suggestion only): Apps -- all normal apps Editors -- editors (run it in xterm, if nothing else) Net -- mail, news, web, irc, etc Programming -- debuggers, etc Shells -- Different shells, like bash, ksh, zsh, ... Tools -- other tools: xclock, xmag, xman, Viewers -- Picture viewers, gs, ... Math -- Math apps like: gnuplot, octave, oleo,.. Graphics -- xpaint, xfig, xtiff, Emulators -- Dosemu, ... Sound -- System -- system administration and monitoring Games -- games and recreations Adventure -- walk around virtual space, zork, MOO's, etc Arcade -- (any game where reflexes count) Board -- Like: Gnuchess, pente, gnugo Card -- solitaire, etc Puzzles -- Stuff from xpuzzles, ... Sports -- Games derived from "real world" sports Strategy -- Build your world (Games like lincity, freeciv) Tetris-like -- games involving falling blocks Toys -- (oneko, xeyes, etc.) Screen -- Lock -- xlock, etc. Screen-saver -- Root-window -- things that fill the root window Window-managers -- (change between fvwm, afterstep, etc) Modules -- fvwm modules, etc. XShells -- shells (like xterm, rxvt, ...) (running the user's login shell in them). This is basically what Joey Hess posted on debian-devel, with Also, I moved the shells to the root, as I don't like to have to go two levels deep for my shell -- but if others prefer that, I'll happily revert this (and I moved xclock in tools, is that OK?) ************************ * What should each menu-manager (fvwm*, twm, pdmenu, ...) do? Provide a configfile-script in /etc/menu-methods that can read the menu-files. This script will be executed by update-menus with the to be installed menu-entries passed to the script via stdin. The scripts in /etc/menu-methods should be configfiles, if the user can tune the behaviour in the script (as is the case in the scripts provided in this package in /usr/doc/menu/examples/$wm). Run update-menus (if it exists) in the postinst, and remove the execute bit from the /etc/menu-methods in the postrm when called with remove. Example bash post{rm,inst} script: #postrm: #!/bin/sh set -e inst=/etc/menu-methods/twm #or fvwm, ... whatever manager you're installing case "$1" in remove) chmod a-x $inst ;; purge) #remove the files that install-fvwmgenmenu creates: rm /etc/X11/twm/{system.twmrc,menus.dat,menudefs.hook} #maybe also rm $inst, if dpkg doesn't do that itself. ;; upgrade);; *) echo "postrm called with unknown argument \`$1'" >&2 exit 0 ;; esac #postinst: #!/bin/sh set -e inst=/etc/menu-methods/pdmenu #or fvwm, ... whatever manager you're installing if [ -x /usr/bin/update-menus ] ; then if [ -f $inst ]; then chmod a+x $inst update-menus; fi fi The menu package should not include any installer scripts for window managers (that's the job of the packages that install the window managers), but I do provide scripts for nearly all debian window managers in /usr/doc/menu/examples. See the readme on how to activate them. For an example, see the latest fvwm95 package (or olvwm). ************************ * Options to update-menus -v verbose (generate a lot of output) -d debug (loads of more output) --show-time ************************ * What does update-menus do? when update-menu starts, it: 1 sets a variable $dirs to dirs="/etc/menu /usr/lib/menu /usr/lib/menu/default" (and if a user runs runs it, it will add ~/.menu to the front of that list) 2 it reads the list of installed packages. 3 for d in $dirs; do - read files in $d - check if corresponding package is installed, and, is listed in the $d/.updated-menus file, checking the mod time in $d/.updated-menus. Depending on that information, either put the menufile $file in the the install-menu-list, or the menuentry in the $remove-entries, and do put the entries in the already-correctly-installed-list 4 after going through all dirs, do for method in `ls /etc/menu-methods`; do $cat install-menu-list | method -f --stdin done Ad step 3+4 - The $d/.updated-menus file lists not only the files in that directory and it's mod-time (to check for changes), it also lists the known menu-managers (i.e., the output of `ls /etc/menu-methods`) at the time of the last installation. Based on this information, steps 3+4 are changed a bit, to update/remove new/old menu-managers. Ad step 1+2+3+4 although I've used a sh-like syntax here, it's written in C++. ************************ * The /usr/sbin/install-fvwmgenmenu programme The files /etc/menu-methods/fvwm* are "executable" config files that begin with #!/usr/sbin/install-fvwmgenmenu and thus start that programme, handing it the configuration file for the specific wm in argv[1]. This configuration consists of: - the compatibility mode (used to be fvwm, 9wm, .. but now "gen" for all wm's) - where the various files should be stored/read. - what "types" are supported, and what wrapper files should be used for each "type". See /usr/doc/menu/examples/ for some more comments. Options to install-fvwmgenmenu: -v be verbose -d Produce loads of debugging output -f (always) force install (assume no packages are installed) --install-files take the next arguments to be files woos menuentries should be installed --stdin (always) read menuentries from stdin. The -f and --stdin "options" exist because old versions used to have cache files and other complicated stuff. This didn't result in any speedups, and did complicate stuff. So we (Joey and I) decided to make -f and --stdin options that are always on (and can thus be ignored). Some window managers don't support the m4 or cpp preprocessing, and cannot read the menudefs.hook file from their system.*rc configfile. To still be able to use them, install-fvwmgenmenu will copy the file $path/$examplercfile to $path/$rcfile (with $path, $examplercfile and $rcfile defined in the install-fvwmgenmenu config file), and replace all occurrences 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) ************************ * "supported" section in the install-fvwmgenmenu config files. Each definition defines a display type that this window-manager supports. After the displaytype is the string that should be printed in the system."$wm"rc file for each menu entry that matches that display type. Install-fvwmgenmenu does the following variable expansions: variable in conffile expands to in example below this is: - - - ${title} -> menutitle Xtriangle ${section} -> lastpartofsection Puzzles ${fullsection} -> full section Apps/Games/Puzzles ${id} -> menuentry id xtriangle ${icon} -> icon none ${command} -> command /usr/games/xtriangles ${type} -> type X11 Example (see table above): X11 Apps/Games/Puzzles xtriangle none "Xtriangle" /usr/games/xtriangles (where in the title, menu, ... are taken from the menuentry in the menufile). As a special exception, if no "${command}" occurs in the wrapper, " ${command}" is added at the end, so empty wrapper files will at least hand the command. A similar exception is made for "${title}" in the fvwm2 compat mode. Along the lines of ${var}, you can also use: example example example purpose: ${var} var "var"+'v' none | just expand var $d{var} var \"var\"+'v' none | escape Double quotes $s{var} var "var"+\'v\' none | escape Single quotes $b{var} var \"var\"+\'v\' none | escape Both single and double q $%{var} %var% %"var"% | for icons (In this table, the first line lists the value of ${var}, and the other lines list what $d{var}, ... would have produced). strings like \\n, \\t, ... for their ordinary will be substituted for their C expansions (But not \0xx). Note: the above only holds for "compat=gen". the other compat modes will be disabled in the future, and currently don't support everything that's described above ************************ * Other install-fvwmgenmenu config script items: * compat Please make this "gen" only. (Old versions of install-fvwmgenmenu used to take other compats, but "gen" is much more general). 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 substituted the same way as the "supported" stuff is. treewalk: This string defines in what order to dump the $startmenu, $endmenu, and $submenutitle (and it's 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 $submenutitles of this menu and this menu's children. The default is "c(m)". For olvwm, one needs: "(M)" database: A cache file (old). genmenu: The menufile to generate (usually something like system."$wm"rc). 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 was 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. ************************ * Icons * Please, make sure the icons you specify are always available on the system. So, if you want to have an icon with your menuentry, the preferred method is to supply the icon with that package. Also, to prevent the distribution of icons files to turn too much into a mess, please put all icon files in /usr/X11R6/include/X11/{bitmap,pixmap}. If you, as a system admin, don't like the icons in the menu's, simply remove the $%{icon} from the files in /etc/menu-methods/$wm, and type "update-menus" If you want to specify an icon for a submenu (for example, the Editors submenu), just use the same syntax but leave the command empty: X11 Apps menu/apps /usr/X11R6/include/X11/pixmap/icon.xpm "Editors" As there probably isn't one right package to include the submenu icons, I guess (as Joey suggested) the menu package is the only right place to have these menu's (Otherwise, problems arise when two packages supply different icons for the same submenu, and we can never be sure the icon files are available). ************************ * Taskbar/Titlebar (fvwm*) * The problem with the stuff in the taskbar is that all items are displayed all of the time. So, if 200 debian packages all were to register a button, the buttons would quickly fill the screen, making the exercise useless. The few applications that are considered important enough to be listed in the taskbar usually vary widely on each system, making it impossible to select a ``happy few'' apps that are allowed there on every debian system. If you want your fvwm2 to have a few buttons, you can install files for those packages in /etc/menu/$package, containing both the normal menu entries, and a line like button Games/Puzzles xpuzzles/xmball path-to-pixmap.xpm "Xmball" /usr/games/xmball Then, do the following: cd /etc/menu-methods/ cp fvwm2 fvwm2button vi fvwm2button #and remove all the "supported" entries, adding the one below. For the rest, leave everything the same except those listed below. supported button="+ Style \"${title}\" TitleIcon ${icon} Exec ${command}\\n" endsupported startmenu: "AddToTitlebar \\n" endmenu: "\\n" submenutitle:"" mainmenu: genmenu: "buttondefs.hook"