diff options
Diffstat (limited to 'doc')
34 files changed, 8142 insertions, 0 deletions
diff --git a/doc/BUGS b/doc/BUGS new file mode 100644 index 0000000..2f1c280 --- /dev/null +++ b/doc/BUGS @@ -0,0 +1,24 @@ +Reporting menu bugs +--------------------- + +If you are reporting a bug about the way menus are displayed, please +provide the name and version of the window manager (or menu manager) +you use. You can use the output of +dpkg-query -l <window manager package name> + +----------------------- +If you have a difficult to reproduce problem with install-menu +----------------------- + +# update-menus --stdout > /tmp/menu-stdin +# bzip2 /tmp/menu-stdin +# tar -cvf /tmp/tar.tar /tmp/menu-stdin.bz2 #and any other interesting file +# uuencode /tmp/tar.tar /tmp/tar.tar | mail -s tar.tar menu@packages.debian.org + +If you want to try out a menu-method yourselve several times +(with minor changes etc), you can use the /tmp/menu-stdin file +this way to start your menu-method without starting update-menus: + +/etc/menu-methods/my_wm < /tmp/menu-stdin + + diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..4f5d89a --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,66 @@ +all-local: menu.html/index.html menu.txt.gz menu.info.gz + +DOCS = announce-2 BUGS README.changes README.config-menus README.menu-methods README.new-sections README.package-menus README.pre1 TODO translate README.translations menu.sgml menu.direntry + +man_MANS = install-menu.1 menufile.5 su-to-root.1 update-menus.1 +EXTRA_DIST = $(man_MANS) $(DOCS) $(srcdir)/menu.html $(srcdir)/menu.txt.gz $(srcdir)/menu.info.gz update-menus.fr.1 su-to-root.fr.1 menufile.fr.5 + +docdir=$(datadir)/doc +pkgdocdir=$(docdir)/menu + +menu.html/index.html: menu.sgml + LANG=C debiandoc2html $< + +menu-one-file.html: menu.sgml + LANG=C debiandoc2html -1 -b menu-1-file $< + mv menu-1-file.html/index.html menu-one-file.html + rmdir menu-1-file.html + +menu-one-file: menu-one-file.html + +%.info: %.sgml %.direntry + LANG=C debiandoc2info -s ./$*.direntry $< + +%.txt: %.sgml + LANG=C debiandoc2text -O $< > $@ + +%.gz: % + gzip --best --force --stdout $< > $@ +clean-local: + rm -f menu-one-file.html + +maintainer-clean-local: + rm -rf menu.html *.info* *.txt* + +install-default: + $(INSTALL) -d \ + $(DESTDIR)$(pkgdatadir)/default + for i in $(top_srcdir)/default/*; do \ + test -f $$i && $(INSTALL_DATA) $$i $(DESTDIR)$(pkgdatadir)/default;\ + done; + +install-data-local: + $(INSTALL) -d \ + $(DESTDIR)$(pkgdocdir)/examples \ + $(DESTDIR)$(pkgdocdir)/html \ + $(DESTDIR)$(infodir) + + for i in $(top_srcdir)/examples/*; do \ + test -f $$i && $(INSTALL_DATA) $$i $(DESTDIR)$(pkgdocdir)/examples;\ + done; + + $(INSTALL_DATA) $(srcdir)/menu.html/* $(DESTDIR)$(pkgdocdir)/html + $(INSTALL_DATA) $(srcdir)/menu.txt.gz $(DESTDIR)$(pkgdocdir) + $(INSTALL_DATA) $(srcdir)/menu.info.gz $(DESTDIR)$(infodir) + $(INSTALL_DATA) $(srcdir)/menu.sgml $(DESTDIR)$(pkgdocdir) + + $(INSTALL_DATA) $(srcdir)/BUGS $(DESTDIR)$(pkgdocdir) + $(INSTALL_DATA) $(srcdir)/README.translations $(DESTDIR)$(pkgdocdir) + $(INSTALL_DATA) $(srcdir)/../README $(DESTDIR)$(pkgdocdir) + +uninstall-default: + rm -rf $(DESTDIR)$(pkgdatadir)/default + +uninstall-local: + rm -rf $(DESTDIR)$(pkgdocdir) + rm -f $(DESTDIR)$(infodir)/menu.info.gz diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..b84b422 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,461 @@ +# Makefile.in generated by automake 1.9.6 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +top_builddir = .. +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +INSTALL = @INSTALL@ +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +subdir = doc +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in TODO +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +man1dir = $(mandir)/man1 +am__installdirs = "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man5dir)" +man5dir = $(mandir)/man5 +NROFF = nroff +MANS = $(man_MANS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMDEP_FALSE = @AMDEP_FALSE@ +AMDEP_TRUE = @AMDEP_TRUE@ +AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +GREP = @GREP@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ +MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ +MAKEINFO = @MAKEINFO@ +MO_PROGRAMS = @MO_PROGRAMS@ +MO_SECTIONS = @MO_SECTIONS@ +MO_SUTOROOT = @MO_SUTOROOT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PO_PROGRAMS = @PO_PROGRAMS@ +PO_SECTIONS = @PO_SECTIONS@ +PO_SUTOROOT = @PO_SUTOROOT@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ +am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ +am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@ +am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build_alias = @build_alias@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = $(datadir)/doc +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host_alias = @host_alias@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +DOCS = announce-2 BUGS README.changes README.config-menus README.menu-methods README.new-sections README.package-menus README.pre1 TODO translate README.translations menu.sgml menu.direntry +man_MANS = install-menu.1 menufile.5 su-to-root.1 update-menus.1 +EXTRA_DIST = $(man_MANS) $(DOCS) $(srcdir)/menu.html $(srcdir)/menu.txt.gz $(srcdir)/menu.info.gz update-menus.fr.1 su-to-root.fr.1 menufile.fr.5 +pkgdocdir = $(docdir)/menu +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +uninstall-info-am: +install-man1: $(man1_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man1dir)" || $(mkdir_p) "$(DESTDIR)$(man1dir)" + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ + done +uninstall-man1: + @$(NORMAL_UNINSTALL) + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ + done +install-man5: $(man5_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man5dir)" || $(mkdir_p) "$(DESTDIR)$(man5dir)" + @list='$(man5_MANS) $(dist_man5_MANS) $(nodist_man5_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.5*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 5*) ;; \ + *) ext='5' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man5dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man5dir)/$$inst"; \ + done +uninstall-man5: + @$(NORMAL_UNINSTALL) + @list='$(man5_MANS) $(dist_man5_MANS) $(nodist_man5_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.5*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 5*) ;; \ + *) ext='5' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man5dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man5dir)/$$inst"; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + $(mkdir_p) $(distdir)/$(srcdir) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ + list='$(DISTFILES)'; for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ + esac; \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test "$$dir" != "$$file" && test "$$dir" != "."; then \ + dir="/$$dir"; \ + $(mkdir_p) "$(distdir)$$dir"; \ + else \ + dir=''; \ + fi; \ + if test -d $$d/$$file; then \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(MANS) all-local +installdirs: + for dir in "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man5dir)"; do \ + test -z "$$dir" || $(mkdir_p) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-local mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +info: info-am + +info-am: + +install-data-am: install-data-local install-man + +install-exec-am: + +install-info: install-info-am + +install-man: install-man1 install-man5 + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic \ + maintainer-clean-local + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-info-am uninstall-local uninstall-man + +uninstall-man: uninstall-man1 uninstall-man5 + +.PHONY: all all-am all-local check check-am clean clean-generic \ + clean-local distclean distclean-generic distdir dvi dvi-am \ + html html-am info info-am install install-am install-data \ + install-data-am install-data-local install-exec \ + install-exec-am install-info install-info-am install-man \ + install-man1 install-man5 install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-generic maintainer-clean-local mostlyclean \ + mostlyclean-generic pdf pdf-am ps ps-am uninstall uninstall-am \ + uninstall-info-am uninstall-local uninstall-man uninstall-man1 \ + uninstall-man5 + +all-local: menu.html/index.html menu.txt.gz menu.info.gz + +menu.html/index.html: menu.sgml + LANG=C debiandoc2html $< + +menu-one-file.html: menu.sgml + LANG=C debiandoc2html -1 -b menu-1-file $< + mv menu-1-file.html/index.html menu-one-file.html + rmdir menu-1-file.html + +menu-one-file: menu-one-file.html + +%.info: %.sgml %.direntry + LANG=C debiandoc2info -s ./$*.direntry $< + +%.txt: %.sgml + LANG=C debiandoc2text -O $< > $@ + +%.gz: % + gzip --best --force --stdout $< > $@ +clean-local: + rm -f menu-one-file.html + +maintainer-clean-local: + rm -rf menu.html *.info* *.txt* + +install-default: + $(INSTALL) -d \ + $(DESTDIR)$(pkgdatadir)/default + for i in $(top_srcdir)/default/*; do \ + test -f $$i && $(INSTALL_DATA) $$i $(DESTDIR)$(pkgdatadir)/default;\ + done; + +install-data-local: + $(INSTALL) -d \ + $(DESTDIR)$(pkgdocdir)/examples \ + $(DESTDIR)$(pkgdocdir)/html \ + $(DESTDIR)$(infodir) + + for i in $(top_srcdir)/examples/*; do \ + test -f $$i && $(INSTALL_DATA) $$i $(DESTDIR)$(pkgdocdir)/examples;\ + done; + + $(INSTALL_DATA) $(srcdir)/menu.html/* $(DESTDIR)$(pkgdocdir)/html + $(INSTALL_DATA) $(srcdir)/menu.txt.gz $(DESTDIR)$(pkgdocdir) + $(INSTALL_DATA) $(srcdir)/menu.info.gz $(DESTDIR)$(infodir) + $(INSTALL_DATA) $(srcdir)/menu.sgml $(DESTDIR)$(pkgdocdir) + + $(INSTALL_DATA) $(srcdir)/BUGS $(DESTDIR)$(pkgdocdir) + $(INSTALL_DATA) $(srcdir)/README.translations $(DESTDIR)$(pkgdocdir) + $(INSTALL_DATA) $(srcdir)/../README $(DESTDIR)$(pkgdocdir) + +uninstall-default: + rm -rf $(DESTDIR)$(pkgdatadir)/default + +uninstall-local: + rm -rf $(DESTDIR)$(pkgdocdir) + rm -f $(DESTDIR)$(infodir)/menu.info.gz +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/README.changes b/doc/README.changes new file mode 100644 index 0000000..65581f4 --- /dev/null +++ b/doc/README.changes @@ -0,0 +1,64 @@ +Changes between pre 1.0 and 1.0: + +Basically, both update-menus and install-menu have been re-written +from scratch. + + +************************************* +update-menus + + *forks to background, waits for dpkg to finish (to get a _correct_ + package listing). (This is now only done with dpkgs that don't support + triggers.) + + *allows new menuentry format: + needs=text command=/usr/bin/vi section=Apps/Editors title=Vi \ + longtitle="The editor that people complain even\ + more about than the about weather, vi." \ + id=vi sort=aa myfunkyvar=lichtbewolkt + + +************************************* + +install-fvwmgen -> menu-method: + + *Change of name (The old name wasn't very good anyway, and + it allows me to more easily change the format of the file). + + *Format changed: ${title} is now written as either $title or + print($title) (the latter giving an error if $title is empty). + More about this in /usr/share/doc/menu/html. + + *Long lines can be continued on next line with a "\". + (do make sure there are no spaces after the "\") + + *in the menu-methods files, tabs, newlines, etc used to need + double \\, like "\\t, \\n". These is needed any more. + (now looks like "\t, \n"). + + *things like "startmenu=filename" don't work any more (nobody + knew this worked anyway). + + *Lot's of new "functions", see README + + *Slightly different interpretation of variables: + + ${section} used to print the last part of the section name, now + it prints the full section in a submenu, or the full section + plus "/"$title in menuentries (or plus "/" $sort ":" $title + if $sort is defined). + + ${fullsection} has been removed (section replaces this) + + $subsection now prints what ${section} would have printed + with menu-0.11. + + the id tag isn't needed any more. Now using $sort ":" $title to + determine if two menuentries are the same. + + *in script: mainmenu= isn't accepted any more + (never used to work with "compat=gen"). + + *Now you can actually add icons etc to the submenu entries, + even to the root menus + needs="X11" section="Apps" title="Ap" hotkey=X icon="myiconfile" diff --git a/doc/README.config-menus b/doc/README.config-menus new file mode 100644 index 0000000..862b8ba --- /dev/null +++ b/doc/README.config-menus @@ -0,0 +1,11 @@ +In this directory, the system administrator can install menufiles to +override the menu files provided by Debian in /usr/lib/menu, /usr/share/menu +and /usr/share/menu/default. + +The filename should be the name of the package that it is overriding, +and may contain as many lines and menu entries as necessary. + +Please run 'update-menus' after changing or adding files. + +For more info, please read /usr/share/doc/menu/html. + diff --git a/doc/README.menu-methods b/doc/README.menu-methods new file mode 100644 index 0000000..efced27 --- /dev/null +++ b/doc/README.menu-methods @@ -0,0 +1,10 @@ +In this directory the scripts files for the install programme +of the various window managers are situated. + +update-menus runs all files in this directory, passing it all menuentries +to install on stdin. + +The filenames in this directory must contain only letters/numbers or -_ +any other files (like the .bak, .dpkg-old, ...) are silently ignored. + +For more info, see /usr/share/doc/menu/html diff --git a/doc/README.new-sections b/doc/README.new-sections new file mode 100644 index 0000000..0f0d7a2 --- /dev/null +++ b/doc/README.new-sections @@ -0,0 +1,12 @@ +What I have in mind is something like + +section=Apps/Tools title=SomeClock es=Clocks/Digital/Simple + +section=Apps/Tools[/Clocks/Digital/Simple] title=SomeClock + + +section=Apps/Tools title=SomeClock es=Clocks/Digital/Simple + + + +section=Apps[/hello] title=Tools diff --git a/doc/README.package-menus b/doc/README.package-menus new file mode 100644 index 0000000..9c78b5c --- /dev/null +++ b/doc/README.package-menus @@ -0,0 +1,24 @@ +In this directory, each individual package should install its +menu files. Although changing them in this directory to change +the menus on your local system may work, the sysadmin (you?) +is best advised to put the local menufiles in /etc/menu, as, +otherwise your changes are deleted when you upgrade the corresponding +packages. Users may override the system-wide defaults by putting +their menuentry files in ~/.menu. + + +For the package maintainer that wants to include menu files in his +package: + +The files should have the name of the package that's installing it, +and may contain as many lines (menu entries) as is necessary. + +For examples, please look in /usr/share/menu/default + + +Also, in your postinst you should check for the availability of +the update-menus command, and if available, execute it (no +parameters needed). + +For more info, please read /usr/share/doc/menu/html + diff --git a/doc/README.pre1 b/doc/README.pre1 new file mode 100644 index 0000000..20c2e32 --- /dev/null +++ b/doc/README.pre1 @@ -0,0 +1,428 @@ +This "package" is inspired by the install-fvwm2-menu from the debian fvwm2, +but it tries to provide a somewhat more general interface for +menu-building. With the update-menus command from this package, +(and the /usr/lib/menu/$package files), +no package needs to be modified for every X window manager again, +and it provides a unified interface for both text- and X-oriented +programmes. + +************************ +*It works like this: + +Each package includes a file in /usr/lib/menu/package-name. In this +file, it will have one line per menu-entry, like this (from +/usr/lib/menu/xpuzzles): + X11 Apps/Games/Puzzles xtriangle none "Xtriangle" /usr/games/xtriangles + +This describes the type of interface the package needs (X11), +the menu section the menu entry should be in, an id, possibly +an icon, the menu text, and the command that should be executed. + +Whenever root runs update-menus, it will check all new or +changed menufiles in /etc/menu and /usr/lib/menu, +and run the installation scripts display managers like fvwm2 +should provide in /etc/menu-methods on them. + +The menu package itself provides a set of default menu files, +for people to get the idea, and to speed things up a bit +(These files should be incorporated into the package). + +************************ +* (User-) Configuring the menu's + +A user can specify her/his own menu entries in the ~/.menu directory. +the files in that directory should have names of installed packages, or +"local.name", as update-menus assumes any "package" who's name starts +with "local" is installed. + +A system admin should place system-wide menuentries in /etc/menu, +(not in /usr/lib/menu/package, those will be overridden after an upgrade +of package). Again, filenames must have a name of an installed package, +or starting with "local". + +************************ +* Specifying "No-menu-entry" + +If a user wants to remove an entry from the system menu (in /etc/menu), +then this will do the trick: + echo -n > ~/.menu/package +The zero-size file will tell update-menus that the corresponding +package should not have any menu-entries listed. + +************************ +* What should the each package do to use this: + +-Include a conffile file in /etc/menu/$package. + The name of the file should be $package, with $package the + package name of the binary package the menufile will be distributed + in. (in the case of single source packages that build many binary packages). + This file should contain, for each programme it likes to make + available in a menu: + text Math gnuplot none "Gnuplot" /usr/bin/gnuplot + ^ ^ ^ ^ ^ ^ + | | | | | The binary to be executed + | | | | The menu-entry-name + | | | The pixmap in the menu entry + | | Some ID for this menu entry. .Please make this + | | ${package}/someid, where ${package} is the package name of the + | | package the menu file will be distributed in, as + | | we may require this later. + | The section in which the menu entry should appear + Type: X11 if this programme only runs on X11 displays + text if it only runs on text-oriented terminals; + (the window manager should spawn an + xterm or rxvt in this case) + vc if the program only runs at the Linux console (i.e.: svgalib) + + A programme like gnuplot should NOT have an extra entry for + X11 like this: + X11 Apps/Math gnuplot none "Gnuplot" "xterm -e /usr/bin/gnuplot" + because it will then be next to impossible to configure the + window mangers to spawn rxvt instead. + + If, on the other hand, a programme can both run like a real + X application, and on a terminal (like emacs), then two + entries should be listed (otherwise, emacs will also be run in + an xterm). + +-In your postinst and postrm script, add a line like: + if test -x /usr/bin/update-menus; then update-menus; fi + +-Do not make your package depend on the menu package. + +************************ +* The preferred layout of the menu (currently suggestion only): + + Apps -- all normal apps + Editors -- editors (run it in xterm, if nothing else) + Net -- mail, news, web, irc, etc + Programming -- debuggers, etc + Shells -- Different shells, like bash, ksh, zsh, ... + Tools -- other tools: xclock, xmag, xman, + Viewers -- Picture viewers, gs, ... + Math -- Math apps like: gnuplot, octave, oleo,.. + Graphics -- xpaint, xfig, xtiff, + Emulators -- Dosemu, ... + Sound -- + System -- system administration and monitoring + Games -- games and recreations + Adventure -- walk around virtual space, zork, MOO's, etc + Arcade -- (any game where reflexes count) + Board -- Like: Gnuchess, pente, gnugo + Card -- solitaire, etc + Puzzles -- Stuff from xpuzzles, ... + Sports -- Games derived from "real world" sports + Strategy -- Build your world (Games like lincity, freeciv) + Tetris-like -- games involving falling blocks + Toys -- (oneko, xeyes, etc.) + Screen -- + Lock -- xlock, etc. + Screen-saver -- + Root-window -- things that fill the root window + Window-managers -- (change between fvwm, afterstep, etc) + Modules -- fvwm modules, etc. + XShells -- shells (like xterm, rxvt, ...) + (running the user's login shell in them). + + This is basically what Joey Hess posted on debian-devel, with + Also, I moved the shells to the root, as I don't like to have to + go two levels deep for my shell -- but if others prefer that, I'll + happily revert this (and I moved xclock in tools, is that OK?) + +************************ +* What should each menu-manager (fvwm*, twm, pdmenu, ...) do? + +Provide a configfile-script in /etc/menu-methods that can read +the menu-files. This script will be executed by update-menus +with the to be installed menu-entries passed to the script via +stdin. + +The scripts in /etc/menu-methods should be configfiles, if the user +can tune the behaviour in the script (as is the case in the scripts +provided in this package in /usr/share/doc/menu/examples/$wm). + +Run update-menus (if it exists) in the postinst, and remove the +execute bit from the /etc/menu-methods in the postrm when called +with remove. +Example bash post{rm,inst} script: + +#postrm: + #!/bin/sh + set -e + inst=/etc/menu-methods/twm #or fvwm, ... whatever manager you're installing + case "$1" in + remove) + chmod a-x $inst + ;; + purge) + #remove the files that install-fvwmgenmenu creates: + rm /etc/X11/twm/{system.twmrc,menus.dat,menudefs.hook} + #maybe also rm $inst, if dpkg doesn't do that itself. + ;; + upgrade);; + *) + echo "postrm called with unknown argument \`$1'" >&2 + exit 0 + ;; + esac + +#postinst: + #!/bin/sh + set -e + inst=/etc/menu-methods/pdmenu #or fvwm, ... whatever manager you're installing + if [ -x /usr/bin/update-menus ] ; then + if [ -f $inst ]; then + chmod a+x $inst + update-menus; + fi + fi + +The menu package should not include any installer scripts for +window managers (that's the job of the packages that install the +window managers), but I do provide scripts for nearly all +debian window managers in /usr/share/doc/menu/examples. See the readme +on how to activate them. For an example, see the latest fvwm95 package +(or olvwm). + +************************ +* Options to update-menus + + -v verbose (generate a lot of output) + -d debug (loads of more output) + --show-time + +************************ +* What does update-menus do? + +when update-menu starts, it: + 1 sets a variable $dirs to + dirs="/etc/menu /usr/lib/menu /usr/lib/menu/default" + (and if a user runs runs it, it will add ~/.menu to the front + of that list) + 2 it reads the list of installed packages. + 3 for d in $dirs; do + - read files in $d + - check if corresponding package is installed, and, is listed + in the $d/.updated-menus file, checking the mod time in + $d/.updated-menus. + Depending on that information, either put the menufile $file in the + the install-menu-list, or the menuentry in the $remove-entries, + and do put the entries in the already-correctly-installed-list + 4 after going through all dirs, do + for method in `ls /etc/menu-methods`; do + $cat install-menu-list | method -f --stdin + done + +Ad step 3+4 + - The $d/.updated-menus file lists not only the files in that directory + and it's mod-time (to check for changes), it also lists + the known menu-managers (i.e., the output of `ls /etc/menu-methods`) + at the time of the last installation. Based on this information, + steps 3+4 are changed a bit, to update/remove new/old menu-managers. +Ad step 1+2+3+4 + although I've used a sh-like syntax here, it's written in C++. + +************************ +* The /usr/sbin/install-fvwmgenmenu programme + +The files /etc/menu-methods/fvwm* are "executable" config files +that begin with + #!/usr/sbin/install-fvwmgenmenu +and thus start that programme, handing it the configuration file for the +specific wm in argv[1]. This configuration consists of: + - the compatibility mode (used to be fvwm, 9wm, .. but now "gen" for all wm's) + - where the various files should be stored/read. + - what "types" are supported, and what wrapper files should + be used for each "type". +See /usr/share/doc/menu/examples/ for some more comments. + +Options to install-fvwmgenmenu: + -v be verbose + -d Produce loads of debugging output + -f (always) force install (assume no packages are installed) + --install-files take the next arguments to be files woos menuentries + should be installed + --stdin (always) read menuentries from stdin. + +The -f and --stdin "options" exist because old versions used to +have cache files and other complicated stuff. This didn't result +in any speedups, and did complicate stuff. So we (Joey and I) decided +to make -f and --stdin options that are always on (and can thus be +ignored). + +Some window managers don't support the m4 or cpp +preprocessing, and cannot read the menudefs.hook file +from their system.*rc configfile. To still be able to use them, +install-fvwmgenmenu will copy the file $path/$examplercfile to +$path/$rcfile (with $path, $examplercfile and $rcfile defined +in the install-fvwmgenmenu config file), and replace all +occurrences of "install-menu-defs" with the $genmenu +file it just generated. Although this approach looks quite +clumsy, it does allow for one $path/$examplercfile on the system, +(The m4/cpp approach puts a "include(/etc/X11/*/menudefs.hook)" +in the system.*rc file, so users will never load their menudefs.hook +file). +To activate the file-copying in this way, simply define +the $examplercfile and $rcfile variables in the install-fvwmgenmenu +configuration file (/etc/menu-methods/fvwm*), and make sure +there is a $path/$examplercfile ($path being either $rootprefix, or +$userprefix) + + +************************ +* "supported" section in the install-fvwmgenmenu config files. + +Each definition defines a display type that this window-manager supports. +After the displaytype is the string that should be printed in the +system."$wm"rc file for each menu entry that matches that display type. + +Install-fvwmgenmenu does the following variable expansions: + variable in conffile expands to in example below this is: + - - - + ${title} -> menutitle Xtriangle + ${section} -> lastpartofsection Puzzles + ${fullsection} -> full section Apps/Games/Puzzles + ${id} -> menuentry id xtriangle + ${icon} -> icon none + ${command} -> command /usr/games/xtriangles + ${type} -> type X11 + +Example (see table above): + X11 Apps/Games/Puzzles xtriangle none "Xtriangle" /usr/games/xtriangles + +(where in the title, menu, ... are taken from the menuentry in the menufile). +As a special exception, if no "${command}" occurs in the wrapper, +" ${command}" is added at the end, so empty wrapper files will at least +hand the command. A similar exception is made for "${title}" in the +fvwm2 compat mode. + +Along the lines of ${var}, you can also use: + + example example example purpose: +${var} var "var"+'v' none | just expand var +$d{var} var \"var\"+'v' none | escape Double quotes +$s{var} var "var"+\'v\' none | escape Single quotes +$b{var} var \"var\"+\'v\' none | escape Both single and double q +$%{var} %var% %"var"% | for icons + +(In this table, the first line lists the value of ${var}, and the +other lines list what $d{var}, ... would have produced). + +strings like \\n, \\t, ... for their ordinary will be substituted for +their C expansions (But not \0xx). + +Note: the above only holds for "compat=gen". the other compat modes +will be disabled in the future, and currently don't support everything +that's described above + +************************ +* Other install-fvwmgenmenu config script items: +* +compat + Please make this "gen" only. (Old versions of install-fvwmgenmenu + used to take other compats, but "gen" is much more general). + +startmenu +endmenu +submenutitle + These define what to print for the beginning/end of a menu, and + how to the print a menuentry that pops up another menuentry. + They are substituted the same way as the "supported" stuff is. + +treewalk: + This string defines in what order to dump the $startmenu, $endmenu, + and $submenutitle (and it's children). Each char in the string + refers to : + c : dump children of menu. + m : dump this menu's $submenutitles + ( : dump $startmenu + ) : dump $endmenu + M : dump all $submenutitles of this menu and this menu's children. + The default is "c(m)". For olvwm, one needs: "(M)" + +database: + A cache file (old). + +genmenu: + The menufile to generate (usually something like system."$wm"rc). + +rcfile: + If the window manager doesn't support an "include filename" or + "read(filename)" statement in it's config file, you can rename + the wm's config file to system."$wm"rc-menu, and insert + a "install-menu-defs" line (without the quotes, or whitespace around + it, and "install-menu-defs" must be the only thing on the line) + in the system."$wm"rc-menu file. This will then get replaced + by the $genmenu file that was just created (see also $examplercfile). + +examplercfile: + if needed (see rcfile), this is the system.rc"$wm"-menu file. + In that case, make rcfile=system.rc"$wm". + +rootprefix: + The prefix to use when running as root (applies to $genmenu, $rcfile, + $examplercfile and other old cache files) + +userprefix: + see rootprefix, but when running as user. + +************************ +* Icons +* + +Please, make sure the icons you specify are always available on the system. +So, if you want to have an icon with your menuentry, the preferred method +is to supply the icon with that package. Also, to prevent the distribution +of icons files to turn too much into a mess, please put all icon +files in /usr/X11R6/include/X11/{bitmap,pixmap}. + +If you, as a system admin, don't like the icons in the menu's, simply +remove the $%{icon} from the files in /etc/menu-methods/$wm, and +type "update-menus" + + +If you want to specify an icon for a submenu (for example, the Editors +submenu), just use the same syntax but leave the command empty: + + X11 Apps menu/apps /usr/X11R6/include/X11/pixmap/icon.xpm "Editors" + +As there probably isn't one right package to include the submenu icons, +I guess (as Joey suggested) the menu package is the only right place +to have these menu's (Otherwise, problems arise when two packages +supply different icons for the same submenu, and we can never be sure +the icon files are available). + + +************************ +* Taskbar/Titlebar (fvwm*) +* + +The problem with the stuff in the taskbar is that all items are +displayed all of the time. So, if 200 debian packages all were to +register a button, the buttons would quickly fill the screen, making +the exercise useless. The few applications that are considered important +enough to be listed in the taskbar usually vary widely on each system, +making it impossible to select a ``happy few'' apps that are allowed +there on every debian system. If you want your fvwm2 to have a few +buttons, you can install files for those packages in /etc/menu/$package, +containing both the normal menu entries, and a line like + button Games/Puzzles xpuzzles/xmball path-to-pixmap.xpm "Xmball" /usr/games/xmball + +Then, do the following: +cd /etc/menu-methods/ +cp fvwm2 fvwm2button +vi fvwm2button +#and remove all the "supported" entries, adding the one below. For the rest, +leave everything the same except those listed below. + +supported + button="+ Style \"${title}\" TitleIcon ${icon} Exec ${command}\\n" +endsupported +startmenu: "AddToTitlebar \\n" +endmenu: "\\n" +submenutitle:"" +mainmenu: +genmenu: "buttondefs.hook" + + + diff --git a/doc/README.translations b/doc/README.translations new file mode 100644 index 0000000..5417af3 --- /dev/null +++ b/doc/README.translations @@ -0,0 +1,52 @@ +******************************************************** +*** *** +*** Menu sections translations *** +*** *** +******************************************************** + +Debian menu includes translations of menu sections names +in various languages. The list is available in +/etc/menu-methods/lang.h. + +A) Selecting the language: + +1) System-wide: +The simplest way is to set up root locales and menu will be translated +accordingly. + +Another solution is to add +outputlanguage="xx" +in /etc/menu-methods/menu.h +where xx is you language code. + +2) User-wide: +Just run update-menus under the locales of your choice. +You can also copy the file +/etc/menu-methods/<your favorite wm> +to +~/.menu-methods/ +and add +outputlanguage="xx" +where xx is you language code. + +3) KDE +Make sure menu-xdg is installed and that root locales are not "C". +Menu will be translated in all languages at once. The users just +need to configure KDE to use their language and menus will follow. + +B) Problems: +There are unfortunately lots of reasons why translations would fail: +window-manager not supporting menu translations, not supporting your +locale encoding or not supporting user menus. + +You can try to add +outputencoding="LOCALE" +at the start of /etc/menu-methods/<your favorite wm> +and run update-menus under different locale encodings. + +C) Screenshots +Some screenshots are available at +<http://people.debian.org/~ballombe/menu-snapshot>. + +-- +Bill Allombert <ballombe@debian.org> Sun, 3 Oct 2004 19:23:53 +0200 diff --git a/doc/TODO b/doc/TODO new file mode 100644 index 0000000..146cf05 --- /dev/null +++ b/doc/TODO @@ -0,0 +1,31 @@ +(Obsolete file by Joost) + + TODO: Add a $source={Debian,System,User} tag (in update-menus), + andreas. + + TODO: probably we need a translate() function too, to be able to do: + dir=translate(ifeq($Source,"User","Local User")) + etc. + +----------------------- +buttonbars: +----------------------- + +Something like a tag "buttonbarpriority=0--99" added to every +menuentry, where buttonbarpriority=0 means that this entry is absolutely +useless in the buttonbar, while buttonbarpriority=99 means that this +menuentry really should be in the buttonbar on every debian computer +(I'm assuming neither priority will be used in reality, if this ever +is implemented). + +Then the file /etc/menu-methods/menu.h could have something like + buttonbarentries=8 +in it, suggesting that menu should create buttonbar entries for the +8 highest priority buttonbar entries. (These numbers can then easily +be overruled in user files in ~/.menu-methods/* or whatever). + +Thinking about this, this might actually be doable -- but I don't forsee +any spare time comming up in my life soon, so it will take some time + +(note that the subject of buttonbars and menus has come up quite +frequently on debian-devel). diff --git a/doc/announce-2 b/doc/announce-2 new file mode 100644 index 0000000..c035750 --- /dev/null +++ b/doc/announce-2 @@ -0,0 +1,116 @@ +Hi there, + +I've just released menu-2.0. It has many new features, one of +wich is the optimization of the menu tree, using something I've +called "hints". This is what I want to start discussion about +with this email. + +******************** +First, why: + +On my system, there are only two entries in the +/Apps/Editors submenu. But I'm sure that other systems have +15 or more entries there. Both aren't optimal: on my system, +the /Apps/Editors submenu could better be removed or merged +with another menu; while on the other systems, /Apps/Editors +should get other sub-entries. Because of the static-ness +of the menu tree, it was never possible to attac this problem. +Now, with "hints" it is. + +******************** +How it works: + +The hints actually work in a rather strange way: when +hint_optimize=true (in the config file) then all $section +elements (like "section=Apps/Editors", in the menuentry file) +are added to the specified $hints variable (new variable in the +menuentry file, could be "hints=Bulky,Expert,Serious" for Emacs). +The order (/Apps/Editors or /Editors/Apps) of the resulting hints +is completely ignored. Then, the +hints for each menu entry are put in an array that is handed to +the optimization routine, that 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 toplevel 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 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 obout the optimimum number of +menu entries. + +Menu is always free to discard hints, if they are not neccecary. + +Although this procedure ignores the real debian tree (so much +discussed about), it does eventually come up that look surprisingly +like just that tree. + +As soon as hints are specified for more menu entries, this procedure +will allow menu to merge, say "Apps/Viewers" and "Apps/Sound", if we +give both submenus the hint "MultiMedia". (Would be good on my system, +as both contain less than 3 entries). If those submenus do get +the "Multimedia" hint, then all `children' of those submenus (like +GhostVieuw and RoseGarden) will automatically inherit those hints. + +******************** +What to discuss? + +Well, the hints have most effect if there is some overal uniformity +in their use. + +For example, Emacs could be given a hints=Bulky, but if that is done, +then all big editors should get a hints=Bulky, and not something like +hints=Big, or hints=MS-like, as then menu will not any more be able +to group all big editors in one menuentry. + +So, we should agree on some hints that can be used in most submenus +(Big or Bulky probably could be used in many more submenus, as would +X11, or Text), and there probably are some hints that can only be used +in one submenu (like "Music" in the Apps/Sound section). + +The hints that apply to submenus (e.g., the hints=Multimedia for +the submenus /Apps/Sound and /Apps/Viewers) can best be set in +the menu package; the hints that apply to programs etc. have +to be set in the menu entry files of those programs. + +Another problem is that English isn't my first language, and I +don't really feel compatent enough to think of many english words +that apply to several menu entries or submenus. I'm hoping other +people are better at thinking of them:). + + +******************** +Closing remarks: + +All of the tree optimization is optional, it will not happen by default +(maybe I should however set hint_optimize=true in /etc/menu-methods/menu.h). + +These hints will provide for a (the only?) way out for those that dislike +their overfull/underfull submenus. + +Yes, a variable menu tree _is_ also a disadvantage, if you want to tell +a friend "Find netscape in Apps/Net/Netscape", and on your friend's +system, it turns out that the section is "Apps/Web/Netscape". But I for +one always tel people to "type `netscape' if you want to start netscape. +Personally, I mostly see the tree as a means for people to find out what +is installed on their system, and, once installed, a possibly nice +`graphical' way to re-start it (on one's own system). + +******************** +Groetjes, +joostje + diff --git a/doc/cmap.xpm b/doc/cmap.xpm new file mode 100644 index 0000000..c752e8b --- /dev/null +++ b/doc/cmap.xpm @@ -0,0 +1,32 @@ +/* XPM */ +static char * cmap3[] = { +/* width height num_colors chars_per_pixel */ +" 46 2 24 1", +" c #000000", +". c #000000", +"# c #ff0000", +"a c #ff00ff", +"b c #0000ff", +"c c #00ffff", +"d c #00ff00", +"e c #ffff00", +"f c #7f0000", +"g c #7f007f", +"h c #00007f", +"i c #007f7f", +"j c #007f00", +"k c #7f7f00", +"l c #191919", +"m c #333333", +"n c #4c4c4c", +"o c #666667", +"p c #7f7f7f", +"q c #999999", +"r c #b2b2b2", +"s c #cccccc", +"t c #e5e5e5", +"u c #ffffff", +/* pixels */ +"..##aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuu" +"..##aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuu" +}; diff --git a/doc/install-menu.1 b/doc/install-menu.1 new file mode 100644 index 0000000..1d122bd --- /dev/null +++ b/doc/install-menu.1 @@ -0,0 +1,43 @@ +.TH install-menu 1 "28 November 2005" "Debian Project" "Debian GNU/Linux manual" +.SH NAME +install-menu \- Process a menu method and generate the menu files for a window +manager or a menu-aware application. +.SH DESCRIPTION +.B update-menus(1) +computes the list of menu entries and passes it in turn to the menu methods in +\fI/etc/menu-methods/\fP. The task of a menu methods is to generate menus +for a specific window manager. +.B install-menu +provides a generic and customizable way to do that. The documentation of the +.B install-menu +definition language is available in the Debian Menu manual, a local copy being +available in +.BR /usr/share/doc/menu/html. +.SH SYNOPSIS +.B install-menu [-vh] [--remove] <menu-method> +.PP +Read menu entries from stdin in \fIupdate-menus --stdout\fP format and generate +menu files using the specified menu-method. +.PP +Normally used in menu method scripts as \fI#! /usr/bin/install-menu\fP. +.SH OPTIONS +.IP "-h,--help" +Show the help message and exit. +.IP "--remove" +Remove the menu files instead of generating them. +.IP "-v,--verbose" +Output messages about what the program is doing. +.SH COPYING +.B install-menu +is distributed under the term of the GNU General Public License version 2, or +(at your option) any later version. +.SH AUTHOR +Written by Joost Witteveen +.RI <joostje@debian.org>. +Now maintained by Bill Allombert +.RI <ballombe@debian.org>. +.SH "SEE ALSO" +.BR update-menus (1), +.BR menufile (5), +.BR /usr/share/doc/menu/html + diff --git a/doc/menu.direntry b/doc/menu.direntry new file mode 100755 index 0000000..0d9bd79 --- /dev/null +++ b/doc/menu.direntry @@ -0,0 +1,11 @@ +#!/bin/sh +sedscript=`tempfile` +cat <<'EOF' > $sedscript +/@c %\*\*add dircategory and direntry here/a\ +@dircategory Information\ +@direntry\ +* Debian menu: \(menu\). The Debian menu system\ +@end direntry +EOF +sed -f $sedscript <$1 >$2 +rm $sedscript 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - Introduction</title> + +<link href="index.html" rel="start"> +<link href="index.html" rel="prev"> +<link href="ch2.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch1"></a></p> +<hr> + +<p> +[ <a href="index.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ 1 ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch2.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 1 - Introduction +</h1> + +<hr> + +<p> +Before the advent of <code>update-menus</code>, 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, +<code>fvwm</code>'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. +</p> + +<p> +<code>update-menus</code> 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. <code>update-menus</code> 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 <code>update-menus</code> as that user, thus creating +window-manager startup files that are used in preference to the systemwide +files. +</p> + +<p> +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 +<samp>/Applications/Editors</samp>, 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 +<samp>/Applications/Editors</samp> tree in, say <samp>Editors/Beginner</samp>, +<samp>Editors/Experienced</samp>, or whatever, if there are many entries in +that submenu, or maybe even totally removing <samp>/Applications/Editors</samp> +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). +</p> + +<p> +Each package that needs to add an entry to the menu tree, includes a menu file +<code>/usr/share/menu/package-name</code>. In this file, it will have one line +per menu entry, like this (copied from <code>/usr/share/menu/xbase</code>): +</p> + +<pre> + ?package(xbase):command="/usr/bin/xedit" needs="X11" \ + section="Applications/Editors" title="Xedit" \ + hints="Beginner,Small" +</pre> + +<p> +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 <samp>/Applications/Editors</samp> is +overfull, it could put Xedit in a <samp>Applications/Editors/Beginner</samp> or +<samp>Applications/Editors/Small</samp> subsection. +</p> + +<p> +Whenever <samp>root</samp> runs <code>update-menus</code>, it will check all +menu files in <code>/etc/menu</code>, <code>/usr/lib/menu</code>, +<code>/usr/share/menu</code>, and run the installation scripts that display +managers like <code>fvwm2</code> should provide in +<code>/etc/menu-methods</code>. +</p> + +<p> +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.) +</p> + +<p> +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. +</p> + +<p> +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). +</p> + +<hr> + +<p> +[ <a href="index.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ 1 ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch2.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - Menu from the viewpoint of a user</title> + +<link href="index.html" rel="start"> +<link href="ch1.html" rel="prev"> +<link href="ch3.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch2"></a></p> +<hr> + +<p> +[ <a href="ch1.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ 2 ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch3.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 2 - Menu from the viewpoint of a user +</h1> + +<hr> + +<hr> + +<h2><a name="s2.1"></a>2.1 How/when do the window manager startup files get created?</h2> + +<p> +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. +</p> + +<p> +When a package that wants to add something to the menu tree gets installed, it +will run <code>update-menus</code> in its <code>postinst</code> script. +Update-menus then reads in all menu files in <code>/etc/menu/</code>, +<code>/usr/lib/menu</code>, <code>/usr/share/menu</code> and +<code>/usr/share/menu/default</code>, and stores the menu entries of all +installed packages in memory. Once that has been done, it will run the +menu-methods in <code>/etc/menu-methods/*</code>, 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 +<code>/etc/menu-methods/</code>. 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 <code>install-menu</code> program. +This program can generate the startupfiles for just about every window manager. +</p> + +<hr> + +<h2><a name="s2.2"></a>2.2 Tuning of the generated window manager startup files</h2> + +<p> +In principle this is a very window-manager specific business. But for all +window managers (and others) applies: +</p> + +<p> +The file to attack is the menu-method in <code>/etc/menu-methods/$wm</code>, +with <samp>$wm</samp> the name of your window manager. However, if this +menu-method <samp>!include</samp>-s the <code>menu.h</code> file (as it +should), you can also edit that file, to make your changes work for every +installed window manager. +</p> + +<p> +If the menu-method file of your window manager does <samp>!include</samp> the +<code>menu.h</code> file, and makes proper use of the definitions in there, +then you can look at the comments in that <code>menu.h</code> file to see how +you can make minor adjustments to the look of your menus in your window +manager. +</p> + +<p> +To generally change the menu tree, see the next section. +</p> + +<hr> + +<h2><a name="s2.3"></a>2.3 Optimization of menu tree: hints</h2> + +<p> +If <samp>hint_optimize=true</samp> has been set in a menu-method script +(actually, that definition should appear in the <samp>!include</samp>-ed +<samp>menu.h</samp> 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 <samp>hints_nentry=...</samp>). 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. +</p> + +<hr> + +<p> +[ <a href="ch1.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ 2 ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch3.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - The menu file</title> + +<link href="index.html" rel="start"> +<link href="ch2.html" rel="prev"> +<link href="ch4.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch3"></a></p> +<hr> + +<p> +[ <a href="ch2.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ 3 ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch4.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 3 - The menu file +</h1> + +<hr> + +<hr> + +<h2><a name="s3.1"></a>3.1 Location</h2> + +<p> +Packages-provided menu files should be in <code>/usr/share/menu/</code>, unless +the menu files are actually executable binaries, in which case they go in +<code>/usr/lib/menu/</code>. System-local menu files should be in +<code>/etc/menu/</code>. User-specific menu files should be in +<code>~/.menu/</code> +</p> + +<hr> + +<h2><a name="s3.2"></a>3.2 Syntax</h2> + +<p> +The format is: +</p> + +<pre> + ?package(package[,package2,...]): \ + field1="value1"\ + field2="value2"\ +</pre> + +<p> +Here is an example to describe the syntax of such a file: +</p> + +<pre> + ?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. +</pre> + +<p> +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. +</p> + +<p> +Values must be quoted with ", and meta-characters (", backslash, +newline) must be escaped with a backslash. +</p> + +<p> +You can include several entries in the same file. +</p> + +<p> +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. +</p> + +<p> +<samp>?package(...)</samp> 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 "<samp>local.</samp>" which are +assumed to be always installed. +</p> + +<p> +The fields <samp>needs</samp>, <samp>section</samp>, <samp>title</samp> and +<samp>command</samp> 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. +</p> + +<hr> + +<h2><a name="s3.3"></a>3.3 The <samp>title</samp> field</h2> + +<p> +The <samp>title</samp> must follow the following requirements: +</p> +<ol type="1" start="1" > +<li> +<p> +It must be short. There is an optional <samp>longtitle</samp> field for users +that want longer titles. +</p> +</li> +</ol> +<ol type="1" start="2" > +<li> +<p> +It must be properly capitalized. Use <em>Emacs</em> and not <em>emacs</em>. +</p> +</li> +</ol> +<ol type="1" start="3" > +<li> +<p> +It must be unique. Two entries must not have the same title. +</p> +</li> +</ol> + +<hr> + +<h2><a name="s3.4"></a>3.4 The <samp>needs</samp> field</h2> + +<p> +The following <samp>needs</samp> are documented for use in the Debian menu. +</p> +<ol type="1" start="1" > +<li> +<p> +<samp>X11</samp>: if this program runs under X11. +</p> +</li> +</ol> +<ol type="1" start="2" > +<li> +<p> +<samp>text</samp>: if it runs under a terminal. X11 window managers will spawn +an X terminal emulator. +</p> +</li> +</ol> +<ol type="1" start="3" > +<li> +<p> +<samp>vc</samp>: if it runs under a linux virtual console but not under a X +terminal emulator. +</p> +</li> +</ol> +<ol type="1" start="4" > +<li> +<p> +<samp>wm</samp>: if it is a X11 window manager. The current window manager +will exec(2) this program to avoid "Another window manager is +running" errors. +</p> +</li> +</ol> + +<p> +A menu manager can use a special <samp>needs</samp> value reflecting the menu +manager name for menu entries that must only be displayed in this menu manager. +Examples include <samp>fvwm</samp> modules, <samp>dwww</samp> menu entries. +</p> + +<p> +A program like gnuplot which can be run on X11 as well as on a text terminal +should <em>not</em> have an extra entry with <samp>needs=X11</samp> 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. +</p> + +<p> +On the other hand, if a program (like <code>emacs</code>) 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 <code>xterm</code> (or <code>rxvt</code>). +However, two entries are not allowed to have the same title. The title must be +unique. +</p> + +<hr> + +<h2><a name="s3.5"></a>3.5 The <samp>section</samp> field</h2> + +<p> +The <samp>section</samp> field holds a slash-separated list of hierarchical +sections components. +</p> + +<p> +The <em>authoritative list of Debian's menu structure</em> 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. +</p> + +<p> +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 <samp>menu</samp> package. +</p> + +<p> +Packages must be placed in leaf sections. Please do <em>not</em> put your +packages into any other sections. +</p> +<dl> +<dt>Applications</dt> +<dd> +<p> +Normal applications +</p> +<dl> +<dt>Accessibility</dt> +<dd> +<p> +Tools to aid people with disabilities or for machines lacking usual input +devices. +</p> + +<p> +Examples: gok, yasr, dasher. +</p> +</dd> +</dl> +<dl> +<dt>Amateur Radio</dt> +<dd> +<p> +Anything relating to HAM radio. +</p> + +<p> +Examples: baken, hamsoft, twlog +</p> +</dd> +</dl> +<dl> +<dt>Data Management</dt> +<dd> +<p> +Interactive database programs, collection managers, address books, bibliography +tools, etc. +</p> + +<p> +gaby, alexandria, mdbtools +</p> +</dd> +</dl> +<dl> +<dt>Editors</dt> +<dd> +<p> +Editors, other than office word processors, for text-based information. +</p> + +<p> +Examples: ksubtile, nano, hexedit +</p> +</dd> +</dl> +<dl> +<dt>Education</dt> +<dd> +<p> +Educational and training softwares. +</p> + +<p> +Examples: gtypist, gcompris, quiz +</p> +</dd> +</dl> +<dl> +<dt>Emulators</dt> +<dd> +<p> +Software that allows you to run non-native software or more than one OS at a +time. +</p> + +<p> +Examples: wine, dosemu, qemu +</p> +</dd> +</dl> +<dl> +<dt>File Management</dt> +<dd> +<p> +Tools for file management, archiving, searching, CD/DVD burning, backup, etc. +</p> + +<p> +Examples: file-roller, mc, baobab +</p> +</dd> +</dl> +<dl> +<dt>Graphics</dt> +<dd> +<p> +2D and 3D graphics manipulation software. +</p> + +<p> +Examples: gimp, inkscape, imagemagick +</p> +</dd> +</dl> +<dl> +<dt>Mobile Devices</dt> +<dd> +<p> +Software that allows you to interface with mobile devices (phones, PDAs, etc.). +</p> + +<p> +Examples: kandy, gnokii, gnome-pilot +</p> +</dd> +</dl> +<dl> +<dt>Network</dt> +<dd> +<p> +Network related software. This is a three-level section, do not put entries +directly here. +</p> +<dl> +<dt>Communication</dt> +<dd> +<p> +Mail, USENET news, chat, instant messaging, IP telephony, video conferencing +software, etc. +</p> + +<p> +Examples: xchat, gaim, mutt +</p> +</dd> +</dl> +<dl> +<dt>File Transfer</dt> +<dd> +<p> +File transfer software such as download managers, FTP clients, P2P clients, +etc. +</p> + +<p> +Examples: amule, gftp, d4x +</p> +</dd> +</dl> +<dl> +<dt>Monitoring</dt> +<dd> +<p> +Network monitoring software +</p> + +<p> +Examples: gip, ettercap, iptstate +</p> +</dd> +</dl> +<dl> +<dt>Web Browsing</dt> +<dd> +<p> +Web browsers, tools for offline browsing, etc. +</p> + +<p> +Examples: elinks, epiphany-browser, webhttrack +</p> +</dd> +</dl> +<dl> +<dt>Web News</dt> +<dd> +<p> +Web feed (RSS, Atom, etc.) and podcast aggregators. +</p> + +<p> +Examples: akregator, kitty, liferea +</p> +</dd> +</dl> +</dd> +</dl> +<dl> +<dt>Office</dt> +<dd> +<p> +Office suites, word processors, spreadsheets, CRM, ERP, financial sofware, etc. +</p> + +<p> +Examples: openoffice.org, tinyerp-client, gnucash +</p> +</dd> +</dl> +<dl> +<dt>Programming</dt> +<dd> +<p> +IDEs, debuggers, etc. +</p> + +<p> +Examples: anjuta, gdb, eclipse +</p> +</dd> +</dl> +<dl> +<dt>Project Management</dt> +<dd> +<p> +Timetable managers, group task trackers, bug tracking software, etc. +</p> + +<p> +Examples: planner, bugzilla, gnotime +</p> +</dd> +</dl> +<dl> +<dt>Science</dt> +<dd> +<p> +Scientific and engineering-related software. +</p> +<dl> +<dt>Astronomy</dt> +<dd> +<p> +Astronomy-related software. +</p> + +<p> +Examples: celestia, spacechart, stellarium +</p> +</dd> +</dl> +<dl> +<dt>Biology</dt> +<dd> +<p> +Biology-related software. +</p> + +<p> +Examples: arb, ncbi-tools-x11, seaview +</p> +</dd> +</dl> +<dl> +<dt>Chemistry</dt> +<dd> +<p> +Chemistry-related software. +</p> + +<p> +Examples: chemtool, kalzium, xdrawchem +</p> +</dd> +</dl> +<dl> +<dt>Data Analysis</dt> +<dd> +<p> +Software designed for processing, extracting, and presenting generic scientific +data. +</p> + +<p> +Examples: fityk, ygraph, mn-fit +</p> +</dd> +</dl> +<dl> +<dt>Electronics</dt> +<dd> +<p> +Circuit design tools, simulators and assemblers for microprocessors, etc +</p> + +<p> +Examples: geda, gnucap, tkgate +</p> +</dd> +</dl> +<dl> +<dt>Engineering</dt> +<dd> +<p> +CAD, UML tools, diagram-drawing and other engineering-related software. +</p> + +<p> +Examples: tcm, dia, qcad +</p> +</dd> +</dl> +<dl> +<dt>Geoscience</dt> +<dd> +<p> +Geoscience-related software. +</p> + +<p> +Examples: earth3d, qgis, therion +</p> +</dd> +</dl> +<dl> +<dt>Mathematics</dt> +<dd> +<p> +Mathematics-related software. +</p> + +<p> +Examples: gcalctool, snappea, xeukleides +</p> +</dd> +</dl> +<dl> +<dt>Medicine</dt> +<dd> +<p> +Medicine-related software. +</p> + +<p> +Examples: mssstest, gnumed-client, xmedcon +</p> +</dd> +</dl> +<dl> +<dt>Physics</dt> +<dd> +<p> +Physics-related software. +</p> + +<p> +Examples: kxterm, ifrit, paw +</p> +</dd> +</dl> +<dl> +<dt>Social</dt> +<dd> +<p> +Social sciences-related software. +</p> + +<p> +Examples: gnomesword, hanzim, bibletime +</p> +</dd> +</dl> +</dd> +</dl> +<dl> +<dt>Shells</dt> +<dd> +<p> +Various shells to be used inside a terminal emulator. +</p> + +<p> +Examples: bash, ksh, zsh +</p> +</dd> +</dl> +<dl> +<dt>Sound</dt> +<dd> +<p> +Sound players, editors, and rippers/recorders. +</p> + +<p> +Examples: beep-media-player, grip, audacity +</p> +</dd> +</dl> +<dl> +<dt>System</dt> +<dd> +<p> +System related software. +</p> +<dl> +<dt>Administration</dt> +<dd> +<p> +Administrative and system configuration utilities, also tools for personal user +settings. +</p> + +<p> +Examples: gnome-control-center, configure-debian, gksu +</p> +</dd> +</dl> +<dl> +<dt>Hardware</dt> +<dd> +<p> +Tools for manipulating specific hardware, especially non-standard laptop +hardware. +</p> + +<p> +Examples: toshutils, nvclock-gtk, nvtv +</p> +</dd> +</dl> +<dl> +<dt>Language Environment</dt> +<dd> +<p> +This section is reserved for language-env as a special case. +</p> +</dd> +</dl> +<dl> +<dt>Monitoring</dt> +<dd> +<p> +System information and monitoring tools, log viewers, etc. +</p> + +<p> +Examples: top, hal-device-manager, gtkdiskfree +</p> +</dd> +</dl> +<dl> +<dt>Package Management</dt> +<dd> +<p> +Package managers and related tools. +</p> + +<p> +Examples: aptitude, deborphan, smartpm +</p> +</dd> +</dl> +<dl> +<dt>Security</dt> +<dd> +<p> +Security, cryptography and privacy related software, antiviruses, tools to +track and report bugs, etc. +</p> + +<p> +Examples: gpgkeys, bastille, avscan +</p> +</dd> +</dl> +</dd> +</dl> +<dl> +<dt>Terminal Emulators</dt> +<dd> +<p> +Graphical terminal emulators. +</p> + +<p> +Examples: xterm, gnome-terminal, rxvt +</p> +</dd> +</dl> +<dl> +<dt>Text</dt> +<dd> +<p> +Text oriented tools like dictionaries, OCR, translation, text analysis +software, etc. +</p> + +<p> +Examples: kdrill, stardict, turkey +</p> +</dd> +</dl> +<dl> +<dt>TV and Radio</dt> +<dd> +<p> +TV-in, TV-out, FM radio, teletext browsers, etc. +</p> + +<p> +Examples: gradio, gatos, alevt +</p> +</dd> +</dl> +<dl> +<dt>Viewers</dt> +<dd> +<p> +Software for viewing images, documents and other (non-video) media. +</p> + +<p> +Examples: gqview, evince, gthumb +</p> +</dd> +</dl> +<dl> +<dt>Video</dt> +<dd> +<p> +Video players, editors, and rippers/recorders. +</p> + +<p> +Examples: istanbul, totem, kino +</p> +</dd> +</dl> +<dl> +<dt>Web Development</dt> +<dd> +<p> +Software for web site editing, web programming, and site administration. +</p> + +<p> +Examples: bluefish, screem, gphpedit +</p> +</dd> +</dl> +</dd> +</dl> +<dl> +<dt>Games</dt> +<dd> +<p> +Games and recreations +</p> +<dl> +<dt>Action</dt> +<dd> +<p> +Games that involve a lot of action and require fast reflexes. +</p> + +<p> +Examples: xsoldier, supertux, xmoto +</p> +</dd> +</dl> +<dl> +<dt>Adventure</dt> +<dd> +<p> +Role playing and adventure games, interactive movies and stories, etc. +</p> + +<p> +Examples: beneath-a-steel-sky, egoboo, kq +</p> +</dd> +</dl> +<dl> +<dt>Blocks</dt> +<dd> +<p> +Tetris-like games involving falling blocks. +</p> + +<p> +Examples: crack-attack, frozen-bubble, netris +</p> +</dd> +</dl> +<dl> +<dt>Board</dt> +<dd> +<p> +Games played on a board. +</p> + +<p> +Examples: phalanx, xshogi, xboard +</p> +</dd> +</dl> +<dl> +<dt>Card</dt> +<dd> +<p> +Games involving a deck of cards. +</p> + +<p> +Examples: pysol, ace-of-penguins, xpat2 +</p> +</dd> +</dl> +<dl> +<dt>Puzzles</dt> +<dd> +<p> +Tests of ingenuity and logic. +</p> + +<p> +Examples: xmpuzzles, sgt-puzzles, enigma +</p> +</dd> +</dl> +<dl> +<dt>Simulation</dt> +<dd> +<p> +Simulations of the real world in all detail and complexity. +</p> + +<p> +Examples: flightgear, torcs +</p> +</dd> +</dl> +<dl> +<dt>Strategy</dt> +<dd> +<p> +Games involving long-term strategic thinking. +</p> + +<p> +Examples: wesnoth, widelands, netpanzer +</p> +</dd> +</dl> +<dl> +<dt>Tools</dt> +<dd> +<p> +Server browsers, configurators, editors, and other game-related tools that are +not games themselves. +</p> + +<p> +Examples: xqf, crystalspace +</p> +</dd> +</dl> +<dl> +<dt>Toys</dt> +<dd> +<p> +Amusements, eye-candy, entertaining demos, screen hacks (screensavers), etc. +</p> + +<p> +Examples: xdesktopwaves, xphoon, xpenguins +</p> +</dd> +</dl> +</dd> +</dl> +<dl> +<dt>Help</dt> +<dd> +<p> +programs that provide user documentation +</p> + +<p> +Examples: debian-reference, apt-howto, dhelp +</p> +</dd> +</dl> +<dl> +<dt>Screen</dt> +<dd> +<p> +Programs that affect the whole screen. +</p> +<dl> +<dt>Saving</dt> +<dd> +<p> +Tools for blanking the screen. Entries of screen hacks and configuration GUIs +should go to other appropriate sections. +</p> + +<p> +Examples: xscreensaver, xlockmore +</p> +</dd> +</dl> +<dl> +<dt>Locking</dt> +<dd> +<p> +Tools for locking the screen. +</p> + +<p> +Examples: xscreensaver, xlockmore +</p> +</dd> +</dl> +</dd> +</dl> +<dl> +<dt>Window Managers</dt> +<dd> +<p> +X window managers. +</p> + +<p> +Examples: fluxbox, metacity, waimea +</p> +</dd> +</dl> +<dl> +<dt>FVWM Modules</dt> +<dd> +<p> +FVWM-based window manager modules. As only modules related to the running +window-manager are displayed, do not create subsections for specific +window-managers. +</p> + +<p> +Examples: fvwm, fvwm-gnome, fvwm95 +</p> +</dd> +</dl> +<dl> +<dt>Window Maker</dt> +<dd> +<p> +This section is reserved for wmaker as a special case. +</p> + +<p> +All wmaker specific entries must go here. +</p> +</dd> +</dl> + +<p> +Users wanting to access some menu entries quickly can also put them in the root +menu. This is done by using <em>section="/"</em>. Package-provided +menu entries must never use this feature. +</p> + +<hr> + +<h2><a name="s3.6"></a>3.6 The <samp>command</samp> field</h2> + +<p> +The command field holds the command that should be executed when the menu entry +is selected. Commands will be executed with <code>sh -c</code> using +</p> + +<pre> + execl("/bin/sh","sh","-c",command) +</pre> + +<p> +or the equivalent. +</p> + +<hr> + +<h2><a name="s3.7"></a>3.7 The <samp>icon</samp> field</h2> + +<p> +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 <code>/usr/share/pixmaps</code>. +</p> + +<p> +Debian package maintainers should ensure that any icons they include for use in +the Debian menus conform to the following points: +</p> +<ol type="1" start="1" > +<li> +<p> +The icons should be in xpm format. +</p> +</li> +</ol> +<ol type="1" start="2" > +<li> +<p> +The icons may not be larger than 32x32 pixels, although smaller sizes are ok. +</p> +</li> +</ol> +<ol type="1" start="3" > +<li> +<p> +The background area of the icon should be transparent, if possible. +</p> +</li> +</ol> + +<p> +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. +</p> + +<p> +If you, as a system administrator, don't like the icons in the menus, simply +change the <samp>icon()</samp> function from the file +<code>/etc/menu-methods/menu.h</code>, and run <code>update-menus</code>. +</p> + +<hr> + +<h2><a name="s3.8"></a>3.8 The <samp>hints</samp> field</h2> + +<p> +Hints are used to help menu structure generated menus in a more optimal way. +For example: +</p> + +<pre> + ?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 +</pre> + +<p> +The above hints will tell <samp>menu</samp> to consider grouping +<samp>emacs</samp> together with other editors that are marked similar. For +example, if <samp>vi</samp> on your system has a hints="Small,Expert" +definition, and there are too many entries in the +<samp>/Applications/Editors</samp> menu entry, then menu will consider creating +a <samp>/Applications/Editors/Expert</samp> submenu, and put both +<samp>vi</samp> and <samp>emacs</samp> in it. (Of course, only if you have +<samp>hint_optimize=true</samp> in your <code>/etc/menu-methods/menu.h</code> +file). +</p> + +<hr> + +<h2><a name="s3.9"></a>3.9 Entries for menu sections.</h2> + +<p> +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 <samp>icon</samp> and <samp>sort</samp>. The syntax +for menu sections entries is the same as for regular entries, the +<samp>section</samp> field holding the name of the parent section. For example +</p> + +<pre> + ?package(local.games): needs="text" title="Games" section="/" sort="001" +</pre> + +<p> +will sort <samp>Games</samp> first. +</p> + +<hr> + +<h2><a name="s3.10"></a>3.10 Fvwm's task and title bars</h2> + +<p> +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 <code>fvwm2</code> to have a few buttons, you +can install files for those packages in <samp>/menu/$package</samp>, containing +a menu entry like this: +</p> + +<pre> + ?Package(xmball):needs=button\ + section=Games/Puzzles\ + icon=path-to-pixmap.xpm\ + title="Xmball"\ + command=/usr/games/xmball +</pre> + +<p> +Then, do the following: +</p> + +<pre> + cd /etc/menu-methods/ + cp fvwm2 fvwm2button + vi fvwm2button +</pre> + +<p> +and remove all the "supported" entries, adding the one below. For +the rest, leave everything the same except those listed below. +</p> + +<pre> + supported + button="+ Style \"" $title "\" TitleIcon" $icon " Exec " $command "\n" + endsupported + startmenu: "AddToTitlebar \n" + endmenu: "\n" + submenutitle:"" + mainmenu: + genmenu: "buttondefs.hook" +</pre> + +<p> +(Of course regular users (not system administrators) can also specify +`buttonfiles' in their ~/.menu/ directory). +</p> + +<hr> + +<p> +[ <a href="ch2.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ 3 ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch4.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - What packages with applications should do</title> + +<link href="index.html" rel="start"> +<link href="ch3.html" rel="prev"> +<link href="ch5.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch4"></a></p> +<hr> + +<p> +[ <a href="ch3.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ 4 ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch5.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 4 - What packages with applications should do +</h1> + +<hr> + +<h2><a name="s4.1"></a>4.1 Providing a menu file</h2> + +<p> +A package should provide a menu file +<code>/usr/share/menu/<package-name></code> that contains information +about each program it likes to make available in the menus. +</p> + +<hr> + +<h2><a name="s4.2"></a>4.2 Adding a hook for dpkg in your packages</h2> + +<p> +The <samp>postinst</samp> script and the <code>postrm</code> script of the +package should include the line +</p> + +<pre> + if test -x /usr/bin/update-menus; then update-menus; fi +</pre> + +<p> +If you are using <code>debhelper</code>, the program +<code>dh_installmenu</code> can do it for you. +</p> + +<hr> + +<p> +[ <a href="ch3.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ 4 ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch5.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - What packages with menu managers should do</title> + +<link href="index.html" rel="start"> +<link href="ch4.html" rel="prev"> +<link href="ch6.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch5"></a></p> +<hr> + +<p> +[ <a href="ch4.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ 5 ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch6.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 5 - What packages with menu managers should do +</h1> + +<hr> + +<p> +Each package containing a <em>menu manager</em> (i.e., a program that can +display a menu) should provide a script or program in +<code>/etc/menu-methods/</code> that can read the menu files. This script will +be executed by <code>update-menus</code>, which will feed the menu entries to +be installed to your script via standard input (stdin). +</p> + +<p> +The scripts in <code>/etc/menu-methods/</code> should be configuration files, +so the user can tune the behaviour of the script, and they must always include +the <code>/etc/menu-methods/menu.h</code> configuration file at the beginning +with the command <samp>!include menu.h</samp> For the same reason, scripts in +<code>/etc/menu-methods/</code> are requested to use the following configurable +functions: <samp>title()</samp> for the title (in place of +<samp>$title</samp>), <samp>icon()</samp> for the icon (in place of +<samp>$icon</samp>), <samp>term()</samp> for running <samp>text</samp> command +under <samp>X11</samp>. <samp>sections_translations()</samp> for the list of +translations of sections name available. This later one is only defined if you +<samp>!include lang.h</samp> +</p> + +<p> +Good examples for these scripts for nearly all Debian window managers are +included in the <samp>menu</samp> package in +<code>/usr/share/doc/menu/examples</code>. 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). +</p> + +<p> +This script should not be executable in the package. Instead the +<samp>postinst</samp> should add the execute bit and then run +<code>update-menus</code> (if it is executable). +</p> + +<p> +Similarly, the <code>postrm</code> script when called with option ``remove'' +should remove the execute bit and run <code>update-menus</code> (if it is +executable). +</p> + +<p> +Here is an example of such a <code>postrm</code> script using <code>sh</code>: +</p> + +<pre> + #!/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 +</pre> + +<p> +And here is a good example for a <code>postinst</code> script: +</p> + +<pre> + #!/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 +</pre> + +<p> +If you are using <code>debhelper</code>, the program +<code>dh_installmenu</code> can help you do it. +</p> + +<p> +Please, do not make your package <em>depend</em> on the menu package! The +preferred way of telling dpkg that your wm can cooperate with menu is: +</p> + +<pre> + Suggests: menu +</pre> + +<p> +Please only consider using "depends" if you feel providing reasonable +defaults for systems without <code>menu</code> will make life very difficult +for you. +</p> + +<hr> + +<p> +[ <a href="ch4.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ 5 ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch6.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - How a user can override the menus</title> + +<link href="index.html" rel="start"> +<link href="ch5.html" rel="prev"> +<link href="ch7.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch6"></a></p> +<hr> + +<p> +[ <a href="ch5.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ 6 ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch7.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 6 - How a user can override the menus +</h1> + +<hr> + +<hr> + +<h2><a name="s6.1"></a>6.1 Configuring the menus</h2> + +<p> +Users can specify their own menu entries in the <code>~/.menu</code> 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 +</p> + +<pre> + ?package(installed-package): +</pre> + +<p> +or +</p> + +<pre> + ?package(local.mystuff): +</pre> + +<p> +if it's something that isn't ``debian-officially'' installed. (Any ``package'' +that starts with ``<samp>local.</samp>'' is considered installed.) +</p> + +<p> +If users want to have their own menu methods, they should create a +<code>~/.menu-methods</code> directory and put all their menu methods in it. +(If <code>~/.menu-methods</code> exists, <code>/etc/menu-methods</code> will +not be searched when a user runs <code>update-menus</code>). +</p> + +<p> +A system administrator should place system-wide menu entries in +<code>/etc/menu</code> (not in <code>/usr/share/menu/package</code>, since +these files will probably be overwritten by a package upgrade). +</p> + +<hr> + +<h2><a name="s6.2"></a>6.2 Specifying that a menu entry should not be displayed</h2> + +<p> +If a user wants to remove the entries of <samp>package</samp> from the system +menu then this will do the trick: +</p> + +<pre> + echo -n > ~/.menu/package +</pre> + +<p> +The zero-size file will tell <code>update-menus</code> that the corresponding +package should not have any menu entries listed. A system administrator can +remove menu entries system-wide with +</p> + +<pre> + echo -n > /etc/menu/package +</pre> + +<hr> + +<h2><a name="s6.3"></a>6.3 Including other files</h2> + +<p> +<var>Historical comment by Joost:</var> +</p> + +<p> +<var>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.</var> +</p> + +<p> +To include the contents of the file <code>/usr/share/menu/somefile</code>, add +this to your menu file: +</p> + +<pre> + !include /usr/share/menu/somefile +</pre> + +<p> +Apart from that, it is of course possible to make the menu entry file +executable (<samp>chmod a+x ~/.menu/package</samp>), and do something like +</p> + +<pre> + #!/bin/sh + cat /usr/share/menu/somefile + sed -e "/unwanted_entry/s/?package(/?package(notinstalled./" \ + /usr/share/menu/someotherfile +</pre> + +<p> +to get the same effect, with the added flexibility of being able to filter out +unwanted lines. +</p> + +<hr> + +<p> +[ <a href="ch5.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ 6 ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch7.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - The internals of the menu package</title> + +<link href="index.html" rel="start"> +<link href="ch6.html" rel="prev"> +<link href="ch8.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch7"></a></p> +<hr> + +<p> +[ <a href="ch6.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ 7 ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch8.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 7 - The internals of the menu package +</h1> + +<hr> + +<hr> + +<h2><a name="s7.1"></a>7.1 The update-menus program</h2> + +<p> +On startup, update-menus checks the file <code>/var/run/update-menus.pid</code> +and the pid in it. If there's an <code>update-menus</code> process with that +pid it kills it. If <code>/var/lib/dpkg/lock</code> 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 <code>/var/lib/dpkg/lock</code> +file approx. every two second until the file's gone. +</p> + +<p> +Once it's decided to run, whether in the background after dpkg exits, or in the +foreground when used with a trigger-capable dpkg, <code>update-menus</code> +reads the menu-entry files in the following directories: +<code>/etc/menu</code>, <code>/usr/lib/menu</code>, +<code>/usr/share/menu</code>, <code>/usr/share/menu/default</code>. (if a user +runs <code>update-menus</code>, it will add <code>~/.menu</code> 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). +</p> + +<p> +Once it's read all menu entry files, <code>update-menus</code> starts all +executable scripts in <code>/etc/menu-methods/</code>, hands the scripts the +previously created buffer via stdin. (If <code>update-menus</code> is run by a +user, it will first try to run the scripts in <code>~/.menu-methods</code>, and +only if that directory doesn't exist, it will run the scripts in +<code>/etc/menu-methods</code>). +</p> + +<p> +Note that as an aid to debugging, one can use +</p> + +<pre> + update-menus --stdout > /tmp/menu-stdin +</pre> + +<p> +and then view the file <code>/tmp/menu-stdin</code> to see exactly what +<code>update-menus</code> handed the menu-methods on their stdin. +</p> + +<p> +This may also be useful for people writing <code>/etc/menu-method/*</code> +scripts: Running <code>update-menus</code> every time you changed something in +the script may be quite time-consuming. So, it's much easier to run +<code>update-menus --stdout</code> once, and then run +</p> + +<pre> + /etc/menu-methods/mymethod < /tmp/menu-stdin +</pre> + +<p> +(and, if that also takes too long, just try editing /tmp/menu-stdin, and +removing 90% or so of all entries) +</p> + +<hr> + +<h2><a name="s7.2"></a>7.2 The install-menu program</h2> + +<p> +The files <code>/etc/menu-methods/$wm</code> are executable config files that +start with the line +</p> + +<pre> + #!/usr/bin/install-menu +</pre> + +<p> +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: +</p> +<ol type="1" start="1" > +<li> +<p> +the compatibility mode ("menu-1" or "menu-2"). +</p> +</li> +</ol> +<ol type="1" start="2" > +<li> +<p> +where the various files should be stored/read. +</p> +</li> +</ol> +<ol type="1" start="3" > +<li> +<p> +what "needs" are supported, and what wrapper files should be used for +each "type". +</p> +</li> +</ol> +<ol type="1" start="4" > +<li> +<p> +how to remove the generated menu files. +</p> +</li> +</ol> + +<p> +See <code>/usr/share/doc/menu/examples/</code> of the menu package for more +comments. +</p> + +<p> +Options to <code>install-menu</code>: +</p> + +<pre> + --remove Remove the menu files instead of generating them. + --verbose Output outline of operations that are performed. +</pre> + +<p> +Some window managers don't support an `include'-like statement in their +<code>system.*rc</code> files (like <code>m4</code> or <code>cpp</code> +preprocessing); they cannot read the <code>menudefs.hook</code> file generated +by install-menu from their <code>system.*rc</code> config file. To still be +able to use them, <code>install-menu</code> will copy the file +<code>$path/$examplercfile</code> to <code>$path/$rcfile</code> (with +<code>$examplercfile</code> and <code>$rcfile</code> defined in the +<code>install-menu</code> config file, and <code>$path</code> either the +<code>$rootprefix</code> or <code>${HOME}/$userprefix</code>, depending on +whether root or user executed the file.), and replace all occurrences of +``install-menu-defs'' with the <code>$genmenu</code> file it just generated. +</p> + +<p> +As an example, consider the following: +<samp>examplercfile=system.foo-wm-example</samp>, +<samp>rcfile=system.foo-wm</samp>, <samp>genmenu=menudefs.hook</samp> and +<samp>rootprefix=/var/lib/foo-wm/menu</samp>. Now, if +<code>install-menu</code> gets run, it will first generate the file +<code>/var/lib/foo-wm/menu/menudefs.hook</code>. Next, it will line-by-line +read the file <code>/var/lib/foo-wm/menu/system.foo-wm-example</code> and copy +its contents to <code>/var/lib/foo-wm/menu/system.foo-wm</code>, replacing +every occurrence of the string <samp>install-menu-defs</samp> with the contents +of the file <code>/var/lib/foo-wm/menu/menudefs.hook</code>. +</p> + +<p> +To activate the file copying in this way, simply define the +<samp>$examplercfile</samp> and <samp>$rcfile</samp> variables in the +<code>install-menu</code> configuration file (for example, see +<code>/etc/menu-methods/fvwm</code>), and make sure there is a +<code>$path/$examplercfile</code> (<samp>$path</samp> being either +<samp>$rootprefix</samp>, or <code>$userprefix</code>.) +</p> + +<p> +If you are writing a menu method, you can use the following to make debugging +it somewhat more easily: +</p> +<ol type="1" start="1" > +<li> +<p> +use <samp>update-menus --stdout > /tmp/menu-stdin</samp> to create a list of +menu entries in <code>/tmp/menu-stdin</code> and then +</p> +</li> +</ol> +<ol type="1" start="2" > +<li> +<p> +you can run just your menu-method with (if it's called wm): +</p> + +<pre> + ./wm -v < /tmp/menu-stdin +</pre> +</li> +</ol> + +<hr> + +<h2><a name="s7.3"></a>7.3 The install-menu config script definitions</h2> + +<p> +The menu-methods in <code>/etc/menu-methods/*</code> are basically made up of a +lot of ``tag=string'' definitions, telling <code>install-menu</code> how to +generate a <code>system.${wm}rc</code> script. This way you can tune the look +of generated <code>system.${wm}rc</code> to your needs. +</p> + +<p> +In the following, something like +</p> + +<pre> + treewalk="c(m)" +</pre> + +<p> +means that the treewalk variable by default has the value "c(m)". +</p> + +<p> +For examples of what these scripts can look like, see +<code>/usr/share/doc/menu/examples/*</code>. +</p> +<dl> +<dt><samp>compat="menu-1"</samp></dt> +<dd> +<p> +Two mode are defined: +</p> +<dl> +<dt><samp>"menu-1"</samp></dt> +<dd> +<p> +menu directives are terminated by an end-of-line character. +</p> +</dd> +</dl> +<dl> +<dt><samp>"menu-2"</samp></dt> +<dd> +<p> +menu directives are terminated by a semicolon character. +</p> +</dd> +</dl> + +<p> +This must be just after the <samp>!include "menu.h"</samp> directive +so that <code>menu.h</code> can use its own compat mode. +</p> +</dd> +</dl> +<dl> +<dt><samp>outputencoding="UTF-8"</samp></dt> +<dd> +<p> +Set the encoding used for output files. Use <samp>iconv --list</samp> 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. +</p> +</dd> +</dl> +<dl> +<dt><samp>outputlanguage=""</samp></dt> +<dd> +<p> +If set to "C" automatic translations will be disabled. Note that you +can still use translate() to perform explicit translation. +</p> +</dd> +</dl> +<dl> +<dt><samp>supported</samp></dt> +<dt><samp>endsupported</samp></dt> +<dd> +<p> +Between the <samp>supported</samp> and <samp>endsupported</samp> 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: +</p> + +<pre> + function q($s) = "\"" esc($s,"\\\"") "\"" + supported + x11 =" ShowEntry(" q(title()) ", " q($command) ")" + text=" ShowEntry(" q(title()) ", " q(term()) ")" + endsupported +</pre> + +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt><samp>startmenu=""</samp></dt> +<dt><samp>endmenu=""</samp></dt> +<dt><samp>submenutitle=""</samp></dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt><samp>treewalk="c(m)"</samp></dt> +<dd> +<p> +This string defines in what order to dump the <samp>$startmenu</samp>, +<samp>$endmenu</samp>, and <samp>$submenutitle</samp> (and its children). Each +char in the string refers to: +</p> + +<pre> + 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. +</pre> + +<p> +The default is "c(m)". For olvwm, one needs: "(M)" +</p> +</dd> +</dl> +<dl> +<dt><samp>genmenu=""</samp></dt> +<dd> +<p> +The menu file to generate (usually something like +<samp>system."$wm"rc</samp>). The file itself may depend on the +level or title that is currently being worked on, like +</p> + +<pre> + genmenu="/subdir/" replacewith($section," ","_") "/rc.menu" +</pre> + +<p> +(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 <samp>endmenu=</samp> will override the +startmenu stuff (but you probably only need one of the two anyway). +</p> +</dd> +</dl> +<dl> +<dt><samp>rootsection="/Debian"</samp></dt> +<dd> +<p> +the prefix every <samp>$section</samp> variable gets. +</p> +</dd> +</dl> +<dl> +<dt><samp>prerun=""</samp></dt> +<dt><samp>postrun=""</samp></dt> +<dd> +<p> +The commands to run before and after, respectively, the actual generation of +the <code>menudefs.hook</code> (genmenu) file. Commands will be executed by +<code>sh</code>. Example: +</p> + +<pre> + prerun="rm -rf " prefix() "/*" + postrun="killall -USR1 fvwm2" +</pre> + +<p> +(Substitution works just like the supported stuff, see below). +</p> +</dd> +</dl> +<dl> +<dt><samp>preruntest=""</samp></dt> +<dd> +<p> +Just like prerun, but if the return value of the command is non-zero, menu will +quit. +</p> +</dd> +</dl> +<dl> +<dt><samp>also_run=""</samp></dt> +<dd> +<p> +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 <samp>prerun</samp> and +all of the hint stuff are ignored. +</p> +</dd> +</dl> +<dl> +<dt><samp>removemenu=""</samp></dt> +<dd> +<p> +The command to run when the menu-method is invoked with the option +<samp>--remove</samp>. This should remove all the autogenerated menu files. +If this option is not present, then install menu will remove +<samp>genmenu</samp> if it is a constant string and <samp>rcfile</samp> if it +is defined, and try to remove <samp>prefix()</samp> if it is empty. +</p> +</dd> +</dl> +<dl> +<dt><samp>onlyrunasroot=false</samp></dt> +<dt><samp>onlyrunasuser=false</samp></dt> +<dd> +<p> +If <samp>onlyrunasroot</samp> is set to true, <code>install-menu</code> will +quit silently when run as a user. Similarly for <samp>onlyrunasuser</samp>. +<var><samp>onlyrunasroot</samp> is deprecated since it is simpler to just not +define <samp>userprefix</samp>.</var> On the other hand, +<samp>onlyrunasuser</samp> might be needed if you use <samp>rcfile</samp> since +<samp>rootprefix</samp> is used as a fallback location for the template. +</p> +</dd> +</dl> +<dl> +<dt><samp>preoutput="#Automatically generated file. Do not edit (see /usr/share/doc/menu/html)\n\n"</samp></dt> +<dt><samp>postoutput=""</samp></dt> +<dd> +<p> +Text to put at the beginning resp. end of the generated file ($genmenu). +</p> +</dd> +</dl> +<dl> +<dt><samp>command=""</samp></dt> +<dd> +<p> +A command to run instead of <code>install-menus</code>. 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. +</p> + +<p> +Example: +</p> + +<pre> + command="cat > /tmp/menu-stdin" +</pre> +</dd> +</dl> +<dl> +<dt><samp>hotkeyexclude=""</samp></dt> +<dd> +<p> +Keys not to use for hotkey generation. You can use the same variables and +functions here as in for example the startmenu sections. +</p> + +<p> +Example: +</p> + +<pre> + hotkeyexclude="q" $section +</pre> +</dd> +</dl> +<dl> +<dt><samp>hotkeycase="insensitive"</samp></dt> +<dd> +<p> +can be either "insensitive" or "sensitive". Determines +whether the hotkeys can be of mixed case (<samp>fvwm2</samp> reads the hotkeys +case-insensitive, <samp>pdmenu</samp> 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". +</p> +</dd> +</dl> +<dl> +<dt><samp>sort=$sort ":" $title</samp></dt> +<dd> +<p> +Entries within one menu will be alphabetically sorted by whatever sort returns. +So, if you do <samp>sort=ifelse($command, "1", +"0"):$title</samp>, then all submenus will appear above the commands +in a submenu. (A submenu always has <samp>$command=""</samp>). Or, +as Joey Hess writes: +</p> + +<pre> + 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.) +</pre> +</dd> +</dl> +<dl> +<dt><samp>rcfile=""</samp></dt> +<dd> +<p> +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 <samp>system."$wm"rc-menu</samp>, 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 <samp>system."$wm"rc-menu</samp> file. This will then get +replaced by the <samp>$genmenu</samp> file that was just created (see also +<samp>$examplercfile</samp>). +</p> +</dd> +</dl> +<dl> +<dt><samp>examplercfile=""</samp></dt> +<dd> +<p> +if needed (see <samp>rcfile</samp>), this is the +<samp>system.rc"$wm"-menu</samp> file. In that case, make +<samp>rcfile=system.rc"$wm"</samp>. +</p> +</dd> +</dl> +<dl> +<dt><samp>rootprefix=""</samp></dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt><samp>userprefix=""</samp></dt> +<dd> +<p> +As <samp>rootprefix</samp>, 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. +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_optimize=false</samp></dt> +<dd> +<p> +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). +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_nentry=6</samp></dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_topnentry=5</samp></dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_mixedpenalty=15.0</samp></dt> +<dd> +<p> +Penalty for `mixed' menus. Mixed menus are those with both submenus and direct +commands in them. +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_minhintfreq=0.1</samp></dt> +<dd> +<p> +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). +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_mlpenalty=2000</samp></dt> +<dd> +<p> +`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. +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_max_ntry=4</samp></dt> +<dd> +<p> +menu will recursively, for each node, try the hint_max_ntry best local +menu-divisions. +</p> +</dd> +</dl> +<dl> +<dt><samp>hints_max_iter_hint=5</samp></dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt><samp>hint_debug=false</samp></dt> +<dd> +<p> +Set to true if you want to see loads and loads of debug output. +</p> +</dd> +</dl> + +<hr> + +<h2><a name="s7.4"></a>7.4 Hints, tree optimization</h2> + +<p> +The hints actually work in a rather strange way: when +<samp>hint_optimize=true</samp> then all <samp>$section</samp> elements are +added to the specified <samp>$hints</samp> variable, and the order +(<samp>/Applications/Editors</samp> or <samp>/Editors/Applications</samp>) 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: +</p> + +<p> +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 +</p> + +<pre> + Good + Hell + Microsoft +</pre> + +<p> +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 +</p> + +<pre> + Good + Hell + Heaven +</pre> + +<p> +as now it isn't clear whether to visit the Good or the Heaven submenu. +</p> + +<p> +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. +</p> + +<hr> + +<p> +[ <a href="ch6.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ 7 ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch8.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System - Variables and functions in the install-menu scripts</title> + +<link href="index.html" rel="start"> +<link href="ch7.html" rel="prev"> +<link href="index.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="ch8"></a></p> +<hr> + +<p> +[ <a href="ch7.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ 8 ] +[ <a href="index.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br>Chapter 8 - Variables and functions in the install-menu scripts +</h1> + +<hr> + +<p> +The supported "needs" definitions and "startmenu=", +"endmenu=" and "submenutitle=" are interpreted as follows: +</p> + +<hr> + +<h2><a name="s8.1"></a>8.1 String constants</h2> + +<p> +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). +</p> + +<hr> + +<h2><a name="s8.2"></a>8.2 Variables</h2> + +<p> +Anything matching $[a-z,A-Z,_]* is interpreted as a variable, and the +corresponding definition from the menu entry is substituted. +</p> + +<hr> + +<h3><a name="s8.2.1"></a>8.2.1 Special variables</h3> + +<p> +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). +</p> +<dl> +<dt>needs:</dt> +<dd> +<p> +Used to determine whether the window manager supports this menu entry. +</p> +</dd> +</dl> +<dl> +<dt>command:</dt> +<dd> +<p> +If this is undefined, this menu entry is taken as defining a sub-menu. This +way you can specify icons of sub-menus. +</p> +</dd> +</dl> +<dl> +<dt>title!:</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>sort:</dt> +<dd> +<p> +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 "|" +</p> +</dd> +</dl> +<dl> +<dt>section!:</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>basesection!:</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>hotkey!:</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> + +<hr> + +<h3><a name="s8.2.2"></a>8.2.2 Preferred variables</h3> + +<p> +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. +</p> +<dl> +<dt>icon:</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>icon32x32:</dt> +<dd> +<p> +The location of a 32x32 icon file for this menu entry. +</p> +</dd> +</dl> +<dl> +<dt>icon16x16:</dt> +<dd> +<p> +The location of a 16x16 icon file for this menu entry. This allows users to +choose between 16x16 and 32x32 icon. +</p> +</dd> +</dl> +<dl> +<dt>longtitle:</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>description:</dt> +<dd> +<p> +An even longer description (about 5 lines). For example, a description of the +documentation in the dwww generated html pages. +</p> +</dd> +</dl> + +<hr> + +<h3><a name="s8.2.3"></a>8.2.3 Suggested variables</h3> + +<p> +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: +</p> +<dl> +<dt>visible</dt> +<dd> +<p> +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). +</p> +</dd> +</dl> +<dl> +<dt>geometry</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> + +<hr> + +<h2><a name="s8.3"></a>8.3 Functions</h2> + +<p> +Anything matching <samp>[a-zA-Z_]+</samp> 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. +</p> +<dl> +<dt>prefix()</dt> +<dd> +<p> +returns the current prefix dir: either $rootprefix, or $HOME/$userprefix, +depending on who runs install-menu +</p> +</dd> +</dl> +<dl> +<dt>ifroot($rootarg, $userarg)</dt> +<dd> +<p> +if(getuid()==0) print $rootarg, else print $userarg +</p> +</dd> +</dl> +<dl> +<dt>print($arg)</dt> +<dd> +<p> +Same as just $arg; if $arg is empty, generate an error. +</p> +</dd> +</dl> +<dl> +<dt>nstring($n, $string)</dt> +<dd> +<p> +write $string $n times. So, nstring(3,"Aa") writes +"AaAaAa". (Useful in combination with level()). +</p> +</dd> +</dl> +<dl> +<dt>esc($arg1,$arg2)</dt> +<dd> +<p> +Print $arg1, but escape all occurrences of characters in $arg2 with a '\' +(thus, if arg1="hello", arg2="lo", print +"he\l\l\o"). +</p> +</dd> +</dl> +<dl> +<dt>escwith($arg1, $arg2, $arg3)</dt> +<dd> +<p> +Same as esc, but use $arg3 as escape sequence. +</p> +</dd> +</dl> +<dl> +<dt>escfirst($arg1, $arg2, $arg3)</dt> +<dd> +<p> +Same as escwith, but only escapes first occurrence of $arg2. +</p> +</dd> +</dl> +<dl> +<dt>cppesc($arg1)</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>tolower($arg)</dt> +<dt>toupper($arg)</dt> +<dd> +<p> +Returns the argument set in lowercases resp uppercases. +</p> +</dd> +</dl> +<dl> +<dt>replacewith($s, $replace, $with)</dt> +<dd> +<p> +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" +</p> +</dd> +</dl> +<dl> +<dt>replace($s, $replace, $with)</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>ifempty($arg1, $arg2)</dt> +<dd> +<p> +If $arg1 is empty, print $arg2, otherwise print nothing. For compatibility, +$arg1="none" is interpreted as empty. +</p> +</dd> +</dl> +<dl> +<dt>ifnempty($arg1, $arg2)</dt> +<dd> +<p> +If $arg1 is not empty, print $arg2. For compatibility, the string +"none" is seen as empty. +</p> +</dd> +</dl> +<dl> +<dt>ifelse($arg1,$arg2,$arg3)</dt> +<dd> +<p> +If $arg1 is non-empty, print $arg2, otherwise $arg3. For compatibility, the +string "none" is seen as empty. +</p> +</dd> +</dl> +<dl> +<dt>ifeq($arg1, $arg2, $arg3)</dt> +<dd> +<p> +If ($arg1==$arg2) then print $arg3 +</p> +</dd> +</dl> +<dl> +<dt>ifneq($arg1, $arg2, $arg3)</dt> +<dd> +<p> +If ($arg1!=$arg2) then print $arg3 +</p> +</dd> +</dl> +<dl> +<dt>ifeqelse($arg1, $arg2, $arg3, $arg4)</dt> +<dd> +<p> +If ($arg1==$arg2) then print $arg3 else print $arg4 +</p> +</dd> +</dl> +<dl> +<dt>cond_surr($arg1, $arg2, $arg3)</dt> +<dd> +<p> +If $arg1 is non-empty print $arg2$arg1$arg3, otherwise print nothing. For +compatibility, $arg1="none" is interpreted as empty. +</p> +</dd> +</dl> +<dl> +<dt>iffile($arg1, $arg2)</dt> +<dd> +<p> +If file $arg1 exists, and can be opened for reading by whoever started the +current process, return $arg2, otherwise return nothing. +</p> +</dd> +</dl> +<dl> +<dt>ifelsefile($arg1, $arg2, $arg3)</dt> +<dd> +<p> +If file $arg1 exists, and can be opened for reading by whoever started the +current process, return $arg2, otherwise return $arg3. +</p> +</dd> +</dl> +<dl> +<dt>catfile($arg1)</dt> +<dd> +<p> +Return the contents of file $arg1. +</p> +</dd> +</dl> +<dl> +<dt>shell($arg1)</dt> +<dd> +<p> +Return the output of the shell command $arg1. +</p> +</dd> +</dl> +<dl> +<dt>forall($array, "var", $exec)</dt> +<dd> +<p> +For each element of the column separated array $array, set $var to that +element, and print $exec. Example: +</p> + +<pre> + !include lang.h + forall(sections_translations(), "lang", \ + " section[" $lang "]=" translate($lang, title()) "\n") +</pre> +</dd> +</dl> +<dl> +<dt>parent($arg)</dt> +<dd> +<p> +for $arg a "directory", return parent directory: +parent("/Debian/Applications/Editors") = +"/Debian/Applications". +</p> +</dd> +</dl> +<dl> +<dt>basename($arg)</dt> +<dd> +<p> +return the last part of the parent directory: +basename("/Debian/Applications/Editors") = "Applications". +</p> +</dd> +</dl> +<dl> +<dt>stripdir($arg)</dt> +<dd> +<p> +everything after the last slash, i.e. what basename() should have returned: +stripdir("/Debian/Applications/Editors") = "Editors". +</p> +</dd> +</dl> +<dl> +<dt>entrycount()</dt> +<dd> +<p> +the number of entries in this menu. +</p> +</dd> +</dl> +<dl> +<dt>entryindex()</dt> +<dd> +<p> +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. +</p> +</dd> +</dl> +<dl> +<dt>firstentry($arg)</dt> +<dd> +<p> +return $arg if this is the first entry of this menu (that is, entryindex() = +0). Else, return nothing. +</p> +</dd> +</dl> +<dl> +<dt>lastentry()</dt> +<dd> +<p> +return $arg if this is the last entry in this menu (that is, entryindex() = +entrycount() -1). Else, return nothing. +</p> +</dd> +</dl> +<dl> +<dt>level()</dt> +<dd> +<p> +return nesting of this menu in the total menu tree. +</p> +</dd> +</dl> +<dl> +<dt>add($arg1,$arg2)</dt> +<dt>sub($arg1,$arg2)</dt> +<dt>mult($arg1,$arg2)</dt> +<dt>div($arg1,$arg2)</dt> +<dd> +<p> +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()) +</p> +</dd> +</dl> +<dl> +<dt>rcfile()</dt> +<dt>examplercfile()</dt> +<dt>mainmenutitle()</dt> +<dt>rootsection()</dt> +<dt>rootprefix()</dt> +<dt>userprefix()</dt> +<dt>treewalk()</dt> +<dt>postoutput()</dt> +<dt>preoutput()</dt> +<dd> +<p> +These functions all output whatever they were defined to be in the menu-method +file. +</p> +</dd> +</dl> +<dl> +<dt>translate($lang, $text)</dt> +<dd> +<p> +Translate $text into $lang using gettext, see <samp>forall</samp> 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. +</p> +</dd> +</dl> +<dl> +<dt>implicit concatenation</dt> +<dd> +<p> +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" +</p> +</dd> +</dl> + +<hr> + +<p> +[ <a href="ch7.html">previous</a> ] +[ <a href="index.html#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ 8 ] +[ <a href="index.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + 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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> + +<html> + +<head> + +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> + +<title>Debian Menu System</title> + +<link href="index.html" rel="start"> +<link href="ch8.html" rel="prev"> +<link href="ch1.html" rel="next"> +<link href="index.html#contents" rel="contents"> +<link href="index.html#copyright" rel="copyright"> +<link href="ch1.html" rel="chapter" title="1 Introduction"> +<link href="ch2.html" rel="chapter" title="2 Menu from the viewpoint of a user"> +<link href="ch3.html" rel="chapter" title="3 The menu file"> +<link href="ch4.html" rel="chapter" title="4 What packages with applications should do"> +<link href="ch5.html" rel="chapter" title="5 What packages with menu managers should do"> +<link href="ch6.html" rel="chapter" title="6 How a user can override the menus"> +<link href="ch7.html" rel="chapter" title="7 The internals of the menu package"> +<link href="ch8.html" rel="chapter" title="8 Variables and functions in the install-menu scripts"> +<link href="ch2.html#s2.1" rel="section" title="2.1 How/when do the window manager startup files get created?"> +<link href="ch2.html#s2.2" rel="section" title="2.2 Tuning of the generated window manager startup files"> +<link href="ch2.html#s2.3" rel="section" title="2.3 Optimization of menu tree: hints"> +<link href="ch3.html#s3.1" rel="section" title="3.1 Location"> +<link href="ch3.html#s3.2" rel="section" title="3.2 Syntax"> +<link href="ch3.html#s3.3" rel="section" title="3.3 The title field"> +<link href="ch3.html#s3.4" rel="section" title="3.4 The needs field"> +<link href="ch3.html#s3.5" rel="section" title="3.5 The section field"> +<link href="ch3.html#s3.6" rel="section" title="3.6 The command field"> +<link href="ch3.html#s3.7" rel="section" title="3.7 The icon field"> +<link href="ch3.html#s3.8" rel="section" title="3.8 The hints field"> +<link href="ch3.html#s3.9" rel="section" title="3.9 Entries for menu sections."> +<link href="ch3.html#s3.10" rel="section" title="3.10 Fvwm's task and title bars"> +<link href="ch4.html#s4.1" rel="section" title="4.1 Providing a menu file"> +<link href="ch4.html#s4.2" rel="section" title="4.2 Adding a hook for dpkg in your packages"> +<link href="ch6.html#s6.1" rel="section" title="6.1 Configuring the menus"> +<link href="ch6.html#s6.2" rel="section" title="6.2 Specifying that a menu entry should not be displayed"> +<link href="ch6.html#s6.3" rel="section" title="6.3 Including other files"> +<link href="ch7.html#s7.1" rel="section" title="7.1 The update-menus program"> +<link href="ch7.html#s7.2" rel="section" title="7.2 The install-menu program"> +<link href="ch7.html#s7.3" rel="section" title="7.3 The install-menu config script definitions"> +<link href="ch7.html#s7.4" rel="section" title="7.4 Hints, tree optimization"> +<link href="ch8.html#s8.1" rel="section" title="8.1 String constants"> +<link href="ch8.html#s8.2" rel="section" title="8.2 Variables"> +<link href="ch8.html#s8.3" rel="section" title="8.3 Functions"> +<link href="ch8.html#s8.2.1" rel="subsection" title="8.2.1 Special variables"> +<link href="ch8.html#s8.2.2" rel="subsection" title="8.2.2 Preferred variables"> +<link href="ch8.html#s8.2.3" rel="subsection" title="8.2.3 Suggested variables"> + +</head> + +<body> + +<p><a name="index"></a></p> +<hr> + +<p> +[ <a href="ch8.html">previous</a> ] +[ <a href="#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch1.html">next</a> ] +</p> + +<hr> + +<h1> +Debian Menu System +<br></h1> + +<hr> + +<h2><a name="abstract"></a>Abstract</h2> + +<p> +The <samp>menu</samp> package was inspired by the +<code>install-fvwm2-menu</code> program from the old <code>fvwm2</code> +package. However, <samp>menu</samp> tries to provide a more general interface +for menu building. With the <code>update-menus</code> 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. +</p> + +<hr> + +<h2><a name="copyright"></a>Copyright Notice</h2> + +<p> +Copyright ©1997 Joost Witteveen, Joey Hess, Christian Schwarz. ©2002-2005 Bill Allombert. +</p> + +<p> +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. +</p> + +<p> +This is distributed in the hope that it will be useful, but <em>without any +warranty</em>; without even the implied warranty of merchantability or fitness +for a particular purpose. See the GNU General Public License for more details. +</p> + +<p> +A copy of the GNU General Public License is available as +<code>/usr/share/common-licenses/GPL</code> in the Debian GNU/Linux +distribution or on the World Wide Web at +<samp>http://www.gnu.org/copyleft/gpl.html</samp>. You can also obtain it by +writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, +Boston, MA 02110-1301 USA +</p> + +<hr> + +<h2><a name="contents"></a>Contents</h2> + +<ul> +<li><a href="ch1.html">1 Introduction</a><li><a href="ch2.html">2 Menu from the viewpoint of a user</a> + <ul> + <li><a href="ch2.html#s2.1">2.1 How/when do the window manager startup files get created?</a></li> + <li><a href="ch2.html#s2.2">2.2 Tuning of the generated window manager startup files</a></li> + <li><a href="ch2.html#s2.3">2.3 Optimization of menu tree: hints</a> + </ul></li> +<li><a href="ch3.html">3 The menu file</a> + <ul> + <li><a href="ch3.html#s3.1">3.1 Location</a></li> + <li><a href="ch3.html#s3.2">3.2 Syntax</a></li> + <li><a href="ch3.html#s3.3">3.3 The <samp>title</samp> field</a></li> + <li><a href="ch3.html#s3.4">3.4 The <samp>needs</samp> field</a></li> + <li><a href="ch3.html#s3.5">3.5 The <samp>section</samp> field</a></li> + <li><a href="ch3.html#s3.6">3.6 The <samp>command</samp> field</a></li> + <li><a href="ch3.html#s3.7">3.7 The <samp>icon</samp> field</a></li> + <li><a href="ch3.html#s3.8">3.8 The <samp>hints</samp> field</a></li> + <li><a href="ch3.html#s3.9">3.9 Entries for menu sections.</a></li> + <li><a href="ch3.html#s3.10">3.10 Fvwm's task and title bars</a> + </ul></li> +<li><a href="ch4.html">4 What packages with applications should do</a> + <ul> + <li><a href="ch4.html#s4.1">4.1 Providing a menu file</a></li> + <li><a href="ch4.html#s4.2">4.2 Adding a hook for dpkg in your packages</a> + </ul></li> +<li><a href="ch5.html">5 What packages with menu managers should do</a><li><a href="ch6.html">6 How a user can override the menus</a> + <ul> + <li><a href="ch6.html#s6.1">6.1 Configuring the menus</a></li> + <li><a href="ch6.html#s6.2">6.2 Specifying that a menu entry should not be displayed</a></li> + <li><a href="ch6.html#s6.3">6.3 Including other files</a> + </ul></li> +<li><a href="ch7.html">7 The internals of the menu package</a> + <ul> + <li><a href="ch7.html#s7.1">7.1 The update-menus program</a></li> + <li><a href="ch7.html#s7.2">7.2 The install-menu program</a></li> + <li><a href="ch7.html#s7.3">7.3 The install-menu config script definitions</a></li> + <li><a href="ch7.html#s7.4">7.4 Hints, tree optimization</a> + </ul></li> +<li><a href="ch8.html">8 Variables and functions in the install-menu scripts</a> + <ul> + <li><a href="ch8.html#s8.1">8.1 String constants</a></li> + <li><a href="ch8.html#s8.2">8.2 Variables</a></li> + <li><a href="ch8.html#s8.3">8.3 Functions</a></li> + </ul></li> +</ul> + +<hr> + +<p> +[ <a href="ch8.html">previous</a> ] +[ <a href="#contents">Contents</a> ] +[ <a href="ch1.html">1</a> ] +[ <a href="ch2.html">2</a> ] +[ <a href="ch3.html">3</a> ] +[ <a href="ch4.html">4</a> ] +[ <a href="ch5.html">5</a> ] +[ <a href="ch6.html">6</a> ] +[ <a href="ch7.html">7</a> ] +[ <a href="ch8.html">8</a> ] +[ <a href="ch1.html">next</a> ] +</p> + +<hr> + +<p> +Debian Menu System +</p> + +<address> +version 1.4, 10 November 2011<br> +<br> +Joost Witteveen <code><a href="mailto:joostje@debian.org">joostje@debian.org</a></code><br> +Joey Hess <code><a href="mailto:joeyh@debian.org">joeyh@debian.org</a></code><br> +Christian Schwarz <code><a href="mailto:schwarz@debian.org">schwarz@debian.org</a></code><br> +Bill Allombert <code><a href="mailto:ballombe@debian.org">ballombe@debian.org</a></code><br> +<br> +</address> +<hr> + +</body> + +</html> + diff --git a/doc/menu.info.gz b/doc/menu.info.gz Binary files differnew file mode 100644 index 0000000..7484ef8 --- /dev/null +++ b/doc/menu.info.gz diff --git a/doc/menu.sgml b/doc/menu.sgml new file mode 100644 index 0000000..bf189be --- /dev/null +++ b/doc/menu.sgml @@ -0,0 +1,1758 @@ +<!doctype debiandoc system> + +<!-- + Debian Menu System + Copyright (C) 1997 Joost Witteveen, Joey Hess, Christian Schwarz; + Modification (C) 2002-2005 Bill Allombert + released under the terms of the GNU + General Public License, version 2 or (at your option) any later. + --> + +<book> + +<title>Debian Menu System +<author>Joost Witteveen <email/joostje@debian.org/ +<author>Joey Hess <email/joeyh@debian.org/ +<author>Christian Schwarz <email/schwarz@debian.org/ +<author>Bill Allombert <email/ballombe@debian.org/ +<version>version 1.4, <date> + +<abstract> +The <tt/menu/ package was inspired by the <prgn/install-fvwm2-menu/ +program from the old <prgn/fvwm2/ package. However, <tt/menu/ tries to +provide a more general interface for menu building. With the +<prgn/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. +</abstract> + +<copyright>Copyright ©1997 Joost Witteveen, Joey Hess, Christian Schwarz. +©2002-2005 Bill Allombert. +<p> + +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. +<p> + +This is distributed in the hope that it will be useful, but +<em>without any warranty</em>; without even the implied warranty of +merchantability or fitness for a particular purpose. See the GNU +General Public License for more details. +<p> + +A copy of the GNU General Public License is available as +<file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux +distribution or on the World Wide Web at +<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it +by writing to the Free Software Foundation, Inc., +51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +<p> + +<toc sect> + +<chapt>Introduction +<p> + +Before the advent of <prgn/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, <prgn/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. +<p> + +<prgn/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. <prgn/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 <prgn/update-menus/ as that user, thus creating +window-manager startup files that are used in preference to the +systemwide files. +<p> + +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 +<tt>/Applications/Editors</tt>, 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 +<tt>/Applications/Editors</tt> tree in, say <tt>Editors/Beginner</tt>, +<tt>Editors/Experienced</tt>, or whatever, if there are many entries in that +submenu, or maybe even totally removing <tt>/Applications/Editors</tt> 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). + +<p> + +Each package that needs to add an entry to the menu tree, +includes a menu file <file>/usr/share/menu/package-name</file>. In +this file, it will have one line per menu entry, like this (copied +from <file>/usr/share/menu/xbase</file>): +<example> + ?package(xbase):command="/usr/bin/xedit" needs="X11" \ + section="Applications/Editors" title="Xedit" \ + hints="Beginner,Small" +</example> +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 <tt>/Applications/Editors</tt> +is overfull, it could put Xedit in a <tt>Applications/Editors/Beginner</tt> +or <tt>Applications/Editors/Small</tt> subsection. + +<p> + +Whenever <tt/root/ runs <prgn/update-menus/, it will check all +menu files in <file>/etc/menu</file>, <file>/usr/lib/menu</file>, +<file>/usr/share/menu</file>, and run the installation scripts that display +managers like <prgn/fvwm2/ should provide in <file>/etc/menu-methods</file>. +<p> + +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.) +<p> + +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. +<p> + +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). + +<chapt> Menu from the viewpoint of a user +<p> +<sect> How/when do the window manager startup files get created? +<p> +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. +<p> +When a package that wants to add something to the menu tree gets +installed, it will run <prgn/update-menus/ in its <file/postinst/ script. +Update-menus then reads in all menu files in <file>/etc/menu/</file>, +<file>/usr/lib/menu</file>, <file>/usr/share/menu</file> and +<file>/usr/share/menu/default</file>, and stores the menu entries of all +installed packages in memory. Once that has been done, it will run the +menu-methods in +<file>/etc/menu-methods/*</file>, 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 +<file>/etc/menu-methods/</file>. 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 +<prgn>install-menu</prgn> program. This program can generate the +startupfiles for just about every window manager. + +<sect> Tuning of the generated window manager startup files +<p> + +In principle this is a very window-manager specific business. +But for all window managers (and others) applies: +<p> +The file to attack is the menu-method in +<file>/etc/menu-methods/$wm</file>, with <tt/$wm/ the +name of your window manager. However, if this menu-method +<tt/!include/-s the <file/menu.h/ file (as it should), you can also edit +that file, to make your changes work for every installed window +manager. +<p> +If the menu-method file of your window manager does <tt/!include/ the +<file/menu.h/ file, and makes proper use of the definitions in there, +then you can look at the comments in that <file/menu.h/ file to see how +you can make minor adjustments to the look of your menus in your +window manager. +<p> +To generally change the menu tree, see the next section. + +<sect> Optimization of menu tree: hints +<p> +If <tt/hint_optimize=true/ has been set in a menu-method script (actually, that definition should appear in +the <tt/!include/-ed <tt/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 <tt/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. + +<chapt> The menu file +<p> +<sect> Location +<p> +Packages-provided menu files should be in <file>/usr/share/menu/</file>, +unless the menu files are actually executable binaries, in which case they go +in <file>/usr/lib/menu/</file>. +System-local menu files should be in <file>/etc/menu/</file>. +User-specific menu files should be in <file>~/.menu/</file> +<sect> Syntax +<p> The format is: +<example> +?package(package[,package2,...]): \ + field1="value1"\ + field2="value2"\ +</example> +<p> +Here is an example to describe the syntax of such a file: +<example> +?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. +</example> +<p> +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. +<p> +Values must be quoted with ", and meta-characters (", backslash, newline) must +be escaped with a backslash. +<p> +You can include several entries in the same file. +<p> +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. + +<p> <tt/?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 "<tt/local./" which are assumed to be always +installed. +<p> The fields <tt/needs/, <tt/section/, <tt/title/ and <tt/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. + +<sect> The <tt/title/ field +<p> + +The <tt/title/ must follow the following requirements: +<enumlist> + <item> It must be short. There is an optional <tt/longtitle/ field for + users that want longer titles. + <item> It must be properly capitalized. Use <em/Emacs/ and not <em/emacs/. + <item> It must be unique. Two entries must not have the same title. +</enumlist> + +<sect> The <tt/needs/ field +<p> + +The following <tt/needs/ are documented for use in the Debian menu. +<enumlist> + <item> <tt/X11/: if this program runs under X11. + <item> <tt/text/: if it runs under a terminal. X11 window managers will + spawn an X terminal emulator. + <item> <tt/vc/: if it runs under a linux virtual console but not under a X + terminal emulator. + <item> <tt/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. +</enumlist> +<p> + +A menu manager can use a special <tt/needs/ value reflecting the menu manager +name for menu entries that must only be displayed in this menu manager. +Examples include <tt/fvwm/ modules, <tt/dwww/ menu entries. +<p> +A program like gnuplot which can be run on X11 as well as on a text +terminal should <em/not/ have an extra entry with <tt/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. +<p> + +On the other hand, if a program (like <prgn/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 <prgn/xterm/ (or +<prgn/rxvt/). However, two entries are not allowed to have the same title. The +title must be unique. +<p> +<sect> The <tt/section/ field +<p> +The <tt/section/ field holds a slash-separated list of hierarchical sections +components. +<p> +The <em/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. +<p> +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 <tt/menu/ package. +<p> +Packages must be placed in leaf sections. +Please do <em/not/ put your packages into any other sections. +<p> +<taglist> + <tag>Applications</tag> + <item> + <p>Normal applications</p> + <p><taglist> + <tag>Accessibility</tag> + <item> + <p>Tools to aid people with disabilities or for machines + lacking usual input devices.</p> + <p>Examples: gok, yasr, dasher.</p> + </item> + <tag>Amateur Radio</tag> + <item> + <p>Anything relating to HAM radio.</p> + <p>Examples: baken, hamsoft, twlog</p> + </item> + <tag>Data Management</tag> + <item> + <p>Interactive database programs, collection managers, + address books, bibliography tools, etc.</p> + <p>gaby, alexandria, mdbtools</p> + </item> + <tag>Editors</tag> + <item> + <p>Editors, other than office word processors, for + text-based information.</p> + <p>Examples: ksubtile, nano, hexedit</p> + </item> + <tag>Education</tag> + <item> + <p>Educational and training softwares.</p> + <p>Examples: gtypist, gcompris, quiz</p> + </item> + <tag>Emulators</tag> + <item> + <p>Software that allows you to run non-native + software or more than one OS at a time.</p> + <p>Examples: wine, dosemu, qemu</p> + </item> + <tag>File Management</tag> + <item> + <p>Tools for file management, archiving, + searching, CD/DVD burning, backup, etc.</p> + <p>Examples: file-roller, mc, baobab</p> + </item> + <tag>Graphics</tag> + <item> + <p>2D and 3D graphics manipulation software.</p> + <p>Examples: gimp, inkscape, imagemagick</p> + </item> + <tag>Mobile Devices</tag> + <item> + <p>Software that allows you to interface with mobile + devices (phones, PDAs, etc.).</p> + <p>Examples: kandy, gnokii, gnome-pilot</p> + </item> + <tag>Network</tag> + <item> + Network related software. This is a three-level + section, do not put entries directly here. + <taglist> + <tag>Communication</tag> + <item> + <p>Mail, USENET news, chat, instant messaging, + IP telephony, video conferencing software, etc.</p> + <p>Examples: xchat, gaim, mutt</p> + </item> + <tag>File Transfer</tag> + <item> + <p>File transfer software such as download + managers, FTP clients, P2P clients, etc.</p> + <p>Examples: amule, gftp, d4x</p> + </item> + <tag>Monitoring</tag> + <item> + <p>Network monitoring software</p> + <p>Examples: gip, ettercap, iptstate</p> + </item> + <tag>Web Browsing</tag> + <item> + <p>Web browsers, tools for offline browsing, etc.</p> + <p>Examples: elinks, epiphany-browser, webhttrack</p> + </item> + <tag>Web News</tag> + <item> + <p>Web feed (RSS, Atom, etc.) and podcast aggregators. + </p> + <p>Examples: akregator, kitty, liferea</p> + </item> + </taglist> + </item> + <tag>Office</tag> + <item> + <p>Office suites, word processors, spreadsheets, + CRM, ERP, financial sofware, etc.</p> + <p>Examples: openoffice.org, tinyerp-client, gnucash</p> + </item> + <tag>Programming</tag> + <item> + <p>IDEs, debuggers, etc.</p> + <p>Examples: anjuta, gdb, eclipse</p> + </item> + <tag>Project Management</tag> + <item> + <p>Timetable managers, group task trackers, + bug tracking software, etc.</p> + <p>Examples: planner, bugzilla, gnotime</p> + </item> + <tag>Science</tag> + <item> + Scientific and engineering-related software. + <taglist> + <tag>Astronomy</tag> + <item> + <p>Astronomy-related software.</p> + <p>Examples: celestia, spacechart, stellarium</p> + </item> + <tag>Biology</tag> + <item> + <p>Biology-related software.</p> + <p>Examples: arb, ncbi-tools-x11, seaview</p> + </item> + <tag>Chemistry</tag> + <item> + <p>Chemistry-related software.</p> + <p>Examples: chemtool, kalzium, xdrawchem</p> + </item> + <tag>Data Analysis</tag> + <item> + <p>Software designed for processing, extracting, + and presenting generic scientific data.</p> + <p>Examples: fityk, ygraph, mn-fit</p> + </item> + <tag>Electronics</tag> + <item> + <p>Circuit design tools, simulators and + assemblers for microprocessors, etc</p> + <p>Examples: geda, gnucap, tkgate</p> + </item> + <tag>Engineering</tag> + <item> + <p>CAD, UML tools, diagram-drawing and + other engineering-related software.</p> + <p>Examples: tcm, dia, qcad</p> + </item> + <tag>Geoscience</tag> + <item> + <p>Geoscience-related software.</p> + <p>Examples: earth3d, qgis, therion</p> + </item> + <tag>Mathematics</tag> + <item> + <p>Mathematics-related software.</p> + <p>Examples: gcalctool, snappea, xeukleides</p> + </item> + <tag>Medicine</tag> + <item> + <p>Medicine-related software.</p> + <p>Examples: mssstest, gnumed-client, xmedcon</p> + </item> + <tag>Physics</tag> + <item> + <p>Physics-related software.</p> + <p>Examples: kxterm, ifrit, paw</p> + </item> + <tag>Social</tag> + <item> + <p>Social sciences-related software.</p> + <p>Examples: gnomesword, hanzim, bibletime</p> + </item> + </taglist> + </item> + <tag>Shells</tag> + <item> + <p>Various shells to be used inside a terminal emulator.</p> + <p>Examples: bash, ksh, zsh</p> + </item> + <tag>Sound</tag> + <item> + <p>Sound players, editors, and rippers/recorders.</p> + <p>Examples: beep-media-player, grip, audacity</p> + </item> + <tag>System</tag> + <item> + System related software. + <taglist> + <tag>Administration</tag> + <item> + <p>Administrative and system configuration utilities, + also tools for personal user settings.</p> + <p>Examples: gnome-control-center, configure-debian, gksu</p> + </item> + <tag>Hardware</tag> + <item> + <p>Tools for manipulating specific hardware, + especially non-standard laptop hardware.</p> + <p>Examples: toshutils, nvclock-gtk, nvtv</p> + </item> + <tag>Language Environment</tag> + <item> + <p>This section is reserved for language-env as a + special case.</p> + </item> + <tag>Monitoring</tag> + <item> + <p>System information and monitoring tools, log viewers, + etc.</p> + <p>Examples: top, hal-device-manager, gtkdiskfree</p> + </item> + <tag>Package Management</tag> + <item> + <p>Package managers and related tools.</p> + <p>Examples: aptitude, deborphan, smartpm</p> + </item> + <tag>Security</tag> + <item> + <p>Security, cryptography and privacy related software, + antiviruses, tools to track and report bugs, etc.</p> + <p>Examples: gpgkeys, bastille, avscan</p> + </item> + </taglist> + </item> + <tag>Terminal Emulators</tag> + <item> + <p>Graphical terminal emulators.</p> + <p>Examples: xterm, gnome-terminal, rxvt</p> + </item> + <tag>Text</tag> + <item> + <p>Text oriented tools like dictionaries, OCR, + translation, text analysis software, etc.</p> + <p>Examples: kdrill, stardict, turkey</p> + </item> + <tag>TV and Radio</tag> + <item> + <p>TV-in, TV-out, FM radio, teletext browsers, etc.</p> + <p>Examples: gradio, gatos, alevt</p> + </item> + <tag>Viewers</tag> + <item> + <p>Software for viewing images, documents + and other (non-video) media.</p> + <p>Examples: gqview, evince, gthumb</p> + </item> + <tag>Video</tag> + <item> + <p>Video players, editors, and rippers/recorders.</p> + <p>Examples: istanbul, totem, kino</p> + </item> + <tag>Web Development</tag> + <item> + <p>Software for web site editing, web + programming, and site administration.</p> + <p>Examples: bluefish, screem, gphpedit</p> + </item> + </taglist> + </p> + </item> + <tag>Games</tag> + <item> + Games and recreations + <taglist> + <tag>Action</tag> + <item> + <p>Games that involve a lot of action + and require fast reflexes.</p> + <p>Examples: xsoldier, supertux, xmoto</p> + </item> + <tag>Adventure</tag> + <item> + <p>Role playing and adventure games, + interactive movies and stories, etc.</p> + <p>Examples: beneath-a-steel-sky, egoboo, kq</p> + </item> + <tag>Blocks</tag> + <item> + <p>Tetris-like games involving falling blocks.</p> + <p>Examples: crack-attack, frozen-bubble, netris</p> + </item> + <tag>Board</tag> + <item> + <p>Games played on a board.</p> + <p>Examples: phalanx, xshogi, xboard</p> + </item> + <tag>Card</tag> + <item> + <p>Games involving a deck of cards.</p> + <p>Examples: pysol, ace-of-penguins, xpat2</p> + </item> + <tag>Puzzles</tag> + <item> + <p>Tests of ingenuity and logic.</p> + <p>Examples: xmpuzzles, sgt-puzzles, enigma</p> + </item> + <tag>Simulation</tag> + <item> + <p>Simulations of the real world + in all detail and complexity.</p> + <p>Examples: flightgear, torcs</p> + </item> + <tag>Strategy</tag> + <item> + <p>Games involving long-term strategic thinking.</p> + <p>Examples: wesnoth, widelands, netpanzer</p> + </item> + <tag>Tools</tag> + <item> + <p>Server browsers, configurators, editors, and other + game-related tools that are not games themselves.</p> + <p>Examples: xqf, crystalspace</p> + </item> + <tag>Toys</tag> + <item> + <p>Amusements, eye-candy, entertaining + demos, screen hacks (screensavers), etc.</p> + <p>Examples: xdesktopwaves, xphoon, xpenguins</p> + </item> + </taglist> + </item> + <tag>Help</tag> + <item> + <p>programs that provide user documentation</p> + <p>Examples: debian-reference, apt-howto, dhelp</p> + </item> + <tag>Screen</tag> + <item> + Programs that affect the whole screen. + <taglist> + <tag>Saving</tag> + <item> + <p>Tools for blanking the screen. Entries of screen hacks and + configuration GUIs should go to other appropriate sections. + </p> + <p>Examples: xscreensaver, xlockmore</p> + </item> + <tag>Locking</tag> + <item> + <p>Tools for locking the screen.</p> + <p>Examples: xscreensaver, xlockmore</p> + </item> + </taglist> + </item> + <tag>Window Managers</tag> + <item> + <p>X window managers.</p> + <p>Examples: fluxbox, metacity, waimea</p> + </item> + <tag>FVWM Modules</tag> + <item> + <p>FVWM-based window manager modules. As only modules related to + the running window-manager are displayed, do not create + subsections for specific window-managers.</p> + <p>Examples: fvwm, fvwm-gnome, fvwm95</p> + </item> + <tag>Window Maker</tag> + <item> + <p>This section is reserved for wmaker as a special case.</p> + <p>All wmaker specific entries must go here.</p> + </item> +</taglist> +<p> +Users wanting to access some menu entries quickly can also put +them in the root menu. This is done by using <em>section="/"</em>. +Package-provided menu entries must never use this feature. +<sect> The <tt/command/ field +<p> +The command field holds the command that should be executed when the +menu entry is selected. Commands will be executed with <prgn/sh -c/ +using +<example> +execl("/bin/sh","sh","-c",command) +</example> +or the equivalent. + +<sect> The <tt/icon/ field +<p> + +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 +<file>/usr/share/pixmaps</file>. +<p> + +Debian package maintainers should ensure that any icons they include +for use in the Debian menus conform to the following points: +<enumlist> + <item>The icons should be in xpm format. + <item>The icons may not be larger than 32x32 pixels, although smaller + sizes are ok. + <item>The background area of the icon should be transparent, if + possible. +</enumlist> +<p> + +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. +<p> + +If you, as a system administrator, don't like the icons in the menus, simply +change the <tt/icon()/ function from the file +<file>/etc/menu-methods/menu.h</file>, and run <prgn/update-menus/. +<p> + +<sect> The <tt/hints/ field +<p> +Hints are used to help menu structure generated menus in a more optimal way. +For example: +<p> +<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 +</example> +The above hints will tell <tt/menu/ to consider grouping <tt/emacs/ +together with other editors that are marked similar. For example, if +<tt/vi/ on your system has a hints="Small,Expert" definition, and +there are too many entries in the <tt>/Applications/Editors</tt> menu entry, +then menu will consider creating a <tt>/Applications/Editors/Expert</tt> +submenu, and put both <tt/vi/ and <tt/emacs/ in it. (Of course, only if you +have <tt/hint_optimize=true/ in your <file>/etc/menu-methods/menu.h</file> +file). + +<sect> Entries for menu sections. +<p> +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 <tt/icon/ and +<tt/sort/. + +The syntax for menu sections entries is the same as for regular entries, +the <tt/section/ field holding the name of the parent section. + +For example +<example> +?package(local.games): needs="text" title="Games" section="/" sort="001" +</example> +will sort <tt/Games/ first. + +<sect>Fvwm's task and title bars +<p> + +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 <prgn/fvwm2/ to have a few buttons, you can +install files for those packages in <tt>/menu/$package</>, containing +a menu entry like this: +<example> + ?Package(xmball):needs=button\ + section=Games/Puzzles\ + icon=path-to-pixmap.xpm\ + title="Xmball"\ + command=/usr/games/xmball +</example> +Then, do the following: +<example> + cd /etc/menu-methods/ + cp fvwm2 fvwm2button + vi fvwm2button +</example> +and remove all the "supported" entries, adding the one below. For the rest, +leave everything the same except those listed below. +<example> + supported + button="+ Style \"" $title "\" TitleIcon" $icon " Exec " $command "\n" + endsupported + startmenu: "AddToTitlebar \n" + endmenu: "\n" + submenutitle:"" + mainmenu: + genmenu: "buttondefs.hook" +</example> +(Of course regular users (not system administrators) can also specify +`buttonfiles' in their ~/.menu/ directory). + +<chapt>What packages with applications should do +<sect> Providing a menu file +<p> +A package should provide a menu file +<file>/usr/share/menu/<package-name></file> that contains +information about each program it likes to make available in the +menus. +<p> +<sect> Adding a hook for dpkg in your packages +<p> +The <tt/postinst/ script and the <file/postrm/ script of the package +should include the line +<example> + if test -x /usr/bin/update-menus; then update-menus; fi +</example> +If you are using <prgn/debhelper/, the program <prgn/dh_installmenu/ +can do it for you. +<p> + +<chapt>What packages with menu managers should do +<p> + +Each package containing a <em/menu manager/ (i.e., a program that can +display a menu) should provide a script or program in +<file>/etc/menu-methods/</> that can read the menu files. This script +will be executed by <prgn/update-menus/, which will feed the menu +entries to be installed to your script via standard input (stdin). +<p> + +The scripts in <file>/etc/menu-methods/</> should be configuration +files, so the user can tune the behaviour of the script, and they must always +include the <file>/etc/menu-methods/menu.h</> configuration file at the beginning +with the command <tt>!include menu.h</> + +For the same reason, scripts in <file>/etc/menu-methods/</> are requested +to use the following configurable functions: + +<tt/title()/ for the title (in place of <tt/$title/), +<tt/icon()/ for the icon (in place of <tt/$icon/), +<tt/term()/ for running <tt/text/ command under <tt/X11/. +<tt/sections_translations()/ for the list of translations of sections name +available. This later one is only defined if you <tt>!include lang.h</tt> +<p> + +Good examples for these scripts for nearly all Debian window managers +are included in the <tt/menu/ package in +<file>/usr/share/doc/menu/examples</file>. 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). +<p> + +This script should not be executable in the package. Instead +the <tt/postinst/ should add the execute bit and then run +<prgn/update-menus/ (if it is executable). +<p> + +Similarly, the <file/postrm/ script when called with option ``remove'' should +remove the execute bit and run <prgn/update-menus/ (if it is executable). +<p> + +Here is an example of such a <file/postrm/ script using <prgn/sh/: +<example> + #!/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 +</example> + +And here is a good example for a <file/postinst/ script: +<example> + #!/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 +</example> +If you are using <prgn/debhelper/, the program <prgn/dh_installmenu/ +can help you do it. +<p> +Please, do not make your package <em/depend/ on the menu package! The +preferred way of telling dpkg that your wm can cooperate with menu is: +<example> + Suggests: menu +</example> +Please only consider using "depends" if you feel providing reasonable +defaults for systems without <prgn>menu</prgn> will make life very difficult +for you. +<p> + +<chapt>How a user can override the menus +<p> + +<sect>Configuring the menus +<p> + +Users can specify their own menu entries in the <file>~/.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 +<example> + ?package(installed-package): +</example> +or +<example> + ?package(local.mystuff): +</example> +if it's something that isn't ``debian-officially'' installed. (Any +``package'' that starts with ``<tt/local./'' is considered installed.) +<p> + +If users want to have their own menu methods, they should create +a <file>~/.menu-methods</> directory and put all their menu methods in it. +(If <file>~/.menu-methods</> exists, +<file>/etc/menu-methods</> will not be searched when a user runs +<prgn/update-menus/). +<p> + +A system administrator should place system-wide menu entries in +<file>/etc/menu</> (not in <file>/usr/share/menu/package</>, since these +files will probably be overwritten by a package upgrade). +<p> + +<sect>Specifying that a menu entry should not be displayed +<p> + +If a user wants to remove the entries of <tt/package/ from the system menu then +this will do the trick: +<example> + echo -n > ~/.menu/package +</example> +The zero-size file will tell <prgn/update-menus/ that the +corresponding package should not have any menu entries listed. + +A system administrator can remove menu entries system-wide with +<example> + echo -n > /etc/menu/package +</example> + +<p> + +<sect> Including other files +<p> + +<var> Historical comment by Joost:</var> +<p> +<var> +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. +</var> +<p> +To include the contents of the file <file>/usr/share/menu/somefile</>, +add this to your menu file: + +<example> +!include /usr/share/menu/somefile +</example> + +Apart from that, it is of course possible to make the menu entry file +executable (<tt>chmod a+x ~/.menu/package</>), and do something like +<example> +#!/bin/sh +cat /usr/share/menu/somefile +sed -e "/unwanted_entry/s/?package(/?package(notinstalled./" \ + /usr/share/menu/someotherfile +</example> +to get the same effect, with the added flexibility of being able to +filter out unwanted lines. + +<chapt>The internals of the menu package +<p> + +<sect>The update-menus program +<p> + +On startup, update-menus checks the file +<file>/var/run/update-menus.pid</> and the pid in it. If there's an +<prgn/update-menus/ process with that pid it kills it. +If <file>/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 <file>/var/lib/dpkg/lock</> file approx. every two second +until the file's gone. +<p> + +Once it's decided to run, whether in the background after dpkg exits, or in +the foreground when used with a trigger-capable dpkg, +<prgn/update-menus/ reads the menu-entry files in +the following directories: <file>/etc/menu</>, <file>/usr/lib/menu</>, +<file>/usr/share/menu</>, <file>/usr/share/menu/default</>. +(if a user runs <prgn/update-menus/, it will add <file>~/.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). +<p> +Once it's read all menu entry files, <prgn/update-menus/ starts all +executable scripts in <file>/etc/menu-methods/</>, hands the scripts the +previously created buffer via stdin. (If <prgn/update-menus/ is run by +a user, it will first try to run the scripts in <file>~/.menu-methods</>, and +only if that directory doesn't exist, it will run the scripts in +<file>/etc/menu-methods</>). +<p> + +Note that as an aid to debugging, one can use +<example> +update-menus --stdout > /tmp/menu-stdin +</example> +and then view the file <file>/tmp/menu-stdin</> to see exactly what +<prgn/update-menus/ handed the menu-methods on their stdin. +<p> + +This may also be useful for people writing <file>/etc/menu-method/*</> scripts: +Running <prgn/update-menus/ every time you changed something in the script may +be quite time-consuming. So, it's much easier to run +<prgn/update-menus --stdout/ once, and then run +<example> + /etc/menu-methods/mymethod < /tmp/menu-stdin +</example> +(and, if that also takes too long, just try editing /tmp/menu-stdin, +and removing 90% or so of all entries) + +<sect>The install-menu program +<p> + +The files <file>/etc/menu-methods/$wm</> are executable config +files that start with the line +<example> + #!/usr/bin/install-menu +</example> +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: +<enumlist> +<item>the compatibility mode ("menu-1" or "menu-2"). +<item>where the various files should be stored/read. +<item>what "needs" are supported, and what wrapper files should + be used for each "type". +<item>how to remove the generated menu files. +</enumlist> +See <file>/usr/share/doc/menu/examples/</> of the menu package for more +comments. +<p> + +Options to <prgn/install-menu/: +<example> + --remove Remove the menu files instead of generating them. + --verbose Output outline of operations that are performed. +</example> +<p> + +Some window managers don't support an `include'-like statement in their +<file/system.*rc/ files (like <prgn/m4/ or <prgn/cpp/ preprocessing); they +cannot read the <file/menudefs.hook/ file generated by install-menu from their +<file/system.*rc/ config file. To still be able to use them, +<prgn/install-menu/ will copy the file <file>$path/$examplercfile</file> to +<file>$path/$rcfile</file> (with <file/$examplercfile/ and <file/$rcfile/ +defined in the <prgn/install-menu/ config file, and <file/$path/ either the +<file/$rootprefix/ or <file>${HOME}/$userprefix</file>, depending on whether +root or user executed the file.), and replace all occurrences of +``install-menu-defs'' with the <file/$genmenu/ file it just +generated. +<p> +As an example, consider the following: +<tt>examplercfile=system.foo-wm-example</tt>, +<tt>rcfile=system.foo-wm</tt>, <tt>genmenu=menudefs.hook</tt> and +<tt>rootprefix=/var/lib/foo-wm/menu</tt>. Now, if <prgn/install-menu/ gets run, it +will first generate the file +<file>/var/lib/foo-wm/menu/menudefs.hook</file>. Next, it will line-by-line +read the file <file>/var/lib/foo-wm/menu/system.foo-wm-example</file> and copy +its contents to <file>/var/lib/foo-wm/menu/system.foo-wm</file>, replacing +every occurrence of the string <tt>install-menu-defs</tt> with the +contents of the file <file>/var/lib/foo-wm/menu/menudefs.hook</file>. +<p> + +To activate the file copying in this way, simply define the <tt/$examplercfile/ +and <tt/$rcfile/ variables in the <prgn/install-menu/ configuration file (for +example, see <file>/etc/menu-methods/fvwm</file>), and make sure there is a +<file>$path/$examplercfile</> (<tt>$path</> being either <tt/$rootprefix/, or +<file/$userprefix/.) +<p> + +If you are writing a menu method, you can use the following to make +debugging it somewhat more easily: +<enumlist> +<item>use <tt>update-menus --stdout > /tmp/menu-stdin </tt> +to create a list of menu entries in <file>/tmp/menu-stdin</file> +and then +<item>you can run just your menu-method with (if it's called wm): +<example> + ./wm -v < /tmp/menu-stdin +</example> +</enumlist> +<p> + +<sect>The install-menu config script definitions +<p> + +The menu-methods in <file>/etc/menu-methods/*</> are basically made up of +a lot of ``tag=string'' definitions, telling <prgn/install-menu/ +how to generate a <file/system.${wm}rc/ script. This way you can tune +the look of generated <file/system.${wm}rc/ to your needs. +<p> + +In the following, something like +<example> + treewalk="c(m)" +</example> +means that the treewalk variable by default has the value "c(m)". +<p> + +For examples of what these scripts can look like, see +<file>/usr/share/doc/menu/examples/*</>. +<p> + +<taglist> +<tag><tt/compat="menu-1"/ +<item> +Two mode are defined: +<taglist> +<tag> <tt/"menu-1"/ <item> menu directives are terminated by an end-of-line +character. </item> +<tag> <tt/"menu-2"/ <item> menu directives are terminated by a semicolon +character. </item> +</taglist> +This must be just after the <tt>!include "menu.h"</tt> directive so that +<file>menu.h</file> can use its own compat mode. + +<tag><tt/outputencoding="UTF-8"/ +<item> Set the encoding used for output files. Use <tt/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. + +<tag><tt/outputlanguage=""/ +<item> +If set to "C" automatic translations will be disabled. Note that you +can still use translate() to perform explicit translation. + +<tag><tt/supported/ +<tag><tt/endsupported/ +<item> +Between the <tt/supported/ and <tt/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: +<example> + function q($s) = "\"" esc($s,"\\\"") "\"" + supported + x11 =" ShowEntry(" q(title()) ", " q($command) ")" + text=" ShowEntry(" q(title()) ", " q(term()) ")" + endsupported +</example> + +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. + +<tag><tt/startmenu=""/ +<tag><tt/endmenu=""/ +<tag><tt/submenutitle=""/ +<item> +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. + +<tag><tt/treewalk="c(m)"/ +<item> +This string defines in what order to dump the <tt/$startmenu/, <tt/$endmenu/, +and <tt/$submenutitle/ (and its children). Each char in the string +refers to: +<example> + 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. +</example> + +The default is "c(m)". For olvwm, one needs: "(M)" + +<tag><tt/genmenu=""/ +<item> +The menu file to generate (usually something like <tt>system."$wm"rc</>). +The file itself may depend on the level or title that is currently +being worked on, like +<example> + genmenu="/subdir/" replacewith($section," ","_") "/rc.menu" +</example> +(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 <tt/endmenu=/ will override the startmenu stuff (but you probably +only need one of the two anyway). + +<tag><tt>rootsection="/Debian"</> +<item> +the prefix every <tt/$section/ variable gets. + +<tag><tt/prerun=""/ +<tag><tt/postrun=""/ +<item> +The commands to run before and after, respectively, the actual generation of the +<file/menudefs.hook/ (genmenu) file. Commands will be executed by <prgn/sh/. +Example: +<example> + prerun="rm -rf " prefix() "/*" + postrun="killall -USR1 fvwm2" +</example> +(Substitution works just like the supported stuff, see below). +<tag><tt/preruntest=""/ +<item> +Just like prerun, but if the return value of the command is non-zero, +menu will quit. +<tag><tt/also_run=""/ +<item> +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 +<tt/prerun/ and all of the hint stuff are ignored. +<p> + +<tag><tt/removemenu=""/ +<item> +The command to run when the menu-method is invoked with the option +<tt/--remove/. This should remove all the autogenerated menu files. +If this option is not present, then install menu will remove +<tt/genmenu/ if it is a constant string and <tt/rcfile/ if it is +defined, and try to remove <tt/prefix()/ if it is empty. + +<tag><tt/onlyrunasroot=false/ +<tag><tt/onlyrunasuser=false/ +<item> +If <tt/onlyrunasroot/ is set to true, <prgn>install-menu</> will quit silently +when run as a user. Similarly for <tt/onlyrunasuser/. + +<var><tt/onlyrunasroot/ is deprecated since it is simpler to just not define +<tt/userprefix/.</var> On the other hand, <tt/onlyrunasuser/ might be needed +if you use <tt/rcfile/ since <tt/rootprefix/ is used as a fallback location +for the template. + +<tag><tt>preoutput="#Automatically generated file. Do not edit (see /usr/share/doc/menu/html)\n\n"</tt> +<tag><tt>postoutput=""</tt> +<item> +Text to put at the beginning resp. end of the generated file ($genmenu). + +<tag><tt/command=""/ +<item> +A command to run instead of <prgn/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. +<p> + +Example: +<example> + command="cat > /tmp/menu-stdin" +</example> + +<tag><tt/hotkeyexclude=""/ +<item> +Keys not to use for hotkey generation. You can use the same +variables and functions here as in for example the startmenu +sections. +<p> + +Example: +<example> + hotkeyexclude="q" $section +</example> + +<tag><tt/hotkeycase="insensitive"/ +<item> +can be either "insensitive" or "sensitive". Determines +whether the hotkeys can be of mixed case (<tt/fvwm2/ reads +the hotkeys case-insensitive, <tt/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". +<p> + +<tag><tt/sort=$sort ":" $title/ +<item> +Entries within one menu will be alphabetically sorted by whatever +sort returns. So, if you do +<tt/sort=ifelse($command, "1", "0"):$title/, then all submenus will +appear above the commands in a submenu. (A submenu always has +<tt/$command=""/). Or, as Joey Hess writes: +<example> + 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.) +</example> + +<tag><tt/rcfile=""/ +<item> +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 <tt>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 <tt>system."$wm"rc-menu</> file. This will then get replaced +by the <tt/$genmenu/ file that was just created (see +also <tt/$examplercfile/). +<p> + +<tag><tt/examplercfile=""/ +<item> +if needed (see <tt/rcfile/), this is the <tt/system.rc"$wm"-menu/ +file. In that case, make <tt/rcfile=system.rc"$wm"/. +<p> + +<tag><tt/rootprefix=""/ +<item> +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. + +<p> +<tag><tt/userprefix=""/ +<item> +As <tt/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. +<p> + +<tag><tt/hint_optimize=false/ +<item> +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). + +<tag><tt/hint_nentry=6/ +<item> +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. + +<tag><tt/hint_topnentry=5/ +<item> +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. + +<tag><tt/hint_mixedpenalty=15.0/ +<item> +Penalty for `mixed' menus. Mixed menus are those with both submenus +and direct commands in them. + +<tag><tt/hint_minhintfreq=0.1/ +<item> +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). + +<tag><tt/hint_mlpenalty=2000/ +<item> +`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. +<tag><tt/hint_max_ntry=4/ +<item> +menu will recursively, for each node, try the hint_max_ntry best local +menu-divisions. + +<tag><tt/hints_max_iter_hint=5/ +<item> +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. + +<tag><tt/hint_debug=false/ +<item> +Set to true if you want to see loads and loads of debug output. +</taglist> + +<sect> Hints, tree optimization +<p> +The hints actually work in a rather strange way: when +<tt/hint_optimize=true/ then all <tt/$section/ elements are added to +the specified <tt/$hints/ variable, and the order +(<tt>/Applications/Editors</tt> or <tt>/Editors/Applications</tt>) 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: +<p> + +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 +<example> + Good + Hell + Microsoft +</example> +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 +<example> + Good + Hell + Heaven +</example> +as now it isn't clear whether to visit the Good or the Heaven submenu. +<p> +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. + +<chapt>Variables and functions in the install-menu scripts +<p> + +The supported "needs" definitions and "startmenu=", "endmenu=" +and "submenutitle=" are interpreted as follows: + +<sect> String constants +<p> + 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). + +<sect> Variables +<p> + Anything matching $[a-z,A-Z,_]* is interpreted as a variable, and + the corresponding definition from the menu entry is substituted. +</p> +<sect1> Special variables +<p> + 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). +<taglist> +<tag> needs: +<item> + Used to determine whether the window manager supports this + menu entry. +<tag> command: +<item> + If this is undefined, this menu entry is taken as defining + a sub-menu. This way you can specify icons of sub-menus. +<tag> title!: +<item> + 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. +<tag> sort: +<item> + 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 "|" +<tag> section!: +<item> + 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. +<tag> basesection!: +<item> + 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. +<tag> hotkey!: +<item> + 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. +</taglist> +<sect1> + Preferred variables +<p> + 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. +<taglist> +<tag> icon: <item> + 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. +<tag> icon32x32: <item> + The location of a 32x32 icon file for this menu entry. +<tag> icon16x16: <item> + The location of a 16x16 icon file for this menu entry. + This allows users to choose between 16x16 and 32x32 icon. +<tag> longtitle: <item> + 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. +<tag> description: <item> + An even longer description (about 5 lines). + For example, a description of the documentation in + the dwww generated html pages. +</taglist> +<sect1> + Suggested variables +<p> + 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: +<taglist> +<tag> visible <item> + 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). +<tag> geometry <item> + 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. +</taglist> +<sect> Functions +<p> + Anything matching <tt/[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. +<taglist> +<tag> prefix() <item> + returns the current prefix dir: either $rootprefix, or + $HOME/$userprefix, depending on who runs install-menu + +<tag> ifroot($rootarg, $userarg) <item> + if(getuid()==0) print $rootarg, else print $userarg + +<tag> print($arg) <item> + Same as just $arg; if $arg is empty, generate an error. + +<tag> nstring($n, $string) <item> + write $string $n times. So, nstring(3,"Aa") writes "AaAaAa". + (Useful in combination with level()). + +<tag> esc($arg1,$arg2) <item> + Print $arg1, but escape all occurrences of characters in $arg2 + with a '\' (thus, if arg1="hello", arg2="lo", print "he\l\l\o"). + +<tag> escwith($arg1, $arg2, $arg3) <item> + Same as esc, but use $arg3 as escape sequence. + +<tag> escfirst($arg1, $arg2, $arg3) <item> + Same as escwith, but only escapes first occurrence of $arg2. + +<tag> cppesc($arg1) <item> + 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. + +<tag> tolower($arg) +<tag> toupper($arg) <item> + Returns the argument set in lowercases resp uppercases. + +<tag> replacewith($s, $replace, $with) <item> + 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" + +<tag> replace($s, $replace, $with) <item> + 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. + +<tag> ifempty($arg1, $arg2) <item> + If $arg1 is empty, print $arg2, otherwise print nothing. + For compatibility, $arg1="none" is interpreted as empty. + +<tag> ifnempty($arg1, $arg2) <item> + If $arg1 is not empty, print $arg2. + For compatibility, the string "none" is seen as empty. + +<tag> ifelse($arg1,$arg2,$arg3) <item> + If $arg1 is non-empty, print $arg2, otherwise $arg3. + For compatibility, the string "none" is seen as empty. + +<tag> ifeq($arg1, $arg2, $arg3) <item> + If ($arg1==$arg2) then print $arg3 +<tag> ifneq($arg1, $arg2, $arg3) <item> + If ($arg1!=$arg2) then print $arg3 +<tag> ifeqelse($arg1, $arg2, $arg3, $arg4) <item> + If ($arg1==$arg2) then print $arg3 else print $arg4 + +<tag> cond_surr($arg1, $arg2, $arg3) <item> + If $arg1 is non-empty print $arg2$arg1$arg3, otherwise print nothing. + For compatibility, $arg1="none" is interpreted as empty. + +<tag> iffile($arg1, $arg2) <item> + If file $arg1 exists, and can be opened for reading by whoever + started the current process, return $arg2, otherwise return nothing. + + +<tag> ifelsefile($arg1, $arg2, $arg3) <item> + If file $arg1 exists, and can be opened for reading by whoever + started the current process, return $arg2, otherwise return $arg3. + +<tag> catfile($arg1) <item> + Return the contents of file $arg1. + +<tag> shell($arg1) <item> + Return the output of the shell command $arg1. + +<tag> forall($array, "var", $exec) <item> + For each element of the column separated array $array, set + $var to that element, and print $exec. + Example: + <example> + !include lang.h + forall(sections_translations(), "lang", \ + " section[" $lang "]=" translate($lang, title()) "\n") + </example> + +<tag> parent($arg) <item> + for $arg a "directory", return parent directory: + parent("/Debian/Applications/Editors") = "/Debian/Applications". + +<tag> basename($arg) <item> + return the last part of the parent directory: + basename("/Debian/Applications/Editors") = "Applications". + +<tag> stripdir($arg) <item> + everything after the last slash, i.e. what basename() + should have returned: stripdir("/Debian/Applications/Editors") = "Editors". + +<tag> entrycount() <item> + the number of entries in this menu. + +<tag> entryindex() <item> + 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. + +<tag> firstentry($arg) <item> + return $arg if this is the first entry of this menu + (that is, entryindex() = 0). Else, return nothing. + +<tag> lastentry() <item> + return $arg if this is the last entry in this menu + (that is, entryindex() = entrycount() -1). Else, return nothing. + +<tag> level() <item> + return nesting of this menu in the total menu tree. + +<tag> add($arg1,$arg2) +<tag> sub($arg1,$arg2) +<tag> mult($arg1,$arg2) +<tag> div($arg1,$arg2) <item> + 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()) + +<tag> rcfile() +<tag> examplercfile() +<tag> mainmenutitle() +<tag> rootsection() +<tag> rootprefix() +<tag> userprefix() +<tag> treewalk() +<tag> postoutput() +<tag> preoutput() +<item> + These functions all output whatever they were defined to be in + the menu-method file. + +<tag> translate($lang, $text) <item> + Translate $text into $lang using gettext, see <tt/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. + +<tag> implicit concatenation <item> +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" +</taglist> + +</book> + diff --git a/doc/menu.txt.gz b/doc/menu.txt.gz Binary files differnew file mode 100644 index 0000000..14e21bd --- /dev/null +++ b/doc/menu.txt.gz diff --git a/doc/menufile.5 b/doc/menufile.5 new file mode 100644 index 0000000..1b2d7b3 --- /dev/null +++ b/doc/menufile.5 @@ -0,0 +1,214 @@ +.\" -*- nroff -*- +.TH MENUFILE 5 "File Formats" "DEBIAN" +.SH NAME +menufile \- entry in the Debian menu system +.SH SYNOPSIS +.B ~/.menu/* +.PP +.B /etc/menu/* +.PP +.B /usr/lib/menu/* +.PP +.B /usr/share/menu/* +.PP +.B /usr/share/menu/default/* +.SH DESCRIPTION +Menu files add entries to the Debian menu system. The system administrator can +place menu files in /etc/menu/ to override menu files that packages add to +/usr/share/menu/ . The user can place menu files in ~/.menu/ to override all +other menu files. +.PP +Please read the Debian menu manual available in /usr/share/doc/menu/html +for the complete specification of menu files. +.PP +The menu files are usually named after the Debian package that +contains the programs listed in them. In it, you can list several +"menu entries" that specify a specific item in the menu +structure. Each menu entry specifies which packages it depends on; if +that package are not installed, the menu entry will be ignored by +\fBupdate-menus(1)\fP. +(In a menu entry you can specify pseudo-packages that start +with "local."; update-menus will always use those menu entries). +If you wish to remove an item from the menu entirely, make an empty menu +file with the same name as the file you want to override. +.SH Examples +Dosemu could install the following menu file as /usr/share/menu/dosemu: +.PP + ?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu" + ?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu" command="xdos" +.PP +The system administrator wants to override this file to change how dosemu is +run, so /etc/menu/dosemu is created: +.PP + ?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu -A" + ?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu" command="xdos -A" +.PP +A user does not want Dosemu to appear in the menus at all, so the user creates +an empty file named \fI~/.menu/dosemu\fP. +.SH FORMAT +A menu file consists of 0 or more lines of the following format: +.RS +.PP +\fB?package(package-name):var1=value1 var2=value2 \fR ... +.TP +needs +Specify what kind of environment the program require. This variable must be +defined, and should be one of the following: +.RS +.TP +needs="text" +Program requires a terminal +.TP +needs="x11" +Program requires a X server +.TP +needs="vc" +Program requires a Linux console (i.e.: svgalib programs) +.TP +needs="wm" +The program is a window manager. +.TP +needs="fvwmmodule" +The program is a fvwm compatible module. +.RE +.TP +section +The section in which the menu entry should appear. See \fBMENU LAYOUT\fP for +preferred section names. +.RS +.RE +.TP +icon +An icon for this menu entry. If no icon is available, just don't +define this. +.TP +title +The title of the program that will appear on the menus. Keep it short. +If two menu entries share the same title and section, the one that +best fits the available display will be used. So in the example above +with two menu entries that both have the menu id "title", if X is +available, the X11 one will be used; otherwise the text one will be used. +Must be defined. +.TP +command +The command to be executed when this menu entry is selected. +.TP +hints +A comma-separated list of hints on how grouping menu entries; see the manual. +.RE +.SH "MENU LAYOUT" +The \fBauthoritative\fP list of Debian's menu structure is maintained in the +Debian Menu sub-policy document which is part of the Debian Policy package. The +menu structure below is included only for convenience. Please do not put your +packages into any other sections. + +Use `/' to separate sub-menu names, for example, "Applications/Editors" or +"Games/Arcade". +.PP + \fIApplications\fP + \fIAccessibility\fP + \fIAmateur Radio\fP + \fIData Management\fP + \fIEditors\fP + \fIEducation\fP + \fIEmulators\fP + \fIFile Management\fP + \fIGraphics\fP + \fIMobile Devices\fP + \fINetwork\fP + \fICommunication\fP + \fIFile Transfer\fP + \fIMonitoring\fP + \fIWeb Browsing\fP + \fIWeb News\fP + \fIOffice\fP + \fIProgramming\fP + \fIProject Management\fP + \fIScience\fP + \fIAstronomy\fP + \fIBiology\fP + \fIChemistry\fP + \fIData Analysis\fP + \fIElectronics\fP + \fIEngineering\fP + \fIGeoscience\fP + \fIMathematics\fP + \fIMedicine\fP + \fIPhysics\fP + \fISocial\fP + \fIShells\fP + \fISound\fP + \fISystem\fP + \fIAdministration\fP + \fIHardware\fP + \fILanguage Environment\fP + \fIMonitoring\fP + \fIPackage Management\fP + \fISecurity\fP + \fITerminal Emulators\fP + \fIText\fP + \fITV and Radio\fP + \fIViewers\fP + \fIVideo\fP + \fIWeb Development\fP + \fIGames\fP + \fIAction\fP + \fIAdventure\fP + \fIBlocks\fP + \fIBoard\fP + \fICard\fP + \fIPuzzles\fP + \fISimulation\fP + \fIStrategy\fP + \fITools\fP + \fIToys\fP + \fIHelp\fP + \fIScreen\fP + \fISaving\fP + \fILocking\fP + \fIWindow Managers\fP + \fIFVWM Modules\fP + \fIWindow Maker\fP + +.SH NOTES +If you want to specify an icon or hotkey for a sub-menu (for example, +the Editors sub-menu), just use the same syntax but leave the command +empty: + +?package(mypackage):needs="X11" section="Applications" icon="icon.xpm" hotkey="E" title="Editors" + +.PP +Whenever any menu files are changed, you must run +.BR update-menus (1) +.SH FILES +(Earlier listed files override later files with the same names.) +.PP +.I ~/.menu/* +.RS +Menu files added by the user. +.RE +.I /etc/menu/* +.RS +Menu files added by the system administrator. +.RE +.I /usr/lib/menu/* +.RS +Architecture-dependant menu files provided by other Debian packages. +.RE +.I /usr/share/menu/* +.RS +Architecture-independant menu files provided by other Debian packages. +.RE +.I /usr/share/menu/default/* +.RS +Menu files provided by the menu package. +.RE +.SH AUTHORS +Joost Witteveen <joostje@debian.org>, based on work by +Lars Wirzenius <liw@iki.fi>. Now maintained by +Bill Allombert <ballombe@debian.org>. +.PP +(Man page by Joey Hess, <joeyh@debian.org>) +.SH "SEE ALSO" +.BR update-menus (1), +.BR /usr/share/doc/menu/html/index.html diff --git a/doc/menufile.fr.5 b/doc/menufile.fr.5 new file mode 100644 index 0000000..19a5083 --- /dev/null +++ b/doc/menufile.fr.5 @@ -0,0 +1,231 @@ +.\" -*- nroff -*- +.TH "FICHIER DE MENUS" 5 "Formats de fichier" DEBIAN +.SH NOM +menufile \- entrée dans le système des menus Debian +.SH SYNOPSIS +.B ~/.menu/* +.PP +.B /etc/menu/* +.PP +.B /usr/lib/menu/* +.PP +.B /usr/share/menu/* +.PP +.B /usr/share/menu/default/* +.SH DESCRIPTION +Les fichiers de menus ajoutent des entrées dans le système des menus +Debian. L'administrateur système peut placer des fichiers de menus dans +/etc/menu/ qui auront priorité sur les fichiers de menus que les paquets +ajoutent à /usr/share/menu/. Un utilisateur peut placer des fichiers de menus +dans ~/.menu/ qui auront priorité sur tous les autres fichiers de menus. +.PP +Veuillez consulter le manuel des menus Debian présent dans +/usr/share/doc/menu/html pour les spécifications complètes des fichiers de +menus. +.PP +Les fichiers de menus portent d'habitude le nom du paquet Debian qui +contient les programmes qu'ils listent. Ils peuvent contenir plusieurs «\ +entrées de menus\ », qui spécifient un élément particulier de la structure +d'un menu. Chaque entrée de menu spécifie les paquets dont elle dépend, ce qui +permet à \fBupdate-menus(1)\fP d'ignorer le menu si ces paquets ne sont pas +installés. (Dans une entrée de menu vous pouvez spécifier des pseudo\-paquets +qui commencent par «\ local.\ », ce qui indique à update\-menus de toujours +utiliser ces menus). Si vous voulez supprimer entièrement tous les éléments +d'un fichier de menus, vous pouvez créer un fichier vide portant le même nom +que ce fichier de menus. +.SH Exemples +Dosemu peut installer le fichier de menus suivant dans +/usr/share/menu/dosemu\ : +.PP + ?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu" + ?package(dosemu):needs="x11" section="Applications/Emulators" title="Dosemu" command="xdos" +.PP +L'administrateur système peut vouloir remplacer ce fichier pour changer la +façon dont dosemu est exécuté, il crée alors le fichier /etc/menu/dosemu +suivant\ : +.PP + ?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu \-A" + ?package(dosemu):needs="x11" section="Applications/Emulators" title="Dosemu" command="xdos \-A" +.PP +Il se peut également qu'un utilisateur ne veuille pas voir apparaître Dosemu +dans ses menus. Il peut alors créer un fichier vide nommé ~/.menu/dosemu. +.SH FORMAT +Un fichier de menus consiste en 0 ou plusieurs lignes dans le format +suivant\ : +.RS +.PP +\fB?package(nom_paquet):var1=value1 var2=value2 \fP ... +.TP +needs +Indique le type d'environnement que le programme nécessite. Cette variable +est obligatoire et peut valoir\ : +.RS +.TP +needs="text" +Le programme nécessite un terminal +.TP +needs="x11" +Le programme nécessite un serveur X +.TP +needs="vc" +Le programme nécessite une console Linux (c'est à dire un programme +utilisant svgalib). +.TP +needs="wm" +Le programme est un gestionnaire de fenêtres. +.TP +needs="fvwmmodule" +Le programme est un module compatible avec fvwm. +.RE +.TP +section +La section dans laquelle l'entrée de menu doit être affichée. Reportez\-vous +à la section \fBDISPOSITION DES MENUS\fP pour les noms de section. +.RS +.RE +.TP +icon +Une icône pour cette entrée de menu. Si aucune icône n'est disponible, +il suffit de ne pas définir ce champ. (icon="none" est également possible, +mais il est préférable de ne pas placer cette ligne). +.TP +title +Le titre du programme qui apparaîtra dans le menu. Essayez de garder ce +champ court. Si deux entrées de menu partagent le même titre et la même +section, celle qui est la mieux adaptée au type d'affichage est +conservée. De cette façon, dans l'exemple précédent qui a deux menus qui ont +le même titre, si X est disponible, l'entrée dépendant de X11 est utilisée, +sinon celle pour un affichage texte est utilisée. Ce champ est obligatoire. +.TP +command +La commande à exécuter lorsque cette entrée est sélectionnée. +.TP +hints +Une liste d'indications séparées par des virgules, permettant de grouper les +menus. Veuillez consulter le manuel. +.RE +.SH "DISPOSITION DES MENUS" +La liste \fBofficielle\fP de la structure des menus Debian est maintenue dans +la sous\-charte des menus Debian («\ Debian Menu sub\-policy\ »), qui fait +partie du paquet Debian Policy. La structure de menus ci\-dessous est incluse +(et traduite) pour des raisons de commodité. Veuillez ne pas placer vos paquets +dans d'autres sections. + +NDT\ : les noms de sections officiels sont automatiquement traduits au +moment de la génération des menus. + +Utilisez `/' pour séparer les noms des sous\-menus. Par exemple\ : +"Applications/Editors" ou "Games/Action". +.PP + \fIApplications\fP + \fIAccessibility\fP + \fIAmateur Radio\fP + \fIData Management\fP + \fIEditors\fP + \fIEducation\fP + \fIEmulators\fP + \fIFile Management\fP + \fIGraphics\fP + \fIMobile Devices\fP + \fINetwork\fP + \fICommunication\fP + \fIFile Transfer\fP + \fIMonitoring\fP + \fIWeb Browsing\fP + \fIWeb News\fP + \fIOffice\fP + \fIProgramming\fP + \fIProject Management\fP + \fIScience\fP + \fIAstronomy\fP + \fIBiology\fP + \fIChemistry\fP + \fIData Analysis\fP + \fIElectronics\fP + \fIEngineering\fP + \fIGeoscience\fP + \fIMathematics\fP + \fIMedicine\fP + \fIPhysics\fP + \fISocial\fP + \fIShells\fP + \fISound\fP + \fISystem\fP + \fIAdministration\fP + \fIHardware\fP + \fILanguage Environment\fP + \fIMonitoring\fP + \fIPackage Management\fP + \fISecurity\fP + \fITerminal Emulators\fP + \fIText\fP + \fITV and Radio\fP + \fIViewers\fP + \fIVideo\fP + \fIWeb Development\fP + \fIGames\fP + \fIAction\fP + \fIAdventure\fP + \fIBlocks\fP + \fIBoard\fP + \fICard\fP + \fIPuzzles\fP + \fISimulation\fP + \fIStrategy\fP + \fITools\fP + \fIToys\fP + \fIHelp\fP + \fIScreen\fP + \fISaving\fP + \fILocking\fP + \fIWindow Managers\fP + \fIFVWM Modules\fP + \fIWindow Maker\fP + +.SH NOTES +Si vous voulez spécifier une icône ou un raccourci clavier pour un sous\-menu +(par exemple, le sous\-menu Editors), utilisez la même syntaxe, mais laissez +le champ command vide, comme ceci\ : + +?package(monpaquet):needs="X11" section="Applications" icon="icon.xpm" hotkey="E" title="Editors" + +.PP +À chaque fois qu'un fichier de menus est modifié, vous devez exécuter +.BR update\-menus (1). +.SH FICHIERS +(Fichiers par ordre de priorité décroissante) +.PP +.I ~/.menu/* +.RS +Fichiers de menus ajoutés par l'utilisateur. +.RE +.I /etc/menu/* +.RS +Fichiers de menus ajoutés par l'administrateur système. +.RE +.I /usr/lib/menu/* +.RS +Fichiers de menus dépendants de l'architecture fournis par d'autres paquets +Debian. +.RE +.I /usr/share/menu/* +.RS +Fichiers de menus indépendants de l'architecture fournis par d'autres +paquets Debian. +.RE +.I /usr/share/menu/default/* +.RS +Fichiers de menus fournis par le paquet menu. +.RE +.SH AUTEURS +Joost Witteveen <joostje@debian.org>, basé sur les travaux de Lars +Wirzenius <liw@iki.fi>. Il est désormais maintenu par Bill Allombert +<ballombe@debian.org>. +.PP +Page de manuel par Joey Hess, <joeyh@debian.org> +.PP +Ce document est basé sur une traduction réalisée par Nicolas François le +3 septembre 2005. +.SH "VOIR AUSSI" +.BR update\-menus(1), +.BR /usr/share/doc/menu/html/index.html diff --git a/doc/su-to-root.1 b/doc/su-to-root.1 new file mode 100644 index 0000000..6560c6f --- /dev/null +++ b/doc/su-to-root.1 @@ -0,0 +1,56 @@ +.\" Process this file with +.\" groff -man -Tascii foo.1 +.\" +.TH su\-to\-root 1 "20 October 1998" "Debian Project" "Debian GNU/Linux manual" +.SH NAME +su\-to\-root \- A simple script to give an `interactive' front-end to su. +It can be used in menu entry commands to ask for the root password +.SH SYNOPSIS +.B su\-to\-root [\-X] [\-p <user>] \-c <command> +.SH DESCRIPTION +Most menu entries simply start an editor or a game or whatever. But +some menu entries would like to give the user the ability to change +important settings in the system, that require root privileges. +\fBsu\-to\-root\fP can be used to ask for the root password. +.SH OPTIONS +.IP "\-c <command>" +The command to execute as a string. This option is mandatory. +.IP "\-p <user>" +The name of the user to change to, instead of root. +.IP "\-X" +The command is a X11 program that does not require a terminal. +This is to be used with menu entries that declare needs="X11". +.SH ENVIRONMENT +.IP SU_TO_ROOT_X +Select the su-like program called by \fIsu\-to\-root \-X\fP. +Supported values are \fIgksu\fP, \fIkdesu\fP, \fIkde4su\fP, \fIktsuss\fP, + \fIsux\fP, \fIgksudo\fP and \fIkdesudo\fP. +\fIkde4su\fP denotes the KDE4 version of \fBkdesu\fP. +.IP +When this variable is not set \fBsu\-to\-root\fP will currently try to use +\fIgksu\fP, \fIkdesu\fP, \fIkde4su\fP, \fIktsuss\fP, \fIsux\fP and the built-in +code, in that order with the exception that under a KDE session, \fIkdesu\fP +and \fIkde4su\fP are prefered over \fIgksu\fP. +.IP +The exact set of programs to try and their order is subject to change without +notice. +.IP SU_TO_ROOT_SU +Select the su-like program used in text mode. +Supported values are \fIsudo\fP, \fIsux\fP and \fIsu\fP, the later being +the default. +.SH FILES +.IP /etc/su\-to\-rootrc +.IP ~/.su\-to\-rootrc +\fBsu\-to\-root\fP will source these files at startup in this order. This lets +you define and modify the environment variables above without restarting your X +session. +.SH COPYING +\fBsu\-to\-root\fP is distributed under the GNU General Public License. +(GPL 2.0 or greater). +.SH AUTHORS +Joost Witteveen <joostje@debian.org> +.P +X11 support by Morten Brix Pedersen and Bill Allombert +.RI <ballombe@debian.org> +.SH "SEE ALSO" +\fBupdate\-menus\fP(1), \fBmenufile\fP(5), \fB/usr/share/doc/menu/html\fP diff --git a/doc/su-to-root.fr.1 b/doc/su-to-root.fr.1 new file mode 100644 index 0000000..3aca782 --- /dev/null +++ b/doc/su-to-root.fr.1 @@ -0,0 +1,61 @@ +.\" Process this file with +.\" groff -man -Tascii foo.1 +.TH su\-to\-root 1 "20 octobre 1998" "Projet Debian" "Manuel Debian GNU/Linux" +.SH NOM +su\-to\-root \- un simple script qui est une interface interactive à su. Il +peut être utilisé dans les commandes des entrées de menu pour demander le +mot de passe du super-utilisateur. +.SH SYNOPSIS +\fBsu\-to\-root [\-X] [\-p <utilisateur>] \-c <commande>\fP +.SH DESCRIPTION +La plupart des entrées de menu démarrent un éditeur, un jeu, ou n'importe +quoi d'autre. Mais certaines entrées de menu veulent fournir à l'utilisateur +la possibilité de changer des réglages importants du système, ce qui +nécessite des droits d'administration. +\fBsu\-to\-root\fP peut être utilisé pour demander le mot de passe du +super-utilisateur. +.SH OPTIONS +.IP "\-c <command>" +La commande à exécuter sous forme de chaîne de caractères. Cette option est +obligatoire. +.IP "\-p <utilisateur>" +Le compte utilisateur cible, en lieu et place de root. +.IP \-X +La commande est un programme X11 qui ne nécessite pas de terminal. Elle doit +être utilisée avec les entrées de menu qui déclarent le champs needs="X11". +.SH ENVIRONNEMENT +.IP SU_TO_ROOT_X +Indique le programme permettant de devenir super-utilisateur qui sera appelé +par \fBsu\-to\-root \-X\fP. Les valeurs acceptées sont \fIgksu\fP, \fIkdesu\fP, +\fIkde4su\fP, \fIktsuss\fP, \fIsux\fP, \fIgksudo\fP et \fIkdesudo\fP. \fIkde4su\fP +indique la version KDE4 de \fBkdesu\fP. +.IP +Quand cette variable n'est pas définie, \fBsu-to-root\fP essaie actuellement +d'utiliser \fIgksu\fP, \fIkdesu\fP, \fIkde4su\fP, \fIktsuss\fP, \fIsux\fP et le +code intégré dans cet ordre avec l'exception que, dans une session KDE, +\fIkdesu\fP et \fIkde4su\fP seront préférés à \fIgksu\fP. +.IP +La liste de programmes à essayer et son ordre est sujet à changement sans avertissement. +.IP SU_TO_ROOT_SU +Indique le programme permettant de devenir super-utilisateur qui sera appelé +en mode texte. Les valeurs acceptées sont \fIsux\fP, \fIsudo\fP +et \fIsu\fP, ce dernier étant la valeur par défaut. +.SH FICHIERS +.IP /etc/su\-to\-rootrc +.IP ~/.su\-to\-rootrc +\fBsu\-to\-root\fP sourcera ce fichier au lancement. Ceci +permet de définir et modifier les variables d'environnement décrite +précédemment sans avoir à redémarrer votre session X. +.SH DISTRIBUTION +\fBsu\-to\-root\fP est distribué sous la licence publique générale («\ GPL\ ») +du projet GNU (GPL version 2.0 ou supérieure). +.SH AUTEURS +Joost Witteveen <joostje@debian.org> +.P +Gestion de X11 par Morten Brix Pedersen et Bill Allombert <ballombe@debian.org>. +.P +Cette page de manuel est basée sur une première traduction réalisée par Nicolas +François le 3 septembre 2005. +.SH "VOIR AUSSI" +\fBupdate\-menus\fP(1), \fBmenufile\fP(5), \fB/usr/share/doc/menu/html\fP + diff --git a/doc/translate b/doc/translate new file mode 100644 index 0000000..6eb32ee --- /dev/null +++ b/doc/translate @@ -0,0 +1,129 @@ +Saluton, Hello, Jó napot! + +The debian menus currently currently only exist in +english, "en da's niet goed" (that's not good, Nem jó, Tio malbonas). + +Below I describe how I propose to change this. +At the end of this message I briefly discuss the gnome/kde +approach, and why I really like to make menu compatible +with their format, but not use their translations. + +############# + +What I propose is that update-menus simply learns the dutch, +german, whatever translations for "Apps", "Editors", +"The Gimp", "X Window Snapshot", and so on. +These translations would be provided in a form similar/identical to +the already used i18n format. + +The French translations would be provided by a menu-fr.deb package, +the Dutch translations by menu-du.deb, etc. + +This may seem strange at first, as now the gimp package has no +control over how the menu-entry looks in german. It might at first +sight be much better to put in the menu entry file for the gimp +all translations of "The Gimp" in however many languages we +want to support. + +The downside of this, is that it simply doesn't work in Debian. +The maintainer of the gimp surely doens't know the translations +of "The Gimp" in Dutch, Turkish, Japanise, Esperanto, whatever. +Somewhere in Turkey there may be somone who is really good at +translating all english titles into turkish, but s/he will have +a very hard time convincing all 500+ package maintainers to +include his/her translation into the package. And, a week later +someone in Bulgaria wakes up, and sends 500+ discriptions to +500+ maintainers, asking them to include that. Well, you see, +with about 6000 languages on this earth, the maintainers are +going to have a hard time. + +That is why I propose that the package maintainers simply +don't do anything about the languages, but simply upload their +packages with menu entry files in them. Then some deamon on +master scans all menu entry files in the distribution, and +creates a file with all english words/phrases that should be +translated. This file can be put somewhere on the web, and +then this the translators simply gets that file, translate +the 500+ entries in it, and create a menu-tr.deb (menu-de.deb, etc) +package, and uploads that. Then, the users that want turkish systems +simply install menu-tr.deb package, set the appropriate LC_* +variables, and update-menus does what it should do. + +This approach has the advantages that + - It actually works. Forceing 500+ package maintainers to include + the world's 6000+ languages into their menu entry files is + really never going to work. + - It makes things easy for both the maintainer of the packages + with the menu entry files (they do nothing), and for the + translators (they don't need to get the to-be-translated words + and phrases from all kinds of packages, and send the results to many + different package maintainers). + - It allows users to select what languages to install, so they + don't have to buy extra harddisks because each menu entry file + now is 0.5 M big (5000 languages, 100 chars per language). + +Note that the file with the `to-be-translated' phrases in them +should not just have entries like + Apps + The Gimp + X Window Snapshot +as that will not allow the translators to really see what "Apps" or +"The Gimp" is. Rather, for each to be translated item, there should +be info on what package it came from (to allow the translator to +investigate further), and if present the "description" from the +menu entry file the string came from. Maybe more. But we can +discuss that later. +Also note that there probably aught to be different files for +main and non-free. And thus also menu-nonfree-fr.deb +with the translations for the non-free section. I assume the +translations should be put somewhere into +/usr/share/local/fr/LC_MESSAGES/menu-translate.mo (or menu-translate-non-free) + + +Summary: + - package maintainers do nothing (apart from maintaining:) + - translators get those `to-be-translated' files, translate + the words/phrases in them upload the menu-??.deb pacakges. + - The users install the menu-??.deb packages for whatever language + they like or don't like. + - If there are no big objections (only minor points) I'd like + to start working on menu very soon. (should be a working version + within 2 weeks after I started). + +Postnote: + Why would we do this only for menu? There may well be other packages + that would like to have the same `debian-wide' translation support. + Maybe we shouldn't call the packages "menu-fr.deb", but "translate-fr.deb", + or whatever. + + +############## +Gnome/KDE menu's + +When the translating of menus comes up, gnome/kde automatically also +come up as they already have translations. So, why not use those? +Well, for the above mentioned reasons: "cross-package" communication +is pour to say the least in debian, and there is no way we are +going to support many languages if every change has to go through +the maintainers. And it's very tough on the translators, as they +have to communicate with many different maintainers. + +So, I say that using the translation support from gnome/kde's menu +entry files is not the right way in Debian. + +However, that doesn't mean we shouldn't move to gnome/kde-format +menu entry files. They are basically already very close to what +we have now, and I'm very tempted to simply add support for them to +update-menus so that update-menus can read both formats. What +way we go after that debian-policy has to decide. + + +############## + +Any opinions? + +If there is noone saying this is a realy bad approach, I'd like +to start working on this really soon now. + +Thanks, +joostje diff --git a/doc/update-menus.1 b/doc/update-menus.1 new file mode 100644 index 0000000..48586e3 --- /dev/null +++ b/doc/update-menus.1 @@ -0,0 +1,177 @@ +.\" -*- nroff -*- +.TH UPDATE-MENUS 1 "Debian Utilities" "DEBIAN" +.SH NAME +update-menus \- generate Debian menu system +.SH SYNOPSIS +.B update-menus [\-v] [\-d] [\-h|--help] [--version] [--menufilesdir <dir>] [--menumethod <method>] [--nodefaultdirs] [--stdout] +.SH DESCRIPTION +Before the advent of \fIupdate-menus\fP, when the system administrators installed a +package onto a Debian system, they would need to edit various window +manager configuration 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. +.I update-menus +and Debian's menu package aim to solve this problem. +.PP +.I update-menus +automatically generates menus of installed programs for window +managers and other menu programs. It should be run whenever a +.BR menufile (5) +or menu-method file is changed. +.I update-menus +will be run automatically when Debian packages that contain menu +files are installed on or removed from the system. +.PP +.I update-menus +uses the package-supplied menu entry files (in /usr/share/menu) for +its information about the menus (but this can be overruled by the +system administrator/user; see below). If a menu entry file is executable, +.I update-menus +executes the menu entry file, and uses its stdout to generate the menu +database. + +.SH OPTIONS +.IP "-v" +Verbose output. Shows all arguments to the /etc/menu-methods programs. +.IP "-d" +Debug output. Generates loads of unintelligible output. +.IP "-h, --help" +Display usage help and exit. +.IP "--menufilesdir <dir>" +Adds directory <dir> to the list of directories to search for menu files in. +.IP "--menumethod <method>" +Process only the menu method <method> instead of all the menu methods found. +.IP "--nodefaultdirs" +Disables the search of menu entries in system menu directories. +.IP "--nodpkgcheck" +Do not discard menu entries for packages that are not installed according to +\fIdpkg\fP. +.IP "--remove" +Remove the menus by calling the menu-methods with \fB--remove\fP. +.IP "--stdout" +Output the menu list in a format suitable as input for \fIinstall-menu\fP or a +menu method file. +.IP "--version" +Output version information and exit. +.SH CONFIGURATION +There are several ways to tune the operation of update-menus: +.PP +.I per menu entry, in /etc/menu/$package +.RS +In these directories the system administrator or user can override the default +menu files (If a file /etc/menu/$package exists, than the +corresponding /usr/share/menu/$package file isn't read any more). Users +who want to override the system wide defaults put their files in +~/.menu. See also +.BR menufile(5) +.RE +.I per window-manager in /etc/menu-methods/$wm +.RS +In these configuration files, one can tune generated system.${wm}rc files for +each individual window manager. For example, one can specify that the +wm should ignore any icons that the packages may supply, or set the +default wrapper for text-only applications (usually, an xterm is started to +run a text-only application like vi). Users who want to override the system +wide defaults put their files in ~/.menu-methods. For more info, see +/usr/share/doc/menu/html. +.RE +.I globally, in /etc/menu-methods/translate_menus +.RS +This file contains translations that will be performed for all +menu entries and all window managers. You can specify things like: +`All sections that start with "Games" should be mapped to "Applications/Games"', +or `menuentry "gnuplot" should have a title of "GnuTeken"'. Look at the +default /etc/menu-methods/translate_menus for an example. Users who want to +override the system default translate file, put one in +~/.menu-methods/translate_menus. +.BR Note: +This should not be used for a full translation of the menu. Use po +files as explained in the source package. +.RE +.I error report configuring, in /etc/menu-methods/menu.config +.RS +This file contains general information for the overall behaviour of +update-menus. At the moment you can only configure how verbose the +output of update-menus is, and where it sends the output. The amount +of information is specified by `verbosity=VAL'. Use VAL=quiet to stop +update-menu from reporting anything but the most important errors, +VAL=normal, VAL=verbose, VAL=debug for progressively more output. + +To specify where the output should go, use `method=stdout', +`method=stderr', or `method=syslog facility priority'. `Facility' is one +of auth, authpriv, authcron, authdaemon, authkern, authlocal0, authlocal1, +authlocal2, authlocal3, authlocal4, authlocal5, authlocal6, authlocal7, +authlpr, authmail, authnews, authsyslog, authuser, +authuucp. `priority' is one of emerg, alert, crit, err, warning, +notice, info, debug. + +.RE +.SH FILES +Menu files: (Earlier listed directories override those listed later.) +.RS +.I ~/.menu/* +.RS +Menu files added by the user. (Isn't read if root runs update-menus) +.RE +.I /etc/menu/* +.RS +Menu files added by the system administrator. +.RE +.I /usr/lib/menu/* +.RS +Architecture-dependant menu files provided by other Debian packages. +.RE +.I /usr/share/menu/* +.RS +Architecture-independant menu files provided by other Debian packages. +.RE +.I /usr/share/menu/default/* +.RS +Menu files provided by the menu package. +.RE +.RE +Menu methods: +.RS +.I /etc/menu-methods/ +.RS +Executable configuration files that are added by window managers and other menu +programs, these files are run by +.I update-menus +to generate menus for the different programs. Also in this directory +is the translate_menus file, used for local configuration of the shape of the +menu trees. +.RE +.RE +.RS +.I ~/.menu-methods/ +.RS +For users to override the system-defaults of /etc/menu-methods. +If this directory exists, no files in /etc/menu-methods are read +any more. +.RE +.RE +.SH DISTRIBUTION +Distribution is subject to the GNU General Public License. +.SH BUGS +.I update-menus +may not work properly when run by a normal user, to generate menus for that +user. This is usually because the window manager doesn't expect the +system.${wm}rc files in the directory (usually ~/.${wm}, configurable +in /etc/menu-methods). If you see such a thing, and you find a +solution, please mail <menu@packages.debian.org>. It should work OK for +fvwm and fvwm2: I usually test the package first as an ordinary user. +.PP +.SH AUTHORS +Joost Witteveen <joostje@debian.org>, original idea by +Lars Wirzenius <liw@iki.fi>. Now maintained by +Bill Allombert <ballombe@debian.org>. +.SH THANKS +To Joey Hess, for a lot of good ideas and pre-release testing, and to +Tom Lees for a update-menus in pure C (of which I only used one +function, but that's life). +.PP +Man page by Joey Hess, <joeyh@debian.org> +.SH "SEE ALSO" +.BR menufile (5), +.BR /usr/share/doc/menu/html diff --git a/doc/update-menus.fr.1 b/doc/update-menus.fr.1 new file mode 100644 index 0000000..8d732a8 --- /dev/null +++ b/doc/update-menus.fr.1 @@ -0,0 +1,194 @@ +.\" -*- nroff -*- +.TH UPDATE-MENUS 1 "Utilitaires Debian" "DEBIAN" +.SH NOM +update-menus \- génère les menus d'un système Debian +.SH SYNOPSIS +.B update-menus [\-v] [\-d] [\-h|--help] [--version] [--menufilesdir <répertoire>] [--menumethod <méthode>] [--nodefaultdirs] [--stdout] +.SH DESCRIPTION +Avant l'utilisation de \fIupdate-menus\fP, quand l'administrateur système +installait un paquet sur un système Debian, il devait modifier de nombreux +fichiers de configuration des gestionnaires de fenêtres afin de rendre +accessible ce nouveau programme (les menus de fvwm, par exemple). Ces menus +pouvaient facilement ne plus lister les programmes effectivement accessibles, +certains éléments des menus ne fonctionnant pas, alors que d'autres programmes +n'étaient pas référencés. +.I update-menus +et le paquet Debian menu ont pour but de résoudre ce problème. +.PP +.I update-menus +génère automatiquement les menus des programmes installés pour les +gestionnaires de fenêtres et pour les autres programmes à menus. Il doit être +lancé à chaque fois qu'un fichier de menu (voir +.BR menufile (5)) +ou qu'un script de génération de menus est modifié. +.I update-menus +sera automatiquement lancé dès qu'un paquet Debian contenant des fichiers +de menus sera installé ou supprimé du système. +.PP +.I update-menus +utilise les fichiers de menu fournis par le paquet (dans /usr/share/menu) +pour obtenir ses informations concernant les menus (mais l'administrateur du +système ou un utilisateur peuvent modifier ce comportement, voir plus loin). +Si le fichier de menu est exécutable, +.I update-menus +l'exécute et utilise sa sortie standard pour générer +la base de données du menu. + +.SH OPTIONS +.IP "-v" +Mode bavard. Affiche tous les arguments des programmes /etc/menu-methods +.IP "-d" +Mode Debug. Génère un tas de messages inintelligibles. +.IP "-h, --help" +Affiche un message d'aide et s'arrête. +.IP "--menufilesdir <répertoire>" +Ajoute le répertoire <répertoire> à la liste des répertoires dans laquelle on +recherche des fichiers de menu. +.IP "--menumethod <méthode>" +Traite uniquement le script de génération de menus <méthode>, et non tous les +scripts de génération de menus trouvés. +.IP "--nodefaultdirs" +Désactive la recherche de fichiers de menu dans les répertoires de menu +du système. +.IP "--nodpkgcheck" +Ne pas supprimer les entrées de menu correspondant à des paquets non installés +d'après \fIdpkg\fP. +.IP "--remove" +Supprime les menus générés en passant l'option \fB--remove\fP aux scripts de +génération de menus. +.IP "--stdout" +Génère une liste de menu acceptable comme entrée par \fIinstall-menu\fP ou par +un script de génération de menus. +.IP "--version" +Affiche les informations de version, puis s'arrête. +.SH CONFIGURATION +Il y a plusieurs façons de régler le fonctionnement d'update-menus\ : +.PP +.I par fichier de menu, dans /etc/menu/$paquet +.RS +Dans ce répertoire, l'administrateur système ou l'utilisateur peut passer +outre les réglages par défaut (lorsqu'un fichier /etc/menu/$paquet existe, +le fichier /usr/share/menu/$paquet n'est plus consulté). Un utilisateur +qui veut modifier le réglage par défaut du système placera ses fichiers +dans le répertoire ~/.menu. Voir aussi +.BR menufile (5) +.RE +.I par gestionnaire de fenêtres, dans /etc/menu-methods/$wm +.RS +Dans ces fichiers de configuration, on peut ajuster le fichier system.${wm}rc +généré pour chacun des gestionnaires de fenêtres. Par exemple, on peut +définir que le gestionnaire doit ignorer toute icône que le paquet pourrait +fournir, ou définir le programme générique pour les applications en mode texte +(normalement, c'est xterm qui est lancé pour accueillir une application en mode +texte telle que vi). Les utilisateurs qui veulent passer outre les réglages par +défaut du système déposent leurs fichiers dans ~/.menu-methods. Pour plus +d'informations, consultez /usr/share/doc/menu/html. +.RE +.I globalement, dans /etc/menu-methods/translate_menus +.RS +Ce fichier contient les transformations qui seront utilisées pour chaque entrée +de menu et dans chacun des gestionnaires de fenêtres. Vous pouvez définir des +points tels que\ : «\ Toutes les sections qui commencent par ``Games'' doivent +être référencées par ``Applications/Games''\ », ou «\ l'entrée de menu +``gnuplot'' doit avoir le titre ``GnuTeken''\ » . +Jetez un oeil au fichier par défaut /etc/menu-methods/translate_menus pour +prendre exemple. Les utilisateurs qui veulent passer outre les transformations +par défaut du système le font dans ~/.menu-methods/translate_menus. +.BR Note\ : +ne pas utiliser pour une traduction complète du menu. Servez-vous des fichiers +po comme indiqué dans le paquet source. +.RE +.I pour les rapports d'erreurs, dans /etc/menu-methods/menu.config +.RS +Ce fichier contient des informations générales sur le comportement d' +update-menus. Pour le moment, vous ne pouvez régler que le niveau de bavardage +de la sortie standard du programme, ainsi que la définition de cette sortie. +La quantité d'information est définie par «\ verbosity=VAL\ ». Choisissez +VAL=quiet pour empêcher update-menu d'afficher autre chose que les erreurs les +plus importantes, VAL=normal, VAL=verbose, VAL=debug pour des informations de +plus en plus détaillées. + +Pour définir où le flux sortant doit aller, utilisez «\ method=stdout\ », +«\ method=stderr\ » ou «\ method=syslog facility priorité\ ». «\ facility\ » est +soit auth, authpriv, authcron, authdaemon, authkern, authlocal0, authlocal1, +authlocal2, authlocal3, authlocal4, authlocal5, authlocal6, authlocal7,authlpr, +authmail, authnews, authsyslog, authuser, ou authuucp. «\ priorité\ » est +l'un des termes suivants\ : emerg, alert, crit, err, warning, notice, info, +debug. +.RE +.SH FICHIERS +Fichiers de menu\ : (les répertoires cités en premier sont +prioritaires sur ceux cités plus loin) +.RS +.I ~/.menu/* +.RS +Fichiers de menu ajoutés par l'utilisateur (ignorés si +l'administrateur lance update-menus) +.RE +.I /etc/menu/* +.RS +Fichiers de menu ajoutés par l'administrateur système. +.RE +.I /usr/lib/menu/* +.RS +Fichiers de menu (dépendant de l'architecture) fournis par d'autres paquets +Debian. +.RE +.I /usr/share/menu/* +.RS +Fichiers de menu (indépendant de l'architecture) fournis par d'autres paquets +Debian. +.RE +.I /usr/share/menu/default/* +.RS +Fichiers de menu fournis par le paquet menu. +.RE +.RE +Fichiers de génération de menu (menu methods): +.RS +.I /etc/menu-methods/ +.RS +Fichiers de configuration exécutables ajoutés par les gestionnaires de +fenêtres et autres programmes à menus, qui sont exécutés par +.I update-menus +afin de générer les menus pour ces différents programmes. Le fichier +translate_menus figure aussi dans ce répertoire, et sert aux réglages locaux du +modèle d'arborescence des menus. +.RE +.RE +.RS +.I ~/.menu-methods/ +.RS +Permet aux utilisateurs d'outrepasser le comportement par défaut de +/etc/menu-methods. Si ce répertoire existe, aucun des fichiers de +/etc/menu-methods n'est lu. +.RE +.RE +.SH DISTRIBUTION +La distribution est soumise à la Licence Publique Générale GNU. +.SH BOGUES +.I update-menus +peut connaître des dysfonctionnements quand il est invoqué par un simple +utilisateur pour générer ses propres menus. C'est souvent parce que le +gestionnaire de fenêtres n'attend pas les fichiers system.${wm}rc +dans le répertoire (normalement ~/.${wm}, à configurer dans /etc/menu-methods). +Si vous repérez quelque chose de ce genre et que vous trouvez une solution, +envoyez-moi un courrier à <menu@packages.debian.org>. Cela doit parfaitement +fonctionner pour fvwm et fvwm2\ : je teste d'abord le paquet en tant que simple +utilisateur. +.PP +.SH AUTEURS +Joost Witteveen <joostje@debian.org>, sur une idée originale de +Lars Wirzenius <liw@iki.fi>. Actuellement maintenu par +Bill Allombert <ballombe@debian.org>. +.SH REMERCIEMENTS +À Joey Hess, pour toutes ses bonnes idées et le test de la pré-version, et à +Tom Lees pour son update-menus en C natif (dont je n'ai utilisé qu'une fonction, +mais c'est la vie). +.PP +(page de manuel par Joey Hess, <joeyh@debian.org>) +.SH VOIR AUSSI +.BR menufile (5), +.BR /usr/share/doc/menu/html +.SH TRADUCTION +Sylvain Cherrier <sylvain.cherrier@free.fr> |