From dd7279795c97aa356727d366a2149c9bc838b496 Mon Sep 17 00:00:00 2001 From: Bill Allombert Date: Wed, 16 Nov 2011 12:33:27 +0100 Subject: Imported Debian version 2.1.46 --- doc/menu.html/ch1.html | 207 ++++++++ doc/menu.html/ch2.html | 192 +++++++ doc/menu.html/ch3.html | 1249 ++++++++++++++++++++++++++++++++++++++++++++++ doc/menu.html/ch4.html | 145 ++++++ doc/menu.html/ch5.html | 226 +++++++++ doc/menu.html/ch6.html | 224 +++++++++ doc/menu.html/ch7.html | 821 ++++++++++++++++++++++++++++++ doc/menu.html/ch8.html | 665 ++++++++++++++++++++++++ doc/menu.html/index.html | 208 ++++++++ 9 files changed, 3937 insertions(+) create mode 100644 doc/menu.html/ch1.html create mode 100644 doc/menu.html/ch2.html create mode 100644 doc/menu.html/ch3.html create mode 100644 doc/menu.html/ch4.html create mode 100644 doc/menu.html/ch5.html create mode 100644 doc/menu.html/ch6.html create mode 100644 doc/menu.html/ch7.html create mode 100644 doc/menu.html/ch8.html create mode 100644 doc/menu.html/index.html (limited to 'doc/menu.html') diff --git a/doc/menu.html/ch1.html b/doc/menu.html/ch1.html new file mode 100644 index 0000000..e060eb6 --- /dev/null +++ b/doc/menu.html/ch1.html @@ -0,0 +1,207 @@ + + + + + + + + +Debian Menu System - Introduction + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+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. Users themselves can add/delete menu items, and +should then run update-menus as that user, thus creating +window-manager startup files that are used in preference to the systemwide +files. +

+ +

+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 +/Applications/Editors, while I'm sure that other people have more +like 20 entries there. Many people complained 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 +/Applications/Editors tree in, say Editors/Beginner, +Editors/Experienced, or whatever, if there are many entries in +that submenu, or maybe even totally removing /Applications/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/share/menu/package-name. In this file, it will have one line +per menu entry, like this (copied from /usr/share/menu/xbase): +

+ +
+        ?package(xbase):command="/usr/bin/xedit" needs="X11" \
+                     section="Applications/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 +executed. Also, it tells menu that, if /Applications/Editors is +overfull, it could put Xedit in a Applications/Editors/Beginner or +Applications/Editors/Small subsection. +

+ +

+Whenever root runs update-menus, it will check all +menu files in /etc/menu, /usr/lib/menu, +/usr/share/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/share/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 +summarised here: hints, and the menu-2 compat mode. (where lines are finished +by a ';' instead of a newline). +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch2.html b/doc/menu.html/ch2.html new file mode 100644 index 0000000..558e9b4 --- /dev/null +++ b/doc/menu.html/ch2.html @@ -0,0 +1,192 @@ + + + + + + + + +Debian Menu System - Menu from the viewpoint of a user + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 2 - Menu from the viewpoint of a user +

+ +
+ +
+ +

2.1 How/when do the window manager startup files get created?

+ +

+Basically, users don't need to know any of how and when the startup files are +created, but they might be interested to know anyway. +

+ +

