1
This "package" is inspired by the install-fvwm2-menu from the debian fvwm2,
2
but it tries to provide a somewhat more general interface for
3
menu-building. With the update-menus command from this package,
4
(and the /usr/lib/menu/$package files),
5
no package needs to be modified for every X window manager again,
6
and it provides a unified interface for both text- and X-oriented
9
Note that substantial changes took place with the menu-1.0 release.
10
This README describes menu-1.0, most notable changes are listed in
11
README.changes, and README.pre1 is the old README (please don't use
14
************************
17
Each package includes a file in /usr/lib/menu/package-name. In this
18
file, it will have one line per menu-entry, like this (from
21
?package(xbase):command="/usr/bin/X11/xedit" icon="none" needs="X11" \
22
section="Apps/Editors" title="Xedit"
24
This describes the type of interface the package needs (X11),
25
the menu section the menu entry should be in, possibly
26
an icon, the menu text, and the command that should be executed.
28
Whenever root runs update-menus, it will check all new or
29
changed menufiles in /etc/menu and /usr/lib/menu,
30
and run the installation scripts display managers like fvwm2
31
should provide in /etc/menu-methods on them.
33
The menu package itself provides a set of default menu files,
34
for people to get the idea, and to speed things up a bit
35
(These files should be incorporated into the package).
37
************************
38
* (User-) Configuring the menu's
40
A user can specify her/his own menu entries in the ~/.menu directory.
41
The files can have any name you want, and should start with either:
42
?package(installed-package):
43
or, if it's something that isn't "debian-officially" installed, with
44
?package(local.mystuff):
45
(any "package" that starts with "local." is considered installed).
47
If your using old format menuentryfiles should have names of
48
installed packages, or "local.name", as update-menus assumes any
49
Any "package" that starts with "local." is considered installed.
50
(due to a bug in menu-1.3 this didn't work then).
53
If a user wants to have his own menu-methods, s/he should create a
54
~/.menu-methods directory, and put all scripts s/he wants to be run
55
in there (if ~/.menu-methods exists, /etc/menu-methods will not be
56
searched when a user runs update-menus).
58
A system administrator should place system-wide menuentries in /etc/menu,
59
(not in /usr/lib/menu/package, those will be overridden after an upgrade
62
************************
63
* Specifying "No-menu-entry"
65
If a user wants to remove an entry from the system menu (in /etc/menu),
66
then this will do the trick:
67
echo -n > ~/.menu/package
68
The zero-size file will tell update-menus that the corresponding
69
package should not have any menu-entries listed.
71
************************
72
* What should the each package do to use this:
74
-Include a conffile file in /usr/lib/menu/$package.
75
The name of the file should be $package, with $package the
76
package name of the binary package the menufile will be distributed
77
in. (in the case of single source packages that build many binary packages).
78
This file should contain, for each programme it likes to make
80
?package(gnuplot):\ specifies what packages need to be installed
81
needs=text\ what kind of terminal this command expects
82
\ needs=X11: if this programme only runs on X11
83
needs=text:if it only runs on text terminals;
84
(the window manager should spawn
85
an xterm or rxvt in this case)
86
needs=vc :runs only at Linux console.
87
needs=wm :this starts another windowmanager
88
section=Apps/Math\ in what section should this menuentry be
89
title="Gnuplot"\ The tile of the menuentry (make it short please)
90
command="/usr/bin/gnuplot" the command to run.
92
A programme like gnuplot should NOT have an extra entry for
93
needs=X11 because it will then be next to impossible to configure the
94
window mangers to spawn rxvt instead of the default xterm.
96
If, on the other hand, if a programme can both run like a real
97
X application, and on a terminal (like emacs), then two
98
entries should be listed (otherwise, emacs will also be run in
101
-In your postinst and postrm script, add a line like:
102
if test -x /usr/bin/update-menus; then update-menus; fi
104
-Do not make your package depend on the menu package.
106
************************
107
* The preferred layout of the menu (currently suggestion only):
109
Apps -- all normal apps
110
Editors -- editors (run it in xterm, if nothing else)
111
Net -- mail, news, web, irc, etc
112
Programming -- debuggers, etc
113
Shells -- Different shells, like bash, ksh, zsh, ...
114
Tools -- other tools: xclock, xmag, xman,
115
Viewers -- Picture viewers, gs, ...
116
Math -- Math apps like: gnuplot, octave, oleo,..
117
Graphics -- xpaint, xfig, xtiff,
118
Emulators -- Dosemu, ...
120
System -- system administration and monitoring
121
Games -- games and recreations
122
Adventure -- walk around virtual space, zork, MOO's, etc
123
Arcade -- (any game where reflexes count)
124
Board -- Like: Gnuchess, pente, gnugo
125
Card -- solitaire, etc
126
Puzzles -- Stuff from xpuzzles, ...
127
Sports -- Games derived from "real world" sports
128
Strategy -- Build your world (Games like lincity, freeciv)
129
Tetris-like -- games involving falling blocks
130
Toys -- (oneko, xeyes, etc.)
134
Root-window -- things that fill the root window
135
Window-managers -- (change between fvwm, afterstep, etc)
136
Modules -- fvwm modules, etc.
137
XShells -- shells (like xterm, rxvt, ...)
140
************************
141
* What should each menu-manager (fvwm*, twm, pdmenu, ...) do?
143
Provide a configfile-script in /etc/menu-methods that can read
144
the menu-files. This script will be executed by update-menus
145
with the to be installed menu-entries passed to the script via
148
The scripts in /etc/menu-methods should be configfiles, if the user
149
can tune the behaviour in the script (as is the case in the scripts
150
provided in this package in /usr/doc/menu/examples/$wm).
152
Run update-menus (if it exists) in the postinst, and remove the
153
execute bit from the /etc/menu-methods in the postrm when called
155
Example bash post{rm,inst} script:
160
inst=/etc/menu-methods/twm #or fvwm, ... whatever manager you're installing
167
#remove the files that install-fvwmgenmenu creates:
168
rm /etc/X11/twm/{system.twmrc,menus.dat,menudefs.hook}
169
#maybe also rm $inst, if dpkg doesn't do that itself.
173
echo "postrm called with unknown argument \`$1'" >&2
181
inst=/etc/menu-methods/pdmenu #or fvwm, ... whatever manager you're installing
182
if [ -x /usr/bin/update-menus ] ; then
183
if [ -f $inst ]; then
189
The menu package should not include any installer scripts for
190
window managers (that's the job of the packages that install the
191
window managers), but I do provide scripts for nearly all
192
debian window managers in /usr/doc/menu/examples. See the readme
193
on how to activate them. For an example, see the latest fvwm95 package
197
************************
198
* What does update-menus do?
201
On startup, update-menus does:
202
check file /var/run/update-menus.pid, and the pid in it -- if
203
there's an update-menus process with that pid, kill it.
204
if /var/lib/dpkg/lock exists,
205
fork to background, and return control to dpkg.
206
in background process:
207
Every approx second check for /var/lib/dpkg/lock
208
repeat until it's gone.
210
when the lockfile has disappeared (or never has been), start
211
the "normal" update-menus:
213
1 sets a variable $dirs to
214
dirs="/etc/menu /usr/lib/menu /usr/lib/menu/default"
215
(and if a user runs runs it, it will add ~/.menu to the front
217
2 it reads the list of installed packages.
220
- check if corresponding package is installed, and, is listed
221
in the $d/.updated-menus file, checking the mod time in
223
Depending on that information, either put the menufile $file in the
224
the install-menu-list, or the menuentry in the $remove-entries,
225
and do put the entries in the already-correctly-installed-list
226
4 after going through all dirs, do
227
for method in `ls /etc/menu-methods`; do
228
$cat install-menu-list | method -f --stdin
232
- The $d/.updated-menus file lists not only the files in that directory
233
and it's mod-time (to check for changes), it also lists
234
the known menu-managers (i.e., the output of `ls /etc/menu-methods`)
235
at the time of the last installation. Based on this information,
236
steps 3+4 are changed a bit, to update/remove new/old menu-managers.
238
although I've used a sh-like syntax here, it's written in C++.
241
Here there's a hack for backwards compatibility with the old
242
install-fvwmgenmenu: if the script in /etc/menu-methods doesn't
243
start with "#!/usr/sbin/install-menu", the old dataformat will be sent
246
************************
247
* The /usr/sbin/install-menu programme
249
The files /etc/menu-methods/fvwm* are "executable" config files
251
#!/usr/sbin/install-menu
252
and thus start that programme, handing it the configuration file for the
253
specific wm in argv[1]. This configuration consists of:
254
- the compatibility mode ("menu-1").
255
- where the various files should be stored/read.
256
- what "needs" are supported, and what wrapper files should
257
be used for each "type".
258
See /usr/doc/menu/examples/ for some more comments.
260
Options to install-fvwmgenmenu:
262
-d Produce loads of debugging output
264
The -f and --stdin "options" exist because old versions used to
265
have cache files and other complicated stuff. This didn't result
266
in any speedups, and did complicate stuff. So we (Joey and I) decided
267
to make -f and --stdin options that are always on (and can thus be
270
Some window managers don't support the m4 or cpp
271
preprocessing, and cannot read the menudefs.hook file
272
from their system.*rc configfile. To still be able to use them,
273
install-fvwmgenmenu will copy the file $path/$examplercfile to
274
$path/$rcfile (with $path, $examplercfile and $rcfile defined
275
in the install-fvwmgenmenu config file), and replace all
276
occurrences of "install-menu-defs" with the $genmenu
277
file it just generated. Although this approach looks quite
278
clumsy, it does allow for one $path/$examplercfile on the system,
279
(The m4/cpp approach puts a "include(/etc/X11/*/menudefs.hook)"
280
in the system.*rc file, so users will never load their menudefs.hook
282
To activate the file-copying in this way, simply define
283
the $examplercfile and $rcfile variables in the install-fvwmgenmenu
284
configuration file (/etc/menu-methods/fvwm*), and make sure
285
there is a $path/$examplercfile ($path being either $rootprefix, or
289
If you are wringing a menu-method, you can use the following to
290
debug it somewhat easier:
291
- use the "cat" menu-method in /usr/doc/menu/examples/cat to
292
create a list of menuentries in /tmp/menu-stdin
293
(put it in ~/.menu-methods, and run update-menus), and then
294
- you can run just your menu-method with (if it's called wm):
295
./wm -v < /tmp/menu-stdin
296
(-v for verbose, use -d for debugging, you'll get loads of output).
299
************************
300
* install-menu config script definitions:
303
the menu-methods in /etc/menu-methods/* are basically made up of
304
a lot of section=string definitions, explaining install-menu
305
how to generate a "system.$wmrc" script. This way you can tune
306
the look of generated "system.$wmrc" to your needs.
308
In the following, something like
310
means that the treewalk variable by default has the value "c(m)".
312
For examples of what these scripts can look like, see /usr/doc/menu/examples.
315
Should always be "menu-1".
316
Please, make this the first non-comment line in the script.
320
Between the supported and endsupported keywords you define what
321
"needs" are supported by this window manager. So, the following
322
is for a wm that supports both needs=x11 and needs=text:
326
x11=" ShowEntry("title=\"" $title "\", command=\"" $command "\"")
327
text=" ShowEntry("title=\"" $title "\", command=\""\
328
"xterm -T " $title " -e " $command "\"")
331
For the variable substitution (and functions, not shown above),
332
see the next paragraph.
333
In the above example, you'll notice that for the menuentries that
334
"need=text", an xterm is spawned for the command to run in.
335
Also, as x11 is higher up in the supported list than text, a package that
336
supplies both a "needs=x11" and a "needs=text" entry will have the
337
needs=x11 entry installed, in favour of the needs=text entry.
338
You can continue lines on the next line with a \, but do make sure
339
you don't add any spaces after the \.
344
These define what to print for the beginning/end of a menu, and
345
how to the print a menuentry that pops up another menuentry.
346
They are substituted the same way as the "supported" stuff is
347
(see next paragraph).
350
This string defines in what order to dump the $startmenu, $endmenu,
351
and $submenutitle (and it's children). Each char in the string
353
c : dump children of menu.
354
m : dump this menu's $submenutitles
357
M : dump all $submenutitles of this menu and this menu's children.
358
The default is "c(m)". For olvwm, one needs: "(M)"
361
The menufile to generate (usually something like system."$wm"rc).
362
The file itself may depend on the level or title that is currently
364
genmenu="/subdir/" replacewith($section," ","_") "/rc.menu"
365
(Substitution works just like the supported stuff, see above).
366
Note that the files made this way are truncated upon
367
opening, so if you have a genmenu like the example above, then
368
your endmenu= will override the startmenu stuff (but you probably
369
only need one of the two anyway).
371
rootsection="/Debian"
372
the prefix every $section variable gets.
376
The commands to run before resp. after the actual generation of the
377
menudefs.hook (genmenu) file. Commands will be executed by sh.
379
prerun="rm -rf " prefix() "/*"
380
postrun="killall -USR1 fvwm2"
381
(Substitution works just like the supported stuff, see above).
383
preoutput="#Automatically generated file. Do not edit (see /usr/doc/menu/html)\n\n"
385
Text to put at the beginning resp. end of the generated file ($genmenu).
388
A command to run instead of install-menus. This command will receive
389
the menuentries install-menus would have received on stdin.
392
Keys not to use for hotkey generation. You can use the same
393
variables and functions here as in for example the startmenu
396
hotkeyexclude="q" $section
398
hotkeycase="insensitive"
399
can be either "insensitive" or "sensitive". Determines
400
whether the hotkeys can be of mixed case (fvwm2 reads
401
the hotkeys case-insensitive, pdmenu case-sensitive).
402
In case of the titles "Xa" and "xb", hotkey will generate
403
"X" and "b", whereas sensitive would generate "X" and "x"
406
If the window manager doesn't support an "include filename" or
407
"read(filename)" statement in it's config file, you can rename
408
the wm's config file to system."$wm"rc-menu, and insert
409
a "install-menu-defs" line (without the quotes, or whitespace around
410
it, and "install-menu-defs" must be the only thing on the line)
411
in the system."$wm"rc-menu file. This will then get replaced
412
by the $genmenu file that was just created (see also $examplercfile).
415
if needed (see rcfile), this is the system.rc"$wm"-menu file.
416
In that case, make rcfile=system.rc"$wm".
419
The prefix to use when running as root (applies to $genmenu, $rcfile,
420
$examplercfile and other old cache files)
423
see rootprefix, but when running as user.
427
************************
428
* variables and functions in the install-menu scripts.
430
The supported "needs" definitions and "startmenu=", "endmenu="
431
and "submenutitle=" are interpreted as follows:
436
Anything matching with \"[^\"]*\" is interpreted as a string, and
437
is written verbatim to the output file.
438
Stuff like \n, \t, ... will be substituted for their C expansions
444
Anything matching $[a-z,A-Z,_]* is interpreted as a variable, and
445
the corresponding definition from the menuentry is substituted. So,
449
The following variables are treated in a special way by install-menus,
450
either because they are used for other purposes too, or because they
451
are modified by install-menus (the ones with a "!" are modified
454
needs: used to determine whether the window manager supports this
456
command: If this is undefined, this menuentry is taken as defining
457
a submenu. (this way you can specify icons of submenus).
458
title!: Used for sorting (see section).
459
For submenuentries (those with empty command), this
460
is initialised to the last part of the section.
461
Please, keep the title short (two words at maximum).
462
The title is for people who already know what programme
463
they want to start. See "longtitle" and "description" below
464
for longer descriptions.
465
sort: used for sorting (see section).
466
section!:Used to determine the section of the menuentry.
467
The menuentries that have a empty $command, have their
468
$section changed to modify the current level.
469
The menuentries that have a non-empty $command have their
470
$section modified to $section/$title, or $section/$sort:$title
471
if $sort is defined. The menuentries within one section
472
are sorted according to $section.
473
hotkey!: Modified to reflect what install-menus thinks is the
474
most suitable hotkey for this menuentry. The hotkey=
475
in the menuentry file is taken as a suggestion, that could
476
be overwritten if there is another entry with the same hotkey=.
477
To suggest two possible hotkeys for an entry use
478
hotkey="ab", with "a" being the most preferred hotkey.
481
The following aren't special for install-menus, but it's nice
482
(read: essential) to use the same variables for the same things.
483
So, I'll suggest some here. If you want to invent new ones, please
484
do so and mail them to me so that I can include them here.
486
icon: The location of the iconfile for this menuentry.
487
If you don't have an iconfile, just leave out the icon=
489
longtitle: For people that like descriptive titles (about one line)
490
It is probably best to include this in your menuentries,
491
while the window-managers don't (by default) put it in the
492
menus. That way, people who want descriptive titles can
493
turn them on, but others don't need to use them.
494
description:An even longer description (about 5 lines).
495
For example, a description of the documentation in
496
the dwww generated html pages.
502
Anything matching [a-z,A-Z,_] is taken as a function (and an error
503
is generated if the function doesn't exist). The arguments of the
504
functions can be other functions, string constants or variables.
507
returns the current prefix dir: either $rootprefix, or
508
$HOME/$userprefix, depending on who runs install-menu
510
ifroot($rootarg, $userarg)
511
if(getuid()==0) print $rootarg, else print $userarg
514
Same as just $arg; if $arg is empty, generate an error.
517
Print $arg1, but escape all occurrences of characters in $arg2
518
with a \. (thus, if arg1="hello", arg2="lo", print "he\l\l\o").
520
escwith($arg1, $arg2, $arg3)
521
Same as esc, but use $arg3 as escape sequence.
523
escfirst($arg1, $arg2, $arg3)
524
Same as escwith, but only escapes thirst occurrence of $arg2.
528
Returns the argument set in lowercases resp uppercases.
530
replacewith($s, $replace, $with)
531
Search s for occurrences of characters from string replace, and
532
replace them by the corresponding character in $with.
534
replacewith_string("hello $world, %dir", "$% ", "123")
535
returns: "hello31world,32dir"
537
ifempty($arg1, $arg2)
538
If $arg1 is empty, print $arg2, otherwise print nothing.
539
For compatibility, the string "none" is seen as empty.
541
ifnempty($arg1, $arg2)
542
If $arg1 is not empty, print $arg2.
543
For compatibility, the string "none" is seen as empty.
546
If $arg1 is non-empty, print $arg1, otherwise $arg2.
547
For compatibility, the string "none" is seen as empty.
549
ifeq($arg1, $arg2, $arg3)
550
If ($arg1==$arg2) then print $arg3
551
ifneq($arg1, $arg2, $arg3)
552
If ($arg1!=$arg2) then print $arg3
553
ifeqelse($arg1, $arg2, $arg3, $arg4)
554
If ($arg1==$arg2) then print $arg3 else print $arg4
556
cond_surr($arg1, $arg2, $arg3)
557
If $arg1 is non-empty print $arg2$arg1$arg3, otherwise print nothing.
558
For compatibility, $arg1="none" is interpreted as empty.
561
If file $arg1 exists, and can be opened for reading by whoever
562
started the current process, return $arg2, otherwise return nothing.
565
for arg a "directory", return parent directory:
566
parent("/Debian/Apps/Editors") = "/Debian/Apps".
569
return the last part of the parent directory:
570
basename("/Debian/Apps/Editors") = "Apps".
575
String constants, variables and functions can be concatenated
576
by placing them after each other with a space in between, like
578
"hello" $ifelse($comma, $comma, "sorry" $period " no comma def") " world"
582
User-defined functions (or rather, macros):
584
You can define your own function, by typing (outside "supported" scope):
586
function myfunc($var1, $var2) = "this is my function, var1=" $var1 ", title= "$title
588
Note that this example uses a variable "title" that it expects to be defined.
589
This is true if it is called from the "startmenu", "endmenu", "submenutitle",
590
a supported definition.
592
************************
596
Please, make sure the icons you specify are always available on the system.
597
So, if you want to have an icon with your menuentry, the preferred method
598
is to supply the icon with that package. Also, to prevent the distribution
599
of icons files to turn too much into a mess, please put all icon
600
files in /usr/X11R6/include/X11/{bitmap,pixmap}.
603
Debian package maintainers should ensure that any icons they include that
604
are used with the debian menus conform to the following:
606
1. They should be in xpm format.
607
2. They may be no larger than 32x32 pixels, although smaller sizes are ok.
608
3. They should use only the 24 colors present in cmap.xpm, which comes with
610
4. The background area of the icon should be transparent, if possible.
612
If you have Imagemagick installed, you can make your icons meet requirements
613
1, 2, and 3 with the following command, but you will need to edit the icon
614
afterward to clean it up and make the background transparent:
616
# mogrify -format xpm -geometry 32x32 -map cmap.xpm <filenames>
619
If you, as a system administrator, don't like the icons in the menu's, simply
620
remove the $%{icon} from the files in /etc/menu-methods/$wm, and
624
If you want to specify an icon for a submenu (for example, the Editors
625
submenu), just use the same syntax but leave the command empty:
627
X11 Apps menu/apps /usr/X11R6/include/X11/pixmap/icon.xpm "Editors"
629
As there probably isn't one right package to include the submenu icons,
630
I guess (as Joey suggested) the menu package is the only right place
631
to have these menu's (Otherwise, problems arise when two packages
632
supply different icons for the same submenu, and we can never be sure
633
the icon files are available).
636
************************
637
* Taskbar/Titlebar (fvwm*)
640
The problem with the stuff in the taskbar is that all items are
641
displayed all of the time. So, if 200 debian packages all were to
642
register a button, the buttons would quickly fill the screen, making
643
the exercise useless. The few applications that are considered important
644
enough to be listed in the taskbar usually vary widely on each system,
645
making it impossible to select a ``happy few'' apps that are allowed
646
there on every debian system. If you want your fvwm2 to have a few
647
buttons, you can install files for those packages in /etc/menu/$package,
648
containing both the normal menu entries, and a line like
649
button Games/Puzzles xpuzzles/xmball path-to-pixmap.xpm "Xmball" /usr/games/xmball
651
Then, do the following:
652
cd /etc/menu-methods/
655
#and remove all the "supported" entries, adding the one below. For the rest,
656
leave everything the same except those listed below.
659
button="+ Style \"" $title "\" TitleIcon" $icon " Exec " $command "\n"
661
startmenu: "AddToTitlebar \n"
665
genmenu: "buttondefs.hook"
4
menu is a menu-generator originally made for Debian. It provides an
5
update-menus program to generate menus for different providers of menus
6
(both window managers and console applications like pdmenu).
8
Menu files are placed in /usr/lib/menu by packages. update-menus then reads
9
these files and passes them to install-menu which generates a menu specified
10
by a menu-method (placed in /etc/menu-method).
12
The full documentation for menu can be found in doc/menu.txt.gz or
added
removed
README
