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

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

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

8.1 String constants

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

8.2 Variables

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

8.2.1 Special variables

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

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

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

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

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

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

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

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

8.2.2 Preferred variables

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

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

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

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

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

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

8.2.3 Suggested variables

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

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

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

8.3 Functions

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

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

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

print($arg): Same as just $arg; if $arg is empty, generate an error.

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

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

escwith($arg1, $arg2, $arg3): Same as esc, but use $arg3 as escape sequence.

escfirst($arg1, $arg2, $arg3): Same as escwith, but only escapes first occurrence of $arg2.

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

tolower($arg)
toupper($arg): Returns the argument set in lowercases resp uppercases.

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

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

ifempty($arg1, $arg2): If $arg1 is empty, print $arg2, otherwise print nothing. For compatibility, $arg1="none" is interpreted as empty.

ifnempty($arg1, $arg2): If $arg1 is not empty, print $arg2. For compatibility, the string "none" is seen as empty.

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

ifeq($arg1, $arg2, $arg3): If ($arg1==$arg2) then print $arg3

ifneq($arg1, $arg2, $arg3): If ($arg1!=$arg2) then print $arg3

ifeqelse($arg1, $arg2, $arg3, $arg4): If ($arg1==$arg2) then print $arg3 else print $arg4

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

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

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

catfile($arg1): Return the contents of file $arg1.

shell($arg1): Return the output of the shell command $arg1.

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

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

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

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

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

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

entrycount(): the number of entries in this menu.

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

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

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

level(): return nesting of this menu in the total menu tree.

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

rcfile()
examplercfile()
mainmenutitle()
rootsection()
rootprefix()
userprefix()
treewalk()
postoutput()
preoutput(): These functions all output whatever they were defined to be in the menu-method file.

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

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