+When a package that wants to add something to the menu tree gets installed, it +will run update-menus in its postinst script. +Update-menus then reads in all menu files in /etc/menu/, +/usr/lib/menu, /usr/share/menu and +/usr/share/menu/default, and stores the menu entries of all +installed packages in memory. Once that has been done, it will run the +menu-methods in /etc/menu-methods/*, and pipe the information +about the menu entries to the menu-methods on stdout, so that the menu-methods +can read this. Each window-manager or other program that wants to have the +Debian menu tree, will supply a menu-method script in +/etc/menu-methods/. This menu-method then knows how to generate +the startup-file for that window manager. To facilitate this task for the +window-manager maintainers, menu provides a install-menu program. +This program can generate the startupfiles for just about every window manager. +

+ +
+ +

2.2 Tuning of the generated window manager startup files

+ +

+In principle this is a very window-manager specific business. But for all +window managers (and others) applies: +

+ +

+The file to attack is the menu-method in /etc/menu-methods/$wm, +with $wm the name of your window manager. However, if this +menu-method !include-s the menu.h file (as it +should), you can also edit that file, to make your changes work for every +installed window manager. +

+ +

+If the menu-method file of your window manager does !include the +menu.h file, and makes proper use of the definitions in there, +then you can look at the comments in that menu.h file to see how +you can make minor adjustments to the look of your menus in your window +manager. +

+ +

+To generally change the menu tree, see the next section. +

+ +
+ +

2.3 Optimization of menu tree: hints

+ +

+If hint_optimize=true has been set in a menu-method script +(actually, that definition should appear in the !include-ed +menu.h file), then install-menu will try to alter the menu tree, +to make every submenu have about the optimum number of menu entries (as +specified by hints_nentry=...). It will do that by removing +under-full submenus (only if the `parent' of that submenu isn't itself already +overfull), and by possibly creating new submenus, using hints. Note, however, +that the optimization of the tree takes in principle exponential time, so menu +speeds up the process, at the expense of occasionally not finding the best +tree. So, the tree you are presented with may not be optimal. For tuning +variables, see the hint_* variables in the last chapter. +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch3.html b/doc/menu.html/ch3.html new file mode 100644 index 0000000..673b251 --- /dev/null +++ b/doc/menu.html/ch3.html @@ -0,0 +1,1249 @@ + + + + + + + + +Debian Menu System - The menu file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 3 - The menu file +

+ +
+ +
+ +

3.1 Location

+ +

+Packages-provided menu files should be in /usr/share/menu/, unless +the menu files are actually executable binaries, in which case they go in +/usr/lib/menu/. System-local menu files should be in +/etc/menu/. User-specific menu files should be in +~/.menu/ +

+ +
+ +

3.2 Syntax

+ +

+The format is: +

+ +
+     ?package(package[,package2,...]): \
+        field1="value1"\
+        field2="value2"\
+
+ +

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

+ +
+     ?package(gnumeric):\             specifies what packages need to be installed
+                                      multiple requirements should be separated by
+                                      comma
+       needs="X11"\                   what kind of environment this command expects
+       section="Applications/Office"\ in what section this menu entry should be
+       title="Gnumeric"\              the title of the menu entry
+       command="gnumeric" \           the command to run
+       hints="Gnome,Spreadsheets" \   some hints about menu placement.
+       icon="/usr/share/pixmaps/gnumeric.xpm"  the path to the icon to use.
+
+ +

+A number sign ("#") can be used to include comments. An entry must +be terminated by a newline; however you can use a backslash to escape a +newline. +

+ +

+Values must be quoted with ", and meta-characters (", backslash, +newline) must be escaped with a backslash. +

+ +

+You can include several entries in the same file. +

+ +

+The file must be encoded in 7-bit ASCII. This is necessary to accomodate +window managers that do not support 8-bit encodings. However the translations +are not limited in encoding. +

+ +

+?package(...) contains a comma-separated list of packages that +need to be installed for the menu entry to be displayed. That should include +the package containing the menu file and any packages necessary to run the +command not depended on by the package nor essential. Users can use +pseudo-package names starting with "local." which are +assumed to be always installed. +

+ +

+The fields needs, section, title and +command are mandatory. Other fields are optional. Custom fields +are supported, so you can add new fields for you own purpose. If a field is +specified multiple times in a menu entry, the last instance will be used. +

+ +
+ +

3.3 The title field

+ +

+The title must follow the following requirements: +

+
    +
  1. +

    +It must be short. There is an optional longtitle field for users +that want longer titles. +

    +
    2. +
+
    +
  1. +

    +It must be properly capitalized. Use Emacs and not emacs. +

    +
    2. +
+
    +
  1. +

    +It must be unique. Two entries must not have the same title. +

    +
    2. +
+ +
+ +

3.4 The needs field

+ +

+The following needs are documented for use in the Debian menu. +

+
    +
  1. +

    +X11: if this program runs under X11. +

    +
    2. +
+
    +
  1. +

    +text: if it runs under a terminal. X11 window managers will spawn +an X terminal emulator. +

    +
    2. +
+
    +
  1. +

    +vc: if it runs under a linux virtual console but not under a X +terminal emulator. +

    +
    2. +
+
    +
  1. +

    +wm: if it is a X11 window manager. The current window manager +will exec(2) this program to avoid "Another window manager is +running" errors. +

    +
    2. +
+ +

+A menu manager can use a special needs value reflecting the menu +manager name for menu entries that must only be displayed in this menu manager. +Examples include fvwm modules, dwww menu entries. +

+ +

+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 with an +hard-coded call to an X terminal emulator, because this would defeat the +configuration mechanism of menu that allow to choose which window manager is +called. +

+ +

+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 (or rxvt). +However, two entries are not allowed to have the same title. The title must be +unique. +

+ +
+ +

3.5 The section field

+ +

+The section field holds a slash-separated list of hierarchical +sections components. +

+ +

+The authoritative list of Debian's menu structure is maintained in the +Debian Menu sub-policy document which is part of the Debian Policy package. +The current menu structure was drafted in 2006 by Linas Zvirblis with input +from the debian-devel mailing list. +

+ +

+The menu structure below is included only for convenience and is not +authoritative. If it disagrees with the structure in the Debian Menu +sub-policy, please send a wishlist bug to the menu package. +

+ +

+Packages must be placed in leaf sections. Please do not put your +packages into any other sections. +

+
+
Applications
+
+

+Normal applications +

+
+
Accessibility
+
+

+Tools to aid people with disabilities or for machines lacking usual input +devices. +

+ +

+Examples: gok, yasr, dasher. +

+
+
+
+
Amateur Radio
+
+

+Anything relating to HAM radio. +

+ +

+Examples: baken, hamsoft, twlog +

+
+
+
+
Data Management
+
+

+Interactive database programs, collection managers, address books, bibliography +tools, etc. +

+ +

+gaby, alexandria, mdbtools +

+
+
+
+
Editors
+
+

+Editors, other than office word processors, for text-based information. +

+ +

+Examples: ksubtile, nano, hexedit +

+
+
+
+
Education
+
+

+Educational and training softwares. +

+ +

+Examples: gtypist, gcompris, quiz +

+
+
+
+
Emulators
+
+

+Software that allows you to run non-native software or more than one OS at a +time. +

+ +

+Examples: wine, dosemu, qemu +

+
+
+
+
File Management
+
+

+Tools for file management, archiving, searching, CD/DVD burning, backup, etc. +

+ +

+Examples: file-roller, mc, baobab +

+
+
+
+
Graphics
+
+

+2D and 3D graphics manipulation software. +

+ +

+Examples: gimp, inkscape, imagemagick +

+
+
+
+
Mobile Devices
+
+

+Software that allows you to interface with mobile devices (phones, PDAs, etc.). +

+ +

+Examples: kandy, gnokii, gnome-pilot +

+
+
+
+
Network
+
+

+Network related software. This is a three-level section, do not put entries +directly here. +

+
+
Communication
+
+

+Mail, USENET news, chat, instant messaging, IP telephony, video conferencing +software, etc. +

+ +

+Examples: xchat, gaim, mutt +

+
+
+
+
File Transfer
+
+

+File transfer software such as download managers, FTP clients, P2P clients, +etc. +

+ +

+Examples: amule, gftp, d4x +

+
+
+
+
Monitoring
+
+

+Network monitoring software +

+ +

+Examples: gip, ettercap, iptstate +

+
+
+
+
Web Browsing
+
+

+Web browsers, tools for offline browsing, etc. +

+ +

+Examples: elinks, epiphany-browser, webhttrack +

+
+
+
+
Web News
+
+

+Web feed (RSS, Atom, etc.) and podcast aggregators. +

+ +

+Examples: akregator, kitty, liferea +

+
+
+
+
+
+
Office
+
+

+Office suites, word processors, spreadsheets, CRM, ERP, financial sofware, etc. +

+ +

+Examples: openoffice.org, tinyerp-client, gnucash +

+
+
+
+
Programming
+
+

+IDEs, debuggers, etc. +

+ +

+Examples: anjuta, gdb, eclipse +

+
+
+
+
Project Management
+
+

+Timetable managers, group task trackers, bug tracking software, etc. +

+ +

+Examples: planner, bugzilla, gnotime +

+
+
+
+
Science
+
+

+Scientific and engineering-related software. +

+
+
Astronomy
+
+

+Astronomy-related software. +

+ +

+Examples: celestia, spacechart, stellarium +

+
+
+
+
Biology
+
+

+Biology-related software. +

+ +

+Examples: arb, ncbi-tools-x11, seaview +

+
+
+
+
Chemistry
+
+

+Chemistry-related software. +

+ +

+Examples: chemtool, kalzium, xdrawchem +

+
+
+
+
Data Analysis
+
+

+Software designed for processing, extracting, and presenting generic scientific +data. +

+ +

+Examples: fityk, ygraph, mn-fit +

+
+
+
+
Electronics
+
+

+Circuit design tools, simulators and assemblers for microprocessors, etc +

+ +

+Examples: geda, gnucap, tkgate +

+
+
+
+
Engineering
+
+

+CAD, UML tools, diagram-drawing and other engineering-related software. +

+ +

+Examples: tcm, dia, qcad +

+
+
+
+
Geoscience
+
+

+Geoscience-related software. +

+ +

+Examples: earth3d, qgis, therion +

+
+
+
+
Mathematics
+
+

+Mathematics-related software. +

+ +

+Examples: gcalctool, snappea, xeukleides +

+
+
+
+
Medicine
+
+

+Medicine-related software. +

+ +

+Examples: mssstest, gnumed-client, xmedcon +

+
+
+
+
Physics
+
+

+Physics-related software. +

+ +

+Examples: kxterm, ifrit, paw +

+
+
+
+
Social
+
+

+Social sciences-related software. +

+ +

+Examples: gnomesword, hanzim, bibletime +

+
+
+
+
+
+
Shells
+
+

+Various shells to be used inside a terminal emulator. +

+ +

+Examples: bash, ksh, zsh +

+
+
+
+
Sound
+
+

+Sound players, editors, and rippers/recorders. +

+ +

+Examples: beep-media-player, grip, audacity +

+
+
+
+
System
+
+

+System related software. +

+
+
Administration
+
+

+Administrative and system configuration utilities, also tools for personal user +settings. +

+ +

+Examples: gnome-control-center, configure-debian, gksu +

+
+
+
+
Hardware
+
+

+Tools for manipulating specific hardware, especially non-standard laptop +hardware. +

+ +

+Examples: toshutils, nvclock-gtk, nvtv +

+
+
+
+
Language Environment
+
+

+This section is reserved for language-env as a special case. +

+
+
+
+
Monitoring
+
+

+System information and monitoring tools, log viewers, etc. +

+ +

+Examples: top, hal-device-manager, gtkdiskfree +

+
+
+
+
Package Management
+
+

+Package managers and related tools. +

+ +

+Examples: aptitude, deborphan, smartpm +

+
+
+
+
Security
+
+

+Security, cryptography and privacy related software, antiviruses, tools to +track and report bugs, etc. +

+ +

+Examples: gpgkeys, bastille, avscan +

+
+
+
+
+
+
Terminal Emulators
+
+

+Graphical terminal emulators. +

+ +

+Examples: xterm, gnome-terminal, rxvt +

+
+
+
+
Text
+
+

+Text oriented tools like dictionaries, OCR, translation, text analysis +software, etc. +

+ +

+Examples: kdrill, stardict, turkey +

+
+
+
+
TV and Radio
+
+

+TV-in, TV-out, FM radio, teletext browsers, etc. +

+ +

+Examples: gradio, gatos, alevt +

+
+
+
+
Viewers
+
+

+Software for viewing images, documents and other (non-video) media. +

+ +

+Examples: gqview, evince, gthumb +

+
+
+
+
Video
+
+

+Video players, editors, and rippers/recorders. +

+ +

+Examples: istanbul, totem, kino +

+
+
+
+
Web Development
+
+

+Software for web site editing, web programming, and site administration. +

+ +

+Examples: bluefish, screem, gphpedit +

+
+
+
+
+
+
Games
+
+

+Games and recreations +

+
+
Action
+
+

+Games that involve a lot of action and require fast reflexes. +

+ +

+Examples: xsoldier, supertux, xmoto +

+
+
+
+
Adventure
+
+

+Role playing and adventure games, interactive movies and stories, etc. +

+ +

+Examples: beneath-a-steel-sky, egoboo, kq +

+
+
+
+
Blocks
+
+

+Tetris-like games involving falling blocks. +

+ +

+Examples: crack-attack, frozen-bubble, netris +

+
+
+
+
Board
+
+

+Games played on a board. +

+ +

+Examples: phalanx, xshogi, xboard +

+
+
+
+
Card
+
+

+Games involving a deck of cards. +

+ +

+Examples: pysol, ace-of-penguins, xpat2 +

+
+
+
+
Puzzles
+
+

+Tests of ingenuity and logic. +

+ +

+Examples: xmpuzzles, sgt-puzzles, enigma +

+
+
+
+
Simulation
+
+

+Simulations of the real world in all detail and complexity. +

+ +

+Examples: flightgear, torcs +

+
+
+
+
Strategy
+
+

+Games involving long-term strategic thinking. +

+ +

+Examples: wesnoth, widelands, netpanzer +

+
+
+
+
Tools
+
+

+Server browsers, configurators, editors, and other game-related tools that are +not games themselves. +

+ +

+Examples: xqf, crystalspace +

+
+
+
+
Toys
+
+

+Amusements, eye-candy, entertaining demos, screen hacks (screensavers), etc. +

+ +

+Examples: xdesktopwaves, xphoon, xpenguins +

+
+
+
+
+
+
Help
+
+

+programs that provide user documentation +

+ +

+Examples: debian-reference, apt-howto, dhelp +

+
+
+
+
Screen
+
+

+Programs that affect the whole screen. +

+
+
Saving
+
+

+Tools for blanking the screen. Entries of screen hacks and configuration GUIs +should go to other appropriate sections. +

+ +

+Examples: xscreensaver, xlockmore +

+
+
+
+
Locking
+
+

+Tools for locking the screen. +

+ +

+Examples: xscreensaver, xlockmore +

+
+
+
+
+
+
Window Managers
+
+

+X window managers. +

+ +

+Examples: fluxbox, metacity, waimea +

+
+
+
+
FVWM Modules
+
+

+FVWM-based window manager modules. As only modules related to the running +window-manager are displayed, do not create subsections for specific +window-managers. +

+ +

+Examples: fvwm, fvwm-gnome, fvwm95 +

+
+
+
+
Window Maker
+
+

+This section is reserved for wmaker as a special case. +

+ +

+All wmaker specific entries must go here. +

+
+
+ +

+Users wanting to access some menu entries quickly can also put them in the root +menu. This is done by using section="/". Package-provided +menu entries must never use this feature. +

+ +
+ +

3.6 The command field

+ +

+The command field holds the command that should be executed when the menu entry +is selected. Commands will be executed with sh -c using +

+ +
+     execl("/bin/sh","sh","-c",command)
+
+ +

+or the equivalent. +

+ +
+ +

3.7 The icon field

+ +

+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. Icons should generally be installed in the +directory /usr/share/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. +
+
    +
  1. +

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

    +
    2. +
+
    +
  1. +

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

    +
    2. +
+ +

+You can provide both 16x16 and 32x32 pixels icons using the variables icon16x16 +and icon32x32 so that the user can configure menu to use one or the other. +

+ +

+If you, as a system administrator, don't like the icons in the menus, simply +change the icon() function from the file +/etc/menu-methods/menu.h, and run update-menus. +

+ +
+ +

3.8 The hints field

+ +

+Hints are used to help menu structure generated menus in a more optimal way. +For example: +

+ +
+     ?package(emacs20):\
+       needs="x11"\
+       hints="Big,Expert,Featureful" \
+       section="Applications/Editors"\
+       title="Emacs 20"\
+       command="/usr/bin/emacs20"\
+       icon=/usr/share/emacs/20.3/etc/emacs.xbm
+
+ +

+The above hints will tell menu to consider grouping +emacs together with other editors that are marked similar. For +example, if vi on your system has a hints="Small,Expert" +definition, and there are too many entries in the +/Applications/Editors menu entry, then menu will consider creating +a /Applications/Editors/Expert submenu, and put both +vi and emacs in it. (Of course, only if you have +hint_optimize=true in your /etc/menu-methods/menu.h +file). +

+ +
+ +

3.9 Entries for menu sections.

+ +

+It is possible to add entries for menu sections, but it is not mandatory since +section entries are created automatically. However, this allows to specify +fields for sections like icon and sort. The syntax +for menu sections entries is the same as for regular entries, the +section field holding the name of the parent section. For example +

+ +
+     ?package(local.games): needs="text" title="Games" section="/" sort="001"
+
+ +

+will sort Games first. +

+ +
+ +

3.10 Fvwm's task and title bars

+ +

+The problem with the stuff in the task bar is that all items are displayed all +of the time. So, if 1500 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 task bar +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 (as a local +system administrator) 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"
+
+ +

+(Of course regular users (not system administrators) can also specify +`buttonfiles' in their ~/.menu/ directory). +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch4.html b/doc/menu.html/ch4.html new file mode 100644 index 0000000..d793f51 --- /dev/null +++ b/doc/menu.html/ch4.html @@ -0,0 +1,145 @@ + + + + + + + + +Debian Menu System - What packages with applications should do + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 4 - What packages with applications should do +

+ +
+ +

4.1 Providing a menu file

+ +

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

+ +
+ +

4.2 Adding a hook for dpkg in your packages

+ +

+The postinst script and the postrm script of the +package should include the line +

+ +
+      if test -x /usr/bin/update-menus; then update-menus; fi
+
+ +

+If you are using debhelper, the program +dh_installmenu can do it for you. +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch5.html b/doc/menu.html/ch5.html new file mode 100644 index 0000000..78df396 --- /dev/null +++ b/doc/menu.html/ch5.html @@ -0,0 +1,226 @@ + + + + + + + + +Debian Menu System - What packages with menu managers should do + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 5 - What packages with menu managers should do +

+ +
+ +

+Each package containing a menu manager (i.e., a program that can +display a menu) should provide a script or program in +/etc/menu-methods/ that can read the menu files. This script will +be executed by update-menus, which will feed the menu entries to +be installed to your script via standard input (stdin). +

+ +

+The scripts in /etc/menu-methods/ should be configuration files, +so the user can tune the behaviour of the script, and they must always include +the /etc/menu-methods/menu.h configuration file at the beginning +with the command !include menu.h For the same reason, scripts in +/etc/menu-methods/ are requested to use the following configurable +functions: title() for the title (in place of +$title), icon() for the icon (in place of +$icon), term() for running text command +under X11. sections_translations() for the list of +translations of sections name available. This later one is only defined if you +!include lang.h +

+ +

+Good examples for these scripts for nearly all Debian window managers are +included in the menu package in +/usr/share/doc/menu/examples. Note that while working on your +script, you can use the tricks described in "The internals of the menu +package", section "The update-menus program", to run just your +script, instead of having update-menus run all scripts (can save quite a lot of +time). +

+ +

+This script should not be executable in the package. Instead the +postinst should add the execute bit and then run +update-menus (if it is executable). +

+ +

+Similarly, the postrm script when called with option ``remove'' +should remove the execute bit and run update-menus (if it is +executable). +

+ +

+Here is an example of such a postrm script using sh: +

+ +
+       #!/bin/sh
+       set -e
+       inst=/etc/menu-methods/#PACKAGE#
+       case "$1" in
+          remove)
+             if [ -f $inst ]; then
+                     chmod a-x $inst
+                     if [ -x /usr/bin/update-menus ]; then update-menus ; fi
+             fi
+          ;;
+          purge)
+              #remove the files that install-menu creates:
+              rm -rf /var/lib/foo-wm/menu
+          ;;
+          upgrade);;
+          *)
+              echo "postrm called with unknown argument \`$1'" >&2
+              exit 0
+          ;;
+       esac
+
+ +

+And here is a good example for a postinst script: +

+ +
+       #!/bin/sh
+       set -e
+       inst=/etc/menu-methods/#PACKAGE#
+       if [ -f $inst ]; then
+           chmod a+x $inst
+           if [ -x /usr/bin/update-menus ]; then
+               update-menus
+           fi
+       fi
+
+ +

+If you are using debhelper, the program +dh_installmenu can help you do it. +

+ +

+Please, do not make your package depend on the menu package! The +preferred way of telling dpkg that your wm can cooperate with menu is: +

+ +
+        Suggests: menu
+
+ +

+Please only consider using "depends" if you feel providing reasonable +defaults for systems without menu will make life very difficult +for you. +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch6.html b/doc/menu.html/ch6.html new file mode 100644 index 0000000..fcfa7b9 --- /dev/null +++ b/doc/menu.html/ch6.html @@ -0,0 +1,224 @@ + + + + + + + + +Debian Menu System - How a user can override the menus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 6 - How a user can override the menus +

+ +
+ +
+ +

6.1 Configuring the menus

+ +

+Users can specify their own menu entries in the ~/.menu directory. +The files can have an arbitrary file name as long as the new syntax for the +menu entries is used. They should start with either +

+ +
+       ?package(installed-package):
+
+ +

+or +

+ +
+       ?package(local.mystuff):
+
+ +

+if it's something that isn't ``debian-officially'' installed. (Any ``package'' +that starts with ``local.'' is considered installed.) +

+ +

+If users want to have their own menu methods, they should create a +~/.menu-methods directory and put all their menu methods in it. +(If ~/.menu-methods exists, /etc/menu-methods will +not be searched when a user runs update-menus). +

+ +

+A system administrator should place system-wide menu entries in +/etc/menu (not in /usr/share/menu/package, since +these files will probably be overwritten by a package upgrade). +

+ +
+ +

6.2 Specifying that a menu entry should not be displayed

+ +

+If a user wants to remove the entries of package from the system +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. A system administrator can +remove menu entries system-wide with +

+ +
+       echo -n  > /etc/menu/package
+
+ +
+ +

6.3 Including other files

+ +

+Historical comment by Joost: +

+ +

+More out of curiosity than anything else, I recently read the KDE mailing +list. In it I saw some discussion about how good the Debian menu system is +(whow, thanks, guys!), but one person found a missing feature: s/he said you +couldn't include other files in the user menu files. Well, actually, it was +already possible, but not very well documented. +

+ +

+To include the contents of the file /usr/share/menu/somefile, add +this to your menu file: +

+ +
+     !include /usr/share/menu/somefile
+
+ +

+Apart from that, it is of course possible to make the menu entry file +executable (chmod a+x ~/.menu/package), and do something like +

+ +
+     #!/bin/sh
+     cat  /usr/share/menu/somefile
+     sed -e  "/unwanted_entry/s/?package(/?package(notinstalled./" \
+          /usr/share/menu/someotherfile
+
+ +

+to get the same effect, with the added flexibility of being able to filter out +unwanted lines. +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch7.html b/doc/menu.html/ch7.html new file mode 100644 index 0000000..3cc602c --- /dev/null +++ b/doc/menu.html/ch7.html @@ -0,0 +1,821 @@ + + + + + + + + +Debian Menu System - The internals of the menu package + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 7 - The internals of the menu package +

+ +
+ +
+ +

7.1 The update-menus program

+ +

+On startup, update-menus checks the file /var/run/update-menus.pid +and the pid in it. If there's an update-menus process with that +pid it kills it. If /var/lib/dpkg/lock exists, it checks to see +if dpkg supports triggers. If so, it uses dpkg-trigger to trigger a real +update-menus run later. Otherwise, it forks to background and returns control +to dpkg. The background process checks the /var/lib/dpkg/lock +file approx. every two second until the file's gone. +

+ +

+Once it's decided to run, whether in the background after dpkg exits, or in the +foreground when used with a trigger-capable dpkg, update-menus +reads the menu-entry files in the following directories: +/etc/menu, /usr/lib/menu, +/usr/share/menu, /usr/share/menu/default. (if a user +runs update-menus, it will add ~/.menu to the front +of that list). For every menu entry line in each file it checks if the +corresponding package is installed. The menu entries of all packages marked as +installed by dpkg are added together in one big buffer that is kept in memory +(exception: executable menu entry files are executed, and stdout is placed in +the buffer). +

+ +

+Once it's read all menu entry files, update-menus starts all +executable scripts in /etc/menu-methods/, hands the scripts the +previously created buffer via stdin. (If update-menus is run by a +user, it will first try to run the scripts in ~/.menu-methods, and +only if that directory doesn't exist, it will run the scripts in +/etc/menu-methods). +

+ +

+Note that as an aid to debugging, one can use +

+ +
+     update-menus --stdout > /tmp/menu-stdin
+
+ +

+and then view the file /tmp/menu-stdin to see exactly what +update-menus handed the menu-methods on their stdin. +

+ +

+This may also be useful for people writing /etc/menu-method/* +scripts: Running update-menus every time you changed something in +the script may be quite time-consuming. So, it's much easier to run +update-menus --stdout once, and then run +

+ +
+       /etc/menu-methods/mymethod < /tmp/menu-stdin
+
+ +

+(and, if that also takes too long, just try editing /tmp/menu-stdin, and +removing 90% or so of all entries) +

+ +
+ +

7.2 The install-menu program

+ +

+The files /etc/menu-methods/$wm are executable config files that +start with the line +

+ +
+       #!/usr/bin/install-menu
+
+ +

+and thus start that program, handing it the configuration file for the specific +window manager in the first command line argument. This configuration consists +of: +

+
    +
  1. +

    +the compatibility mode ("menu-1" or "menu-2"). +

    +
    2. +
+
    +
  1. +

    +where the various files should be stored/read. +

    +
    2. +
+
    +
  1. +

    +what "needs" are supported, and what wrapper files should be used for +each "type". +

    +
    2. +
+
    +
  1. +

    +how to remove the generated menu files. +

    +
    2. +
+ +

+See /usr/share/doc/menu/examples/ of the menu package for more +comments. +

+ +

+Options to install-menu: +

+ +
+       --remove  Remove the menu files instead of generating them.
+       --verbose Output outline of operations that are performed.
+
+ +

+Some window managers don't support an `include'-like statement in their +system.*rc files (like m4 or cpp +preprocessing); they cannot read the menudefs.hook file generated +by install-menu from their system.*rc config file. To still be +able to use them, install-menu will copy the file +$path/$examplercfile to $path/$rcfile (with +$examplercfile and $rcfile defined in the +install-menu config file, and $path either the +$rootprefix or ${HOME}/$userprefix, depending on +whether root or user executed the file.), and replace all occurrences of +``install-menu-defs'' with the $genmenu file it just generated. +

+ +

+As an example, consider the following: +examplercfile=system.foo-wm-example, +rcfile=system.foo-wm, genmenu=menudefs.hook and +rootprefix=/var/lib/foo-wm/menu. Now, if +install-menu gets run, it will first generate the file +/var/lib/foo-wm/menu/menudefs.hook. Next, it will line-by-line +read the file /var/lib/foo-wm/menu/system.foo-wm-example and copy +its contents to /var/lib/foo-wm/menu/system.foo-wm, replacing +every occurrence of the string install-menu-defs with the contents +of the file /var/lib/foo-wm/menu/menudefs.hook. +

+ +

+To activate the file copying in this way, simply define the +$examplercfile and $rcfile variables in the +install-menu configuration file (for example, see +/etc/menu-methods/fvwm), and make sure there is a +$path/$examplercfile ($path being either +$rootprefix, or $userprefix.) +

+ +

+If you are writing a menu method, you can use the following to make debugging +it somewhat more easily: +

+
    +
  1. +

    +use update-menus --stdout > /tmp/menu-stdin to create a list of +menu entries in /tmp/menu-stdin and then +

    +
    2. +
+
    +
  1. +

    +you can run just your menu-method with (if it's called wm): +

    + +
    +       ./wm -v < /tmp/menu-stdin
+
    +
    2. +
+ +
+ +

7.3 The install-menu config script definitions

+ +

+The menu-methods in /etc/menu-methods/* are basically made up of a +lot of ``tag=string'' definitions, telling install-menu how to +generate a system.${wm}rc script. This way you can tune the look +of generated system.${wm}rc to your needs. +

+ +

+In the following, something like +

+ +
+       treewalk="c(m)"
+
+ +

+means that the treewalk variable by default has the value "c(m)". +

+ +

+For examples of what these scripts can look like, see +/usr/share/doc/menu/examples/*. +

+
+
compat="menu-1"
+
+

+Two mode are defined: +

+
+
"menu-1"
+
+

+menu directives are terminated by an end-of-line character. +

+
+
+
+
"menu-2"
+
+

+menu directives are terminated by a semicolon character. +

+
+
+ +

+This must be just after the !include "menu.h" directive +so that menu.h can use its own compat mode. +

+
+
+
+
outputencoding="UTF-8"
+
+

+Set the encoding used for output files. Use iconv --list to get +the list of supported encoding. Useful values include "UTF-8" and +"ISO-8859-1". The special value "LOCALE" means that the +current locale encoding will be used. If set to an empty string, no +translations are performed. This is the default. +

+
+
+
+
outputlanguage=""
+
+

+If set to "C" automatic translations will be disabled. Note that you +can still use translate() to perform explicit translation. +

+
+
+
+
supported
+
endsupported
+
+

+Between the supported and endsupported keywords you +define what "needs" are supported by this window manager. So, the +following is an example for a wm that supports both needs=x11 and needs=text: +

+ +
+       function q($s) = "\"" esc($s,"\\\"") "\""
+       supported
+         x11 =" ShowEntry(" q(title()) ", " q($command) ")"
+         text=" ShowEntry(" q(title()) ", " q(term())   ")"
+       endsupported
+
+ +

+For the variable substitution (and functions, not shown above), see the next +paragraph. In the above example, you'll notice that for the menu entries that +"need=text", the term() function is used. This is a user-supplied +function that will run $command in a X terminal emulator. Also, as X11 is +higher up in the supported list above than text, a package that supplies both a +"needs=X11" and a "needs=text" entry will have the +needs=X11 entry installed, in favour of the needs=text entry. You can continue +lines on the next line with a backslash ("\"), but make sure you +don't add any spaces after the backslash. +

+
+
+
+
startmenu=""
+
endmenu=""
+
submenutitle=""
+
+

+These define what to print for the beginning/end of a menu, and how to the +print a menu entry that pops up another menu. They are substituted the same +way as the "supported" stuff is; see next paragraph. +

+
+
+
+
treewalk="c(m)"
+
+

+This string defines in what order to dump the $startmenu, +$endmenu, and $submenutitle (and its 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)" +

+
+
+
+
genmenu=""
+
+

+The menu file to generate (usually something like +system."$wm"rc). The file itself may depend on the +level or title that is currently being worked on, like +

+ +
+         genmenu="/subdir/" replacewith($section," ","_") "/rc.menu"
+
+ +

+(Substitution works just like in the supported stuff, see above). Note that +the files made this way are truncated upon opening, so if you have a genmenu +like the example above, then your endmenu= will override the +startmenu stuff (but you probably only need one of the two anyway). +

+
+
+
+
rootsection="/Debian"
+
+

+the prefix every $section variable gets. +

+
+
+
+
prerun=""
+
postrun=""
+
+

+The commands to run before and after, respectively, the actual generation of +the menudefs.hook (genmenu) file. Commands will be executed by +sh. Example: +

+ +
+       prerun="rm -rf " prefix() "/*"
+       postrun="killall -USR1 fvwm2"
+
+ +

+(Substitution works just like the supported stuff, see below). +

+
+
+
+
preruntest=""
+
+

+Just like prerun, but if the return value of the command is non-zero, menu will +quit. +

+
+
+
+
also_run=""
+
+

+If non-zero, install-menus will, after generating the output files, also load +the file also_run, and use the new assignments to treewalk, genmenu, etc. to +generate more output. This second time, variables like prerun and +all of the hint stuff are ignored. +

+
+
+
+
removemenu=""
+
+

+The command to run when the menu-method is invoked with the option +--remove. This should remove all the autogenerated menu files. +If this option is not present, then install menu will remove +genmenu if it is a constant string and rcfile if it +is defined, and try to remove prefix() if it is empty. +

+
+
+
+
onlyrunasroot=false
+
onlyrunasuser=false
+
+

+If onlyrunasroot is set to true, install-menu will +quit silently when run as a user. Similarly for onlyrunasuser. +onlyrunasroot is deprecated since it is simpler to just not +define userprefix. On the other hand, +onlyrunasuser might be needed if you use rcfile since +rootprefix is used as a fallback location for the template. +

+
+
+
+
preoutput="#Automatically generated file. Do not edit (see /usr/share/doc/menu/html)\n\n"
+
postoutput=""
+
+

+Text to put at the beginning resp. end of the generated file ($genmenu). +

+
+
+
+
command=""
+
+

+A command to run instead of install-menus. This command used to +be needed to get around limitations due to compatibility stuff. But that +compatibility with pre menu-1 stuff has been dropped, and isn't needed any +more. +

+ +

+Example: +

+ +
+       command="cat > /tmp/menu-stdin"
+
+
+
+
+
hotkeyexclude=""
+
+

+Keys not to use for hotkey generation. You can use the same variables and +functions here as in for example the startmenu sections. +

+ +

+Example: +

+ +
+       hotkeyexclude="q" $section
+
+
+
+
+
hotkeycase="insensitive"
+
+

+can be either "insensitive" or "sensitive". Determines +whether the hotkeys can be of mixed case (fvwm2 reads the hotkeys +case-insensitive, pdmenu case-sensitive). In case of the titles +"Xa" and "xb", hotkey case-insensitive will generate +"X" and "b", whereas case-sensitive would generate +"X" and "x". +

+
+
+
+
sort=$sort ":" $title
+
+

+Entries within one menu will be alphabetically sorted by whatever sort returns. +So, if you do sort=ifelse($command, "1", +"0"):$title, then all submenus will appear above the commands +in a submenu. (A submenu always has $command=""). Or, +as Joey Hess writes: +

+ +
+       You can add another field to the menu items, with whatever name you like,
+       let's say it's called priority. Then add this line to
+       /etc/menu-methods/*:
+       
+       sort=ifelse($priority, $priority, "9")
+       
+       This has the result of sorting things so items with a low priority sort to the
+       top, and items with no priority default to priority 9 and sort to the bottom.
+       
+       (Note that it compares the strings alphabetically, not numerically.)
+
+
+
+
+
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). If it is not defined, the +menu-method will be skipped when run as root. +

+
+
+
+
userprefix=""
+
+

+As rootprefix, but when running as user. userprefix is relative +to the user home directory, unless it start with 2 slashes, in which case it is +treated as an absolute path. If it is not defined, the menu-method will be +skipped when run as a user. +

+
+
+
+
hint_optimize=false
+
+

+If set to true, menu will try to generate an `optimal' tree, using the +variables below. If set to false, menu will keep the sections as they are +specified in the menu entry files (and ignore any hint stuff). +

+
+
+
+
hint_nentry=6
+
+

+Optimal number of entries in a submenu. It's a float, so you can set it to 5.5 +if you cannot decide between 5 and 6. Also, values less than 3 probably don't +work very well at the moment. +

+
+
+
+
hint_topnentry=5
+
+

+Same as hint_nentry, but for the top level menu. Often here are other entries, +added by the window-manager itself (like Exit, Xterm, whatever) that menu +doesn't know about, so that you may want to instruct menu to put less entries +in the top level menu. +

+
+
+
+
hint_mixedpenalty=15.0
+
+

+Penalty for `mixed' menus. Mixed menus are those with both submenus and direct +commands in them. +

+
+
+
+
hint_minhintfreq=0.1
+
+

+Minimal relative frequency for the hints before they are considered. Internal +variable to speed up the tree generation. If you find menu slow, increase this +value (to, say 0.2 or 0.3). +

+
+
+
+
hint_mlpenalty=2000
+
+

+`max local penalty', while evaluating the possible trees, menu gives +`penalties' for submenus that don't contain the desired number of submenus. +The penalty is sqrt(n_entry_opt-n_entry), and eventually will be calculated as +a sum of all nodes. But to speed things up, menu will discard possibilities in +which any node has a `local' penalty of more than hint_mlpenalty. Increase +this value if you think menu is overlooking your favorite tree (also decrease +minhintfreq), decrease this value if you think menu is wasting too much time. +Because of hint_max_ntry, the influence of this variable is nearly zero +nowadays. +

+
+
+
+
hint_max_ntry=4
+
+

+menu will recursively, for each node, try the hint_max_ntry best local +menu-divisions. +

+
+
+
+
hints_max_iter_hint=5
+
+

+The search for what hints to use in one menu is rather expensive. But due to +the way things are sorted, menu seems to always find the `best' match in the +first 2% of iterations. Thus, a way to speed things up is simply to cut of +menu searching after `some' iterations are done. This value controls this, and +limits the number of iterations to +5+hint_max_iter_hint*number_of_possible_hints. Set this value to negative to +disable this. +

+
+
+
+
hint_debug=false
+
+

+Set to true if you want to see loads and loads of debug output. +

+
+
+ +
+ +

7.4 Hints, tree optimization

+ +

+The hints actually work in a rather strange way: when +hint_optimize=true then all $section elements are +added to the specified $hints variable, and the order +(/Applications/Editors or /Editors/Applications) of +the resulting hints is completely ignored. Then, the hints for each menu entry +are handed to the optimization routine, which will calculate a reasonable tree +for those hints. That tree must comply with the following: +

+ +

+When a user looks for a program "Program" with, say, hints +"Good,Bulky,Heaven", then, while walking through the tree, it should +at every node visited be clear for the user what submenu to select (or the menu +should have "Program" directly in it). So, the top-level menu may +look like +

+ +
+       Good
+       Hell
+       Microsoft
+
+ +

+because then a searcher for a menu entry with hints +"Good,Bulky,Heaven" will know to select the submenu "Good". +The toplevel menu may not look like +

+ +
+       Good
+       Hell
+       Heaven
+
+ +

+as now it isn't clear whether to visit the Good or the Heaven submenu. +

+ +

+That rule allows usually for many different trees, and the task of the +optimization procedure is to select, in a finite amount of time, the tree that +best matches the user's desire about the optimum number of menu entries. +

+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/ch8.html b/doc/menu.html/ch8.html new file mode 100644 index 0000000..caa542f --- /dev/null +++ b/doc/menu.html/ch8.html @@ -0,0 +1,665 @@ + + + + + + + + +Debian Menu System - Variables and functions in the install-menu scripts + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +
Chapter 8 - Variables and functions in the install-menu scripts +

+ +
+ +

+The supported "needs" definitions and "startmenu=", +"endmenu=" and "submenutitle=" are interpreted as follows: +

+ +
+ +

8.1 String constants

+ +

+Anything inside double quotes ("") is interpreted as a string, and is +written verbatim to the output file. Escape sequences like \n, \t, ... will +be replaced with their C expansions (but currently \0xx octal escape sequences +are not supported). +

+ +
+ +

8.2 Variables

+ +

+Anything matching $[a-z,A-Z,_]* is interpreted as a variable, and the +corresponding definition from the menu entry is substituted. +

+ +
+ +

8.2.1 Special variables

+ +

+The following variables are treated in a special way by install-menus, either +because they are used for other purposes too, or because they are modified by +install-menus (the ones marked with a "!" are modified by +install-menus). +

+
+
needs:
+
+

+Used to determine whether the window manager supports this menu entry. +

+
+
+
+
command:
+
+

+If this is undefined, this menu entry is taken as defining a sub-menu. This +way you can specify icons of sub-menus. +

+
+
+
+
title!:
+
+

+Used for sorting (see section). For sub-menu entries (those with empty +command), this is initialised to the last part of the section. Please, keep +the title short (two words at maximum). The title is for people who already +know what program they want to start. See "longtitle" and +"description" below for longer descriptions. +

+
+
+
+
sort:
+
+

+Used for sorting (see section). To make sure an entry is at the beginning, use +something with a low ASCII number, like "$". For sorting at the end, +use "|" +

+
+
+
+
section!:
+
+

+Used to determine the section of the menu entry. The menu entries that have a +empty $command, ie those that define a submenu, have $title added to the end of +$section The menu entries that have a non-empty $command have their $section +modified to $section/$title, or $section/$sort:$title if $sort is defined. The +menu entries within one submenu are sorted according to $section. If you want +to retrieve the real section name, see the $basesection variable. +

+
+
+
+
basesection!:
+
+

+Used to contain the *real* section name. This is useful because $section will +be changed to $section/$title in special cases (see above). This causes a +problem when you want to do parent($section) because you won't get the real +parent section. Instead you can use $basesection, which will never contain the +title. +

+
+
+
+
hotkey!:
+
+

+Modified to reflect what install-menus thinks is the most suitable hotkey for +this menu entry. The hotkey= in the menu entry file is taken as a suggestion, +that could be overwritten if there is another entry with the same hotkey=. To +suggest two possible hotkeys for an entry use hotkey="ab", with +"a" being the most preferred hotkey. +

+
+
+ +
+ +

8.2.2 Preferred variables

+ +

+The following aren't special for install-menus, but it's nice (read: essential) +to use the same variables for the same things. So, I'll suggest some here. If +you want to invent new ones, please do so and mail them to me so that I can +include them here. +

+
+
icon:
+
+

+The location of the icon file for this menu entry. If you don't have an icon +file, just leave out the icon= in the menu entry. +

+
+
+
+
icon32x32:
+
+

+The location of a 32x32 icon file for this menu entry. +

+
+
+
+
icon16x16:
+
+

+The location of a 16x16 icon file for this menu entry. This allows users to +choose between 16x16 and 32x32 icon. +

+
+
+
+
longtitle:
+
+

+For people that like descriptive titles (about one line) It is probably best to +include this in your menu entries, while the window-managers don't (by default) +put it in the menus. That way, people who want descriptive titles can turn +them on, but others don't need to use them. +

+
+
+
+
description:
+
+

+An even longer description (about 5 lines). For example, a description of the +documentation in the dwww generated html pages. +

+
+
+ +
+ +

8.2.3 Suggested variables

+ +

+The following variables probably shouldn't appear often (or at all) in the menu +files supplied with packages. They are mostly intended for use by local system +managers. Nevertheless, it is advised that all Debian systems use the +following variable names: +

+
+
visible
+
+

+Some apps add entries to utmp the utmp file, so that "who" and +friends know they are running (this is especially true for xterms etc). If +$visible set (to anything other than "" or "none"), xterms +etc will not write logging info to utmp. (may not work for your window +manager). +

+
+
+
+
geometry
+
+

+For X apps, this will be the size of the (main) window that will be created +(units in either chars or pixels, depending on type of main window (xterm or +graphic)). If you as package maintainer want to use this, you should probably +think about setting this variable somewhere in an Xresources file. +

+
+
+ +
+ +

8.3 Functions

+ +

+Anything matching [a-zA-Z_]+ is taken as a function name, and an +error is generated if the function doesn't exist. The arguments of the +functions can be other functions, string constants or variables. +

+
+
prefix()
+
+

+returns the current prefix dir: either $rootprefix, or $HOME/$userprefix, +depending on who runs install-menu +

+
+
+
+
ifroot($rootarg, $userarg)
+
+

+if(getuid()==0) print $rootarg, else print $userarg +

+
+
+
+
print($arg)
+
+

+Same as just $arg; if $arg is empty, generate an error. +

+
+
+
+
nstring($n, $string)
+
+

+write $string $n times. So, nstring(3,"Aa") writes +"AaAaAa". (Useful in combination with level()). +

+
+
+
+
esc($arg1,$arg2)
+
+

+Print $arg1, but escape all occurrences of characters in $arg2 with a '\' +(thus, if arg1="hello", arg2="lo", print +"he\l\l\o"). +

+
+
+
+
escwith($arg1, $arg2, $arg3)
+
+

+Same as esc, but use $arg3 as escape sequence. +

+
+
+
+
escfirst($arg1, $arg2, $arg3)
+
+

+Same as escwith, but only escapes first occurrence of $arg2. +

+
+
+
+
cppesc($arg1)
+
+

+Escape anything that isn't a letter, number or _ with $<hex-ascii-code>. +So, for example, a '-' is replaced by '$2D'. This way, $arg1 can be used as a +#define in cpp. +

+
+
+
+
tolower($arg)
+
toupper($arg)
+
+

+Returns the argument set in lowercases resp uppercases. +

+
+
+
+
replacewith($s, $replace, $with)
+
+

+Search $s for occurrences of characters from string replace, and replace them +by the corresponding character in $with. Example: replacewith("hello +$world, %dir", "$% ", "123") returns: +"hello31world,32dir" +

+
+
+
+
replace($s, $replace, $with)
+
+

+Search $s for occurences of $replace and replace them with $with. Note that +the behaviour of this function is quite different than the replacewith() +function. +

+
+
+
+
ifempty($arg1, $arg2)
+
+

+If $arg1 is empty, print $arg2, otherwise print nothing. For compatibility, +$arg1="none" is interpreted as empty. +

+
+
+
+
ifnempty($arg1, $arg2)
+
+

+If $arg1 is not empty, print $arg2. For compatibility, the string +"none" is seen as empty. +

+
+
+
+
ifelse($arg1,$arg2,$arg3)
+
+

+If $arg1 is non-empty, print $arg2, otherwise $arg3. For compatibility, the +string "none" is seen as empty. +

+
+
+
+
ifeq($arg1, $arg2, $arg3)
+
+

+If ($arg1==$arg2) then print $arg3 +

+
+
+
+
ifneq($arg1, $arg2, $arg3)
+
+

+If ($arg1!=$arg2) then print $arg3 +

+
+
+
+
ifeqelse($arg1, $arg2, $arg3, $arg4)
+
+

+If ($arg1==$arg2) then print $arg3 else print $arg4 +

+
+
+
+
cond_surr($arg1, $arg2, $arg3)
+
+

+If $arg1 is non-empty print $arg2$arg1$arg3, otherwise print nothing. For +compatibility, $arg1="none" is interpreted as empty. +

+
+
+
+
iffile($arg1, $arg2)
+
+

+If file $arg1 exists, and can be opened for reading by whoever started the +current process, return $arg2, otherwise return nothing. +

+
+
+
+
ifelsefile($arg1, $arg2, $arg3)
+
+

+If file $arg1 exists, and can be opened for reading by whoever started the +current process, return $arg2, otherwise return $arg3. +

+
+
+
+
catfile($arg1)
+
+

+Return the contents of file $arg1. +

+
+
+
+
shell($arg1)
+
+

+Return the output of the shell command $arg1. +

+
+
+
+
forall($array, "var", $exec)
+
+

+For each element of the column separated array $array, set $var to that +element, and print $exec. Example: +

+ +
+           !include lang.h
+           forall(sections_translations(), "lang", \ 
+              " section[" $lang "]=" translate($lang, title()) "\n")
+
+
+
+
+
parent($arg)
+
+

+for $arg a "directory", return parent directory: +parent("/Debian/Applications/Editors") = +"/Debian/Applications". +

+
+
+
+
basename($arg)
+
+

+return the last part of the parent directory: +basename("/Debian/Applications/Editors") = "Applications". +

+
+
+
+
stripdir($arg)
+
+

+everything after the last slash, i.e. what basename() should have returned: +stripdir("/Debian/Applications/Editors") = "Editors". +

+
+
+
+
entrycount()
+
+

+the number of entries in this menu. +

+
+
+
+
entryindex()
+
+

+returns relative position of this entry. Start with 0, last entry is +entrycount() - 1. BUG: if sort= anything other than $title, then this +entryindex() will return incorrect values. +

+
+
+
+
firstentry($arg)
+
+

+return $arg if this is the first entry of this menu (that is, entryindex() = +0). Else, return nothing. +

+
+
+
+
lastentry()
+
+

+return $arg if this is the last entry in this menu (that is, entryindex() = +entrycount() -1). Else, return nothing. +

+
+
+
+
level()
+
+

+return nesting of this menu in the total menu tree. +

+
+
+
+
add($arg1,$arg2)
+
sub($arg1,$arg2)
+
mult($arg1,$arg2)
+
div($arg1,$arg2)
+
+

+returns the sum, difference, product or quotient of $arg1 and $arg2. Note that +the arguments are strings, that are converted to integers. example: +mult("24", entryindex()) +

+
+
+
+
rcfile()
+
examplercfile()
+
mainmenutitle()
+
rootsection()
+
rootprefix()
+
userprefix()
+
treewalk()
+
postoutput()
+
preoutput()
+
+

+These functions all output whatever they were defined to be in the menu-method +file. +

+
+
+
+
translate($lang, $text)
+
+

+Translate $text into $lang using gettext, see forall for an +example. Note that currently outputlanguage must be set to "C". If +$lang is the empty string, $text will be translated in the current locale +language. See sections_translations() for a list of available translations. +

+
+
+
+
implicit concatenation
+
+

+String constants, variables and functions can be concatenated by placing them +after each other with a space in between, like: "hello" +ifelse($comma, $comma, " sorry" $period " comma not +defined") " world" +

+
+
+ +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + diff --git a/doc/menu.html/index.html b/doc/menu.html/index.html new file mode 100644 index 0000000..cb79bda --- /dev/null +++ b/doc/menu.html/index.html @@ -0,0 +1,208 @@ + + + + + + + + +Debian Menu System + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+ +

Abstract

+ +

+The menu package was inspired by the +install-fvwm2-menu program from the old fvwm2 +package. However, menu tries to provide a more general interface +for menu building. With the update-menus command from this +package, no package needs to be modified for every X window manager again, and +it provides a unified interface for both text- and X-oriented programs. +

+ +
+ +

Copyright Notice

+ +

+Copyright ©1997 Joost Witteveen, Joey Hess, Christian Schwarz. ©2002-2005 Bill Allombert. +

+ +

+This manual is free software; you may redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2, or (at your option) any later version. +

+ +

+This is distributed in the hope that it will be useful, but without any +warranty; without even the implied warranty of merchantability or fitness +for a particular purpose. See the GNU General Public License for more details. +

+ +

+A copy of the GNU General Public License is available as +/usr/share/common-licenses/GPL in the Debian GNU/Linux +distribution or on the World Wide Web at +http://www.gnu.org/copyleft/gpl.html. You can also obtain it by +writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, +Boston, MA 02110-1301 USA +

+ +
+ +

Contents

+ + + +
+ +

+[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ 7 ] +[ 8 ] +[ next ] +

+ +
+ +

+Debian Menu System +

+ +
+version 1.4, 10 November 2011
+
+Joost Witteveen joostje@debian.org
+Joey Hess joeyh@debian.org
+Christian Schwarz schwarz@debian.org
+Bill Allombert ballombe@debian.org
+
+
+
+ + + + + -- cgit v1.2.3