Debian Menu System - chapter 2
What packages with applications should do


2.1 Registering your applications

A package of an application should provide a menu file /usr/lib/menu/<package-name> that contains some information about each program it likes to make available in the menus.

Here is an example to describe the syntax of such a file:

  ?package(gnuplot):\            specifies what packages need to be installed
     needs=text\                 what kind of terminal this command expects
                                 needs=X11: if this program runs only on X11
  			         needs=text: if it only runs on text terminals
					   (the window manager should spawn 
					    an xterm or rxvt in this case)
			         needs=vc: runs only at linux console
			         needs=wm: this starts another windowmanager
     section=Apps/Math\	         in what section this menu entry should be
     title="Gnuplot"\            the title of the menu entry
                                 (please make it short!)
     command="/usr/bin/gnuplot"  the command to run.

A program like gnuplot which can be run on X11 as well as on a text terminal should not have an extra entry with needs=X11 because it will then be next to impossible to configure the window managers to spawn rxvt instead of the default xterm.

On the other hand, if a program like emacs can be run as real X application as well as in a terminal two entries should be listed, otherwise the program will always be run in an xterm.

You should add a line like this to your postinst script (replacing $wm with the name of your window manager, or more precisely, the name of the menu-method in /etc/menu-methods):

 if test -x /usr/bin/update-menus; then update-menus; fi
and the postrm script should get the line
 if test -x /usr/bin/update-menus; then update-menus; fi
(that is, the same line in postinst and in postrm).


2.2 Preferred menu structure

Here is the authoritative list of Debian's menu structure. If you have a package which does not fit in here or if you have any suggestions how to improve this structure, please send an email to the maintainer of the menu package, Joost Witteveen joostje@debian.org.

Please do not put your packages into any other sections without asking for permission first!

       Apps            - normal apps
         Editors       - editors (run it in xterm, if nothing else)
         Emulators     - dosemu, etc.
         Graphics      - xpaint, xfig, xtiff, etc.
	 Hammradio     - Anything relating to hamradio.
         Math          - gnuplot, octave, oleo, etc.
         Net           - mail, news, web, irc, etc.
         Programming   - debuggers, etc.
         Tools         - other tools: xclock, xmag, xman, etc.
	 Technical     - technical stuff.
	 Text          - text oriented tools other than editors.
         Shells        - bash, ksh, zsh, etc.
         Sound         - TkMidity, etc.
         Viewers       - Picture viewers, gs, etc.
         System        - system administration and monitoring tools
       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          - solitare, 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.
         Save          -
         Root-window   - things that fill the root window
       WindowManagers  - (change between fvwm, afterstep, etc)
         Modules       - fvwm modules, etc. 
       XShells         - shells (like xterm, rxvt, ...)


2.3 Icons

Please, make sure the icons you specify are always available on the system. So, if you want to have an icon with your menu entry, 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 the directory /usr/X11R6/include/X11/{bitmaps,pixmaps}.

Debian package maintainers should ensure that any icons they include for use in the debian menus conform to the following points:

  1. The icons should be in xpm format.

  2. The icons may not be larger than 32x32 pixels, although smaller sizes are ok.

  3. The icons should use only the 24 colors present in cmap.xpm, which comes with the menu package.

  4. The background area of the icon should be transparent, if possible.

If you have Imagemagick installed, you can make your icons meet requirements 1, 2, and 3 with the following command, but you will need to edit the icon afterwards to clean it up and make the background transparent:
  $ mogrify -format xpm -geometry 32x32 -map cmap.xpm <filenames>
If you, as a system admin, don't like the icons in the menus, simply remove the $%{icon} from the files in /etc/menu-methods/$wm, and run update-menus.

It's also possible to specify an icon for a submenu. However, if each package would supply its own icons for the sub menus we can never be sure that the icon files are available. Thus, only the menu package is allowed to specify icons for sub menus. The syntax for this is:

  X11 Apps menu/apps /usr/X11R6/include/X11/pixmap/icon.xpm "Editors"

2.4 Fvwm's task and title bars

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 (as a local system admin) you want your fvwm2 to have a few buttons, you can install files for those packages in /menu/$package, containing a menu entry like this:
  ?Package(xmball):needs=button\
                section=Games/Puzzles\
                icon=path-to-pixmap.xpm\
                title="Xmball"\
                command=/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"

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