Dear Christian Schwarz  (and Joey Hess!)

This email is long-over due, but anyway here it is.

I finally got round to writing up something for the Debian Policy
to explain the menu system. What I've got so far is the minimum
any package maintainer should know (or be able to lookup) to use
the menu system, but I think that's the purpose of the Debian Policy.
If any user/maintainer wants to know more, I point them to 
/usr/doc/menu/README.

This email breaks down in two parts:

*About the general menuentries
  Just what I'd like to be added.

*About the web-standard (menuentries):
  I noticed that in the section about the web standard, there
  are some errors (about the menu stuff). This corrects them.

What I've got below isn't formatted at all -- I'm actually not sure
what documentation system you use. If you want me to make chages,
whatever, please tell me.

(This email is also CC'd to Joey Hess, because he knows more
about the menu system than I do, and always spots a lot of mistakes
I make).


Please tell me what you think.


***********************
About the general menuentries.

I call this section 3.11, because I think that's aproximately where it belongs.
but you're of cource free to put it in section 9.234 if you think that's more
appropriate. 

notes: 
1) I'm saying that all apps that can be started
   without arguments should have menuentries -- I'm not sure this is really
   the best formulation, or even close to the trueth.
2) About the "preferred menu tree": I suggest that requests about
   additions to that tree go to me. Maybe they should go to the
   maintainer of the debian-policy document now. However, I'd
   prefer to get the requests myself (I'll discuss them with
   Joey if they are reasonable, usually), because I guess I know
   somewhat more about the menusystem. But if you think otherwise,
   please tell me.

Addition to policy:   
-------------

3.11 Registering menuentries.

Packages that provide applications that need not be passed any
special arguments to configure how they 
work should register a menuentry for those applications, so that
users of the menu package will automatically get menuentries in
their window-managers, as well in shells like pdmenu.

To register menuentries, put create the file /usr/lib/menu/package-name,
with the entries you want to register, and add both to your postinst and
postrm scripts the line 
  if test -x /usr/bin/update-menus; then update-menus; fi


The general format of a menuentry is as follows:

?package(requred-package-name):var1="value1" var2="value2"

Where var can be any of:
(*)needs:     what kind of terminal this command expects
               needs=X11: if this programme only runs 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
               needs=dwww:if this is a entry for dwww (the web system)
(*)section:   The section of the menuentry in the menu tree.
              (see below for a preferred tree).
(*)title:     The title of the menuentry (short, please!)
   longtitle:title, about 60 chars long.
              (longtitle can be configured to show up in stead of
	       the short title in the menumethods).
   description:description, about 240 chars long
(*)command:   The command to run.
   icon:      possibly an icon (see /usr/doc/menu/README).

asterisk, (*) means: this variable has got to be defined, for this
menuentry to be valid.

An example of a menuentry file would be (found in /usr/lib/menu/xpaint):

?package(xpaint):needs=X11 section=Apps/Graphics \
          title="Xpaint" \
          longtitle="Xpaint: jpeg/tiff/png/etc editor" \
          command=/usr/bin/X11/xpaint



The preferred menu-tree is as follows: (if your application doesn't
fit in here, please email me, joostje@debian.org).

       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
	   Admin       -- System adminstration tools, that usually
	                  require root (see /usr/lib/menu/default/lilo
			  for how to do that)
       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.
         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, ...)


For information on how to tailor the look of your menu's, how
to locally add menuentries (or on a per-user-basis), please
see /usr/doc/menu/README.

***********************
About the web-standard (menuentries):

In 3.13 the example web-menu-entry currently reads (part 4):

  [example:]
>    web <Section> <menuid> <Icon> <Description> <html file to be displayed on clicking on the menu>
>
>    Example: 
>
>    web Apps/Viewers gv none GhostView /usr/doc/gv/gv.html


This is both wrong (should've started with dwww, not web), and it's old
format. (and it shouldn't have "description" but "title", but that's less
important) 


Could you change this to read:  

> ?package(package-name):needs=dwww section=<Section> \
>   title="title"\
>   longtitle="longtitle (about 80 chars or so)"\
>   description="Description (about 240 chars or so)"\
>   command=<html file to be displayed on clicking on the menu>
> 
>     Example: 
> 
> ?package(dpkg):needs="dwww" section="Apps/Programming" \
>      title="Debian Programmer" \
>      longtitle="Debian Programmers' Manual" \
>      description="This manual describes the technical aspects of\
>  creating Debian binary and source packages. It also documents\
>  the interface between dselect and its access method scripts"\
>      command="/usr/doc/dpkg/programmer.html/index.html"

This would give new-format (much more versatile), and a working example
(the "web" in stead of "dwww" realy made it all unusable).


joostje@debian.org
