.TH "Untitled article" 7 2019-11-29
.SH gtkmenuplus 5 "2019-11-28" "version 1.1.10" "menu configuration file"
.SH NAME
.LP
Format of menu configuration files for gtkmenuplus(1).
.SH SYNOPSIS
.sp 1
.nf
\fC
menu_configuration_file
\fR
.fi
.SH DESCRIPTION
.LP
Gtkmenuplus takes a «\fCmenu_configuration_file\fR» as its primary argument, and
constructs a menu from the directives that it reads in the file.  This document
describes the format of the menu configuration file, and the set of valid
directives.
.SH FORMAT
.SH Comments
.LP
Anything on a line after the \(lq#\(rq character is considered a comment and is
ignored, - \(lq#\(rq included.
.LP
The following cases are exceptions in which \(lq#\(rq and the characters that follow
it till the end of the line aren\(cqt comments:
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  a backslash \(lq\e\(rq comes immediately before \(lq#\(rq
.RE
.RS
.ti -\w'\(bu  'u
\(bu  directives «\fCcmd=\fR», «\fCif=\fR», «\fCelseif=\fR»
.RE
.RS
.ti -\w'\(bu  'u
\(bu  variable evaluation «\fCvariable_name==\fR»
.RE
.RS
.ti -\w'\(bu  'u
\(bu  variable assignment of quoted strings that include \(lq#\(rq, such as quoted HTML
colors, i.e., \(lq#FAF090\(rq
.RE
.RS
.ti -\w'\(bu  'u
\(bu  valid shell syntax following the above directives, i.e.,
«\fCif=test ${y#prefix} = abc\fR»
.RE
.RS
.ti -\w'\(bu  'u
\(bu  numerical HTML character entities, i.e.,
«\fC&#10;\fR» or «\fC&#x0a;\fR»
.RE
.LP
Lines whose first non-space character is \(lq#\(rq are ignored.
.SH Lines
.LP
Blank lines are ignored.
.LP
Each meaningful line in a menu configuration file contains a directive (which
may be preceded by whitespace).  The case of directives is ignored.
.SH Directives
.LP
Seven directives are inherited from myGtkMenu, the ancestor to gtkmenuplus.
\fB(M)\fR marks directives whose behaviour in gtkmenuplus differs from that in
myGtkMenu.
.sp 1
.nf
\fC
item=item_description
cmd=command                (M) (command may be null)
icon=path_to_image_file    (M) (path may be null)
separator
submenu=submenu_description
iconsize=size
menupos=x y                (M)
menuposition=x y           (synonym for menupos)
\fR
.fi
.LP
The remaining directives are new in gtkmenuplus:
.sp 1
.nf
\fC
icondirectory=path_to_icon_directory

format=format_string

tooltip=tooltip_text
tooltipformat=format_string

launcher=path_to_launcher(s)
launchersub=path_to_directory
launcherdirectory=path_to_launcher_directory
launcherdir=path_to_launcher_directory (synonym for launcherdirectory)
launcherargs=arguments
launcherdirfile=launcher_dirfile
launchersubmenu=launcher_dirfile

activationlogfile=logfile_path

include=menu_configuration_file or
include=path_to_directory[/file_glob] [directory_glob] 

if=condition
elseif=condition or elif=condition
else
endif or fi

error=message

/path_to/file
\(ti/path_to/file

configure=option_list
onexit
endsubmenu
\fR
.fi
.LP
\fBNotes\fR
.LP
For «\fCdirective=value\fR» there may be whitespace between «\fCdirective\fR» and \(lq=\(rq.
Whitespace between \(lq=\(rq and «\fCvalue\fR» is ignored, as is trailing whitespace after
«\fCvalue\fR».
.LP
A line of «\fCitem=\fR» may be followed by a line of «\fCcmd=\fR», «\fCicon=\fR» and/or
«\fCtooltip=\fR», in any order.
.SH Variables
.sp 1
.nf
\fC
variable_name=value
variable_name==expression
\fR
.fi
.LP
Any string preceding \(lq=\(rq, aside from the directives listed above, will be taken
to be a declaration of a variable, providing it meets the following conditions.
.LP
A «\fCvariable_name\fR» may not be the same as any existing environmental variable.
.LP
A «\fCvariable_name\fR» must begin with an alphabetic character.  All other
characters in a «\fCvariable_name\fR» must be alphabetic, numeric or the underscore.
.LP
Whitespace between a «\fCvariable_name\fR» and \(lq=\(rq is ignored.
.LP
Whitespace following the \(lq=\(rq, and trailing whitespace after «\fCvalue\fR» or
«\fCexpression\fR» is ignored.  If you want to include leading or trailing whitespace
in a value or expression, enclose it all in single or double quotes, which will
be stripped before the value is stored or the expression is evaluated.  You can
also use quotes if you want a value beginning with \(lq=\(rq, e.g.
.sp 1
.nf
\fC
myvar="  something nice "
\fR
.fi
.LP
If a «\fCvariable_name\fR» is followed by \(lq==\(rq, the text after the \(lq==\(rq is
interpreted as an expression which is passed to the shell for evaluation;
whatever ends up in stdout becomes the variable value.
.LP
The value of a «\fCvariable_name\fR» is referenced as «\fC$variable_name\fR» in \fIany\fR»
subsequent line of the same file as well as of included files. For instance
«\fC$variable_name\fR» can be all or part of a command (in a «\fCcmd=\fR» line); of a menu
item\(cqs «\fCitem_description\fR» (in an «\fCitem=\fR» line); or of the condition on «\fCif=\fR» or
«\fCelseif=\fR» lines.
.LP
If the same «\fCvariable_name\fR» is re-assigned, including in included files, its
value is redefined.
.SH Parameters
.LP
Additional arguments can optionally follow «\fCmenu_configuration_file\fR» on the
gtkmenuplus command line.  Such arguments are called \fIpositional parameters\fR,
and their value can be referenced by «\fC$1\fR», «\fC$2\fR»,... etc, in any line in the
«\fCmenu_configuration_file\fR» (except «\fCcmd=\fR» lines, since «\fC$1\fR», «\fC$2\fR»... may occur
in shell one-liners and be confused with gtkmenuplus command line parameter
references).
.LP
Referencing an unassigned (null) parameter is allowed in an evaluation context,
such as «\fCif=\fR», «\fCelseif=\fR» or «\fCvariable_name==\fR», and produces the value 0
(\(oqfalse\(cq, \(oqno\(cq).
.LP
«\fC$0\fR» references the «\fCmenu_configuration_file\fR» itself unless gtkmenuplus gets
its input from stdin.  Reference «\fC$0\fR» is invalid in included files.
.SH Paths
.LP
The following lines may contain a path or paths:
.sp 1
.nf
\fC
cmd=command                
icondirectory=path_to_icon_directory
icon=path_to_image_file    
launcherdirectory=path_to_launcher_directory
launcher=path_to_launcher(s)
launchersub=path_to_directory
include=menu_configuration_file 
include=path_to_directory 
\fR
.fi
.LP
Paths may be absolute (beginning with \(lq/\(rq) or relative.  They may begin with
the tilde (\(lq\(ti\(rq), which in all cases will be expanded into «\fC$HOME\fR», as it would
be by the shell.
.LP
Relative paths may begin with \(lq./\(rq and/or include \(lq../\(rq, begin with the name of
a directory or simply name a file.  With some expections noted below, such
paths will be taken to be relative to the path of the directory that contains
the menu configuration file as specified on the gtkmenuplus command line.
.LP
\fBNote\fR Unlike what the shell does, gtkmenuplus resolves relative paths from
the path of the directory that contains «\fC$0\fR» rather than from the current
working directory.  This can be confusing. For that reason it is recommended to
invoke gtkmenplus with the full path of the «\fCmenu_configuration_file\fR».  This
note applies to the remainder of this section.
.LP
\fBExceptions\fR the following directives resolve relative paths as noted:
.sp 1
.nf
\fC
icon=         directory in the last non-null icondirectory= line, if any
launcher=     directory in the last non-null launcherdirectory= line, if any
launchersub=  directory in the last non-null launcherdirectory= line, if any
cmd=          assumed to be on the system's PATH.
\fR
.fi
.LP
The command on a «\fCcmd=command\fR» line in particular may contain multiple paths
requiring expansion (typically multiple arguments to the specified executable).
After expansion the entire command must be no longer than 1024 (?) characters.
.SH DIRECTIVES
.SH Item
.sp 1
.nf
\fC
item=item_description
\fR
.fi
.LP
Denotes the «\fCitem_description\fR» to show in the menu. An underscore as part of
item description indicates that the next letter is the mnemonic (the
keyboard accelerator) for the menu item.
.LP
A mnemonic can also be added via global formatting, cf. «\fCformat=\fR».
.LP
If you want to include an underscore in the item description but not use it to
indicate a mnemonic, use two consecutive underscores.
.LP
An «\fCitem=\fR» line may be immediately followed by any or all of «\fCcmd=\fR», «\fCicon=\fR»
and «\fCtooltip=\fR» lines, in any order.
.LP
An «\fCitem=\fR» line marks the end of any menu item or submenu preceding it.
.SH Cmd
.sp 1
.nf
\fC
cmd=command
\fR
.fi
.LP
Optional.  Denotes the command to run.
.LP
Must be preceded by an «\fCitem=\fR» line, and possibly by «\fCicon=\fR» or «\fCtooltip=\fR»
lines.  It applies to the menu entry begun by the preceding «\fCitem=\fR» line.
.LP
The command that follows «\fCcmd=\fR» on the line must be a valid (syntax error free)
shell command, or nothing.
.LP
«\fCcmd=\fR», on its own, or an «\fCitem=\fR» not followed by a «\fCcmd=\fR», will create a
disabled menu item (possibly to use as a menu or section title).
.LP
You can use \(lq\(ti\(rq to refer to your home directory, e.g. \(ti/bin/myScript.sh.
.LP
A «\fCcmd=\fR» line is the only kind of line in which you can\(cqt use parameters
originating on the gtkmenuplus command line, or as part of an include line,
since «\fC$1\fR», «\fC$2\fR»... may occur in shell one-liners and be confused with
gtkmenuplus command line parameter references.  If you want to use a parameter
in a command, set a variable to the parameter e.g.
.sp 1
.nf
\fC
myParam=$1
\fR
.fi
.LP
and use the variable ($myParam) in the command.   
.LP
Not everything that can work at a shell prompt will work in «\fCcmd=\fR»:  
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  You can\(cqt specify more than one command on a line (using ;, && or |).
.RE
.RS
.ti -\w'\(bu  'u
\(bu  You can\(cqt use environmental variables (e.g. $WINEPREFIX, $HOME).
.RE
.LP
However, you \fIcan\fR get the shell to do stuff like that for gtkmenuplus.  Either
you can make a small script containing the commands you need, or you can make
your command a shell invocation with «\fCsh -c\fR», e.g.:
.sp 1
.nf
\fC
 # start two instances of freecell
 cmd=sh -l -c "( sol --freecell &) ; (sol --freecell &)"
\fR
.fi
.LP
You also can have:
.sp 1
.nf
\fC
 cmd=path_to_a_non_executable_file [path_to_other_non_executable_file ...]
\fR
.fi
.LP
A «\fCnon_executable_file\fR» could for instance be a doc, html, xls or plain text
file.  «\fCpath_to_a_non_executable_file\fR» can begin with a tilde (for the home
directory), or be a relative or absolute path.
.LP
If a «\fCcmd=\fR» begins with a «\fCnon_executable_file\fR», its MIME type is used to
determine which application will be used to execute that file (and any
«\fCpath_to_other_non_executable_files\fR» on the same line). 
.SH Tooltip
.sp 1
.nf
\fC
tooltip=tooltip_text
\fR
.fi
.LP
Optional. Adds a tooltip to a menu item or submenu.
.LP
Must be preceded by an «\fCitem=\fR», and possibly by an «\fCicon=\fR» and/or (if there\(cqs a
preceding «\fCitem=\fR» line) a «\fCcmd=\fR» line.  It applies to the menu entry begun by
the preceding «\fCitem=\fR» line or submenu begun by the preceding «\fCsubmenu=\fR» line.
.SH Icon
.sp 1
.nf
\fC
icon=path_to_image_file | icon_name | NULL
\fR
.fi
.LP
Optional.  Denotes an image to show with the menu item or submenu. 
.LP
Must be preceded by an «\fCitem=\fR», or «\fCsubmenu=\fR» line, and possibly by an «\fCicon=\fR»
and/or (if there\(cqs a preceding «\fCitem=\fR» line) a «\fCcmd=\fR» line.
.LP
It applies to the menu entry begun by the preceding «\fCitem=\fR» line or submenu
begun by the preceding «\fCsubmenu=\fR» line.
.LP
If a menu item lacks an icon line, or has an «\fCicon=\fR» line with nothing
following the \(lq=\(rq sign, gtkmenuplus will attempt to find an icon associated
with the executable named in the menu item\(cqs «\fCcmd=\fR» line; or, if the «\fCcmd=\fR»
line specifies only a non-executable file, an attempt will be made to locate an
icon associated with the default program used to open that file.
.LP
There are situations in which gtkmenplus can\(cqt automatically determine the icon
image for an «\fCitem=\fR» without an «\fCicon=\fR». In such cases you need specify the
icon explicitly:
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  any submenu
.RE
.RS
.ti -\w'\(bu  'u
\(bu  a menu item where the command on the «\fCcmd=command\fR» involves «\fCsh -c\fR» to run
multiple shell commands
.RE
.RS
.ti -\w'\(bu  'u
\(bu  a menu item where «\fCcmd=\fR» involves a terminal emulator to run a shell command
.RE
.RS
.ti -\w'\(bu  'u
\(bu  a menu item where «\fCcmd=\fR» involves gtksu, gksudo or equivalent to run a shell
command 
.RE
.RS
.ti -\w'\(bu  'u
\(bu  successive menu items (e.g. ones opening text files) which, based on command
or file type would all have the same icon
.RE
.RS
.ti -\w'\(bu  'u
\(bu  a «\fCcmd=\fR» consisting of a URL to something on the net or on another machine.
If the net isn\(cqt accessible, gtkmenuplus will block while trying to get
information about the target file type.  It might be better to use a named
icon like, .e.g., text-html or applications-internet.
.RE
.LP
If you do not want an image on your menu item, use the line «\fCicon=NULL\fR», or the
method described below.
.LP
If the most recently encountered \(lqconfigure=\(rq line in the menu configuration
file included the word «\fCnoicons\fR», any item without an «\fCicon=path_to_image_file\fR»
or «\fCicon=icon_name\fR» line will not be assigned an image.
.LP
A subsequent «\fCconfigure=\fR» line containing the word «\fCicons\fR» will cause
gtkmenuplus to revert to its default behaviour of finding icons based on the
application or filetype specified on the «\fCcmd=\fR» line.
.LP
The «\fCpath_to_image_file\fR» includes a dotted file extension and follows the rules
for paths referred to in menu configuration files (see above):
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  A «\fCpath_to_image_file\fR» can begin with a tilde, which will be expanded as in
bash to «\fC$HOME\fR».
.RE
.RS
.ti -\w'\(bu  'u
\(bu  It can be absolute.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  Or it can be relative.  If it doesn\(cqt begin with a dot, and the most recent
«\fCicondirectory=path_to_icon_directory\fR» line has a non-null
«\fCpath_to_icon_directory\fR», the path is relative to that.  Otherwise it\(cqs
relative to the path in which the configuration file was found (as specified
on the gtkmenuplus command line, unless gtkmenuplus is reading from stdin). 
.RE
.LP
The dotted file extension indicates one of the supported image types: png, svg,
xpm or gif.
.LP
Tip: To speed execution, all icon files associated with a menu configuration
file should be of the same image size.
.LP
Instead of a «\fCpath_to_image_file\fR» you can use an «\fCicon_name\fR», which  is
distinguished by not including an extension for the image type.
.LP
An «\fCicon_name\fR» will be recognised if icons matching it are in one of the
standard sets of icon directories (e.g. /usr/share/pixmaps/, subdirectories of
/usr/share/icons, etc); in particular the icon names listed in
freedesktop.org\(cqs Icon Naming Specification: 
.LP
\fIhttp://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html\fR
.SH Format
.sp 1
.nf
\fC
format=formatting 

formatting=[ format_string [;|, format_string [;|, format_string... ]]]
\fR
.fi
.LP
Menu items and submenu labels following a «\fCformat\fR» line have the given
«\fCformat_string\fR»(s) applied, until the occurrence of the next
«\fCformat=formatting\fR» line.  
.br
CAVEAT: However, «\fCformatting\fR» is not applied to items for which a corresponding non-empty command exists («\fCitem=\fR, «\fCcmd=\fR). This should probably be considered a bug.
.LP
If more than one «\fCformat_string\fR» occurs on a «\fCformat=\fR» line, each
«\fCformat_string\fR» is applied in turn to successive following items or submenu
labels at the same level as the menu level in which the «\fCformat=\fR» line occurs.
Items or submenu labels at any other level in the menu hierachy are \fInot\fR
subject to the «\fCformat_string\fR» sequence.
.LP
If «\fCformatting\fR» contains only one «\fCformat_string\fR», that «\fCformat_string\fR» applies
to everything following, no matter where it is in the menu hierarchy.
.LP
A «\fCformat_string\fR» consists of a string of whitespace-separated
attribute=\(lqvalue\(rq pairs, attributes and their values must be appropriate for
placement within a «\fC<span>\fR» tag in the Pango Text Attribute Markup Language,
see 
\fIhttps://developer.gnome.org/pango/stable/PangoMarkupFormat.html\fR
for details
(the \(lqconvenience tags\(rq mentioned aren\(cqt supported).
.LP
An additional non-Pango attribute=\(lqvalue\(rq pair is supported, «\fCmnemonic\fR», see
further down for details.
.LP
Examples:
.sp 1
.nf
\fC
format= font_desc="Sans Italic 12"
format= style="bold" underline="single"
format= foreground="blue"  # color names see /usr/share/X11/rgb.txt
format= weight="bold"      # also possible: "ultralight", "light", "normal",
                           # "ultrabold", "heavy", or a numeric weight
format= size='12800'       # in 1024ths of a point, or one of 'xx-small',
                           # 'x-small', # 'small', 'medium', 'large',
                           # 'x-large', 'xx-large'
format= color="RoyalBlue";color="DodgerBlue"  # alternate two shades
\fR
.fi
.LP
A «\fCformat=\fR» with a null «\fCformat_string\fR» causes all subsequent menu and submenu
items to revert to default formatting.
.LP
As well as using «\fCformat=\fR» lines to modify some menu and submenu entries,
global changes (background color, font, etc.) can be made to menus using the
built-in \(lqGTK theme\(rq mechanism.
.LP
GTK2 and GTK3 differ in the way themes are defined and applied for specific
applications. For GTK2 only you can invoke gtkmenuplus as such:
.sp 1
.nf
\fC
env GTK2_RC_FILES=gtk2_rc_file gtkmenuplus menu_configuration_file
\fR
.fi
.LP
Note: Since version 1.1.3 gtkmenplus unexports variable «\fCGTK2_RC_FILES\fR» to
avoid changing the default theme of any GTK2 application that is being
executed.
.LP
As yet another formatting method, the text of any menu item or submenu label
can be formatted by wrapping it in «\fC<span format_string>some text</span>\fR» tags,
e.g.
.sp 1
.nf
\fC
<span color="white">some text</span>
\fR
.fi
.LP
Menu items or submenus formatted by inclusion of «\fC<span...>...</span>\fR» tags or
by preceding «\fCformat=\fR» lines mustn\(cqt contain \(lq<\(rq or \(lq>\(rq characters.  Use
«\fC&lt;\fR»  or «\fC&gt;\fR» instead.
.LP
If a «\fCformat=\fR» line is in force, that will apply to all parts of a line
containing «\fC<span...>...</span>\fR» tags not within those tags.
.LP
«\fCmnemonic=value\fR» is a semantic, non-Pango attribute=\(lqvalue\(rq that modifies each
formatted item label by inserting a keyboard accelerator key mark («\fC_\fR») before
the character that is to act as accelerator.  The key is detected only while
the menu is being displayed.  Menus display mnemonic keys as underlined
characters.
.LP
«\fCValue\fR» can be either «\fC"1"\fR» or an arbitrary non-null quoted string.
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  «\fC"1"\fR» inserts «\fC_\fR» before the label, unless the label already includes its own
mnemonic.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  A quoted string inserts «\fC_<char><space>\fR» before the label, also
when the label already includes its own mnemonic. «\fC<char>\fR» represents a
character extracted (sequentially with recycling) from «\fCvalue\fR» The sequence is
recycled separately for each submenu level.
.RE
.LP
Examples:
.sp 1
.nf
\fC
format = mnemonic="1"
launchersub = /usr/share/applications
\fR
.fi
.LP
Turns the first letter of all application menu item labels into a mnemonic,
unless the label already includes its own mnemonic.
.sp 1
.nf
\fC
format = mnemonic="ABC"
submenu = England
  item = London
  item = Birmingham
  item = Liverpool
  item = Manchester
submenu = Scotland
  item = Glasgow
  item = Edingburgh
  item = Aberdeen
  item = Inverness
\fR
.fi
.LP
expands into two submenus with the following labels
.sp 1
.nf
\fC
_A England
   _A London, _B Birmingham, _C Liverpool, _A Manchester
_B Scotland
   _A Glasgow, _B Edingburgh, _C Aberdeen, _A Inverness
\fR
.fi
.LP
The rules for applying mnemonic=\(lqvalue\(rq are the same rules as for applying
global label formatting.  menmonic=\(lqvalue\(rq can\(cqt be used within «\fC<span>\fR» tags
and with directive «\fCtooltipformat=\fR».
.SH Tooltipformat
.sp 1
.nf
\fC
tooltipformat=format_string
\fR
.fi
.LP
The text of all tooltips encountered in menu items and submenus is formatted by
the preceding «\fCtooltipformat=format_string\fR» line.
.LP
«\fCformat_string\fR» is as for «\fCformat=>format_string\fR» lines.
.LP
A null «\fCformat_string\fR» turns off formatting for tooltips in subsequent menu
items and submenus.
.SH Launcher
.sp 1
.nf
\fC
launcher=path_to_launcher(s)
\fR
.fi
.LP
A launcher is a freedesktop.org\(cqs «\fC.desktop\fR» file used to launch an
application. It usually includes a name, executable, comment (tooltip) and
icon.  System desktop files can be located in /usr/share/applications, and
/usr/local/share/applications. User\(cqs application files can be located in
\(ti/.local/share/applications, or any other directory.
.LP
If «\fCpath_to_launcher\fR» is the path of a .desktop file, it will be used to create
a menu entry, unless an exclusion case applies (see section \fILauncher Exclusion
Cases\fR).
.LP
Any preceding «\fCformat=format_string\fR» line will apply to that entry.
.LP
Any preceding «\fClauncherargs=arguments\fR» line will apply to that entry, that is,
the «\fCarguments\fR» string will be appended to the command entry for the shell to
execute. Quote «\fCarguments\fR» as needed.
.LP
If «\fCpath_to_launcher(s)\fR» is a directory path (dirpath), it will be scanned for
\&.desktop files, which will all be used to create successive menu entries.
.LP
Any preceding «\fClauncherdirfile=launcher_dirfile\fR» line will apply to the menu
entry of each scanned dirpath.
.LP
«\fCpath_to_launcher(s)\fR» can also be a colon-separated list of paths. In this case
a single «\fClauncher=\fR» line effectively expands to multiple
«\fClauncher=member_path\fR» lines, where «\fCmember_path\fR» represents each successive
member of «\fCpath_to_launcher(s)\fR».  Expansion stops at the end of the list if
«\fCconfigure=nolauncherlistfirst\fR» is enabled (by default it is). If
«\fCconfigure=launcherlistfirst\fR» is enabled, expansion stops after the first
successful file hit in the list.
.LP
Note that each unsuccessful expansion is likely to produce a \(lqFile not found\(rq
error message, which in turn will display an error box. To prevent such error
box from appearing use «\fCconfigure=errorconsoleonly\fR».
.LP
«\fCpath_to_launcher(s)\fR» follows the rules for paths referred to in menu
configuration files (see above):
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  It can begin with a tilde, which will be expanded as in bash to $HOME.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  It can be absolute.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  Or it can be relative.  If «\fCpath_to_launcher(s)\fR» doesn\(cqt begin with a dot,
and the most recent «\fClauncherdirectory=path_to_launcher_directory\fR» line has a
non-null «\fCpath_to_launcher_directory\fR», it\(cqs relative to that.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  Otherwise a relative «\fCpath_to_launcher(s)\fR» is relative to the path in which
the configuration file was found (as specified on the gtkmenuplus command
line, unless gtkmenuplus is reading from stdin).
.RE
.LP
If you want to refer to all the .desktop files in the directory specified by
«\fClauncherdirectory=\fR» use
.sp 1
.nf
\fC
launcher=.
\fR
.fi
.LP
or
.sp 1
.nf
\fC
launcher=*
\fR
.fi
.SH Launcher Exclusion Cases
.LP
A .desktop file is displayed in the menu unless one or more of the following
exclusion cases apply:
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The file is a regular file and its name doesn\(cqt end with \(lq.desktop\(rq, i.e.,
/path/MyEditor.desktop is included; /path/MyEditor is exluded.
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The file is a link and the name of its ultimate target doesn\(cqt end with
\(lq.desktop\(rq, i.e.,
.LP
/path/MyEditor -> /path/a -> /path/b/geany.desktop   # included
/path/MyEditor -> /path/edit_app                     # excluded
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The file includes entry \(lqNoDisplay=true\(rq and «\fCconfigure=launchernodisplay\fR» is
enabled (by default it is).
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The file includes a \(lqCategories=List\(rq entry and List isn\(cqt empty, and an
applicable «\fClauncherdirfile=\fR» «\fCCategories=\fR» entry excludes List.
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The file doesn\(cqt include a \(lqCategory=List\(rq entry or List is empty, and
«\fCconfigure=launchernullcategory\fR» is disabled (by default it\(cqs enabled), and a
\(lqCategory=\(rq list of an applicable «\fClauncherdirfile=\fR» «\fCdirfile\fR» doesn\(cqt
include special category \(lqNULL\(rq (verbatim).
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The \(lqCategory=\(rq entries of the .desktop file and of an applicable
«\fClauncherdir=\fR» «\fCdirfile\fR» are defined, and the intersection between their
list values is empty. Note that null list elements, such as the null item
found between two semicolons in e.g. \(lqDesktop;;System\(rq, don\(cqt count towards
finding an intersection.
.RE
.SH Launchersub
.sp 1
.nf
\fC
launchersub=path_to_directory
\fR
.fi
.LP
It is a recursive version of «\fClauncher=\fR». It displays all the .desktop files
that it can find in «\fCpath_to_directory\fR» and in the subdirectories under it.
Menu entries are created in nested submenus according to the subdirectory
level. More information follows further down in this section.
.LP
«\fCpath_to_directory\fR» can also be a colon-separated list of paths. In this case a
single «\fClaunchersub=\fR» line effectively expands into multiple
«\fClaunchersub=member_path\fR» lines, where «\fCmember_path\fR» represents each successive
member of «\fCpath_to_directory\fR».  Expansion stops at the end of the list if
«\fCconfigure=nolauncherlistfirst\fR» is enabled (by default it is). If
«\fCconfigure=launcherlistfirst\fR» is enabled, expansion stops after the first
successful recursive directory hit in the list.
.LP
Note that each unsuccessful expansion is likely to produce a \(lqFile not found\(rq
error message, which in turn will display an error box. To prevent such error
box from appearing use «\fCconfigure=errorconsoleonly\fR».
.LP
Rules for relative paths, the directives «\fClauncherdirfile=\fR» and «\fClauncherargs=\fR»,
and \fILauncher Exclusion Cases\fR» all apply to «\fClaunchersub=\fR» as they do to
«\fClauncher=\fR». Each topic is explained elsewhere in this document.
.LP
When «\fClaunchersub=dirpath\fR» is encounted submenus are created automatically for
«\fCdirpath\fR» and each scanned subdirectory.
.LP
Up to 5 menu levels are automatically nested (see «\fCMAX_SUBMENU_DEPTH\fR»).
.LP
By default the submenu label is the name of the subdirectory that includes its
\&.desktop files, and the submenu icon is undefined. To specify different values
and other properties use directive «\fClauncherdirfile=\fR».
.LP
If the maximum allowed submenu depth is exceeded, «\fClaunchersub=dirpath\fR» reports
a warning and displays the menu. Contrast that with the «\fCsubmenu=\fR» directive,
which exits with a fatal error if submenu depth is exceeded.
.LP
By default subdirectory scanning depth is set to fill at most 5 submenu levels.
If launcher files exist in lower subdirectories they will be ignored without
warnings.
.LP
For menu testing purposes you can force printing warnings by telling
gtkmenuplus to scan for launcher files at deeper levels. Then if such files
exist and they can\(cqt be displayed within the «\fCMAX_SUBMENU_DEPTH\fR» hard limit, a
warning message is printed to the console. To increase the scan depth set
environment variable «\fCGTKMENUPLUS_SCAN_DEPTH=5\fR» or higher.
.LP
Item formatting for the items in «\fCdirpath\fR» of «\fClaunchersub=dirpath\fR» is set by
the most recent «\fCformat=\fR» and «\fCtooltipformat=\fR» directives that precede
«\fClaunchersub=dirpath\fR». For nested subdirectories, you can control item
formatting by specifying «\fCformat_strings\fR» in a file named «\fC.desktop.directory\fR».
See section \fIFormat\fR» about «\fCformat_strings\fR». Several example menus are included
in directory \(lqtest\(rq of the project repository.
.SH Launcherdirfile
.sp 1
.nf
\fC
launcherdirfile=launcher_dirfile
\fR
.fi
.LP
After this line is encountered, properties of «\fCdirpath\fR» in all subsequent
«\fClauncher=dirpath\fR» and «\fClaunchersub=dirpath\fR» lines are read from
«\fClauncher_dirfile\fR», which stands of \(lqlauncher desktop directory file\(rq.
.LP
A «\fClauncher_dirfile\fR» is a .desktop file that doesn\(cqt include an \(lqExec=\(rq line,
and may include lines \(lqType=Directory\(rq and \(lqFormat=formatting\(rq.
.LP
It sets the menu entry label, icon, and tooltip for each scanned «\fCdirpath\fR».
.LP
Formatting is applied to all contained items and cascades to subdirectories of
«\fCdirpath\fR».
.LP
\&.desktop file entry \(lqCategories=List\(rq, if any, is used to filter which .desktop
files to display in the menu, as explained in section \fILauncher Exclusion
Cases\fR.
.LP
«\fClauncherdirfile=\fR» followed by no text clears out the «\fClauncher_dirpath\fR» string
for all subsequent «\fClauncher=dirpath\fR» lines.
.LP
There can be multiple «\fClauncherdirfiles\fR» lines; each one sets the
«\fClauncher_dirfile\fR» for all «\fClauncher=dirpath\fR» lines that follow, until the next
«\fClauncherdirfile=\fR» line.
.LP
«\fClauncher_dirfile\fR» follows the rules for paths referred to in menu
configuration files (see above): tilde expansion and relative paths.
.LP
An alternative method to provide settings for «\fClauncher{sub}=dirpath\fR» lines is
to place a hidden file named «\fC.desktop.directory\fR» in each subdirectory. If this
file exists, it overrides the «\fClauncher_dirfile\fR» specified by
«\fClauncherdirfile=launcher_dirfile\fR».
.LP
Example of «\fClauncher_dirfile\fR»:
.sp 1
.nf
\fC
# Note: This file is ignored if its dirpath is used in "launcher=dirpath".
[Desktop Entry]
Encoding=UTF-8
Name=submenu label
Comment=redirected from .desktop.directory (tooltip)
Name[es]=localized label example
Comment[es]=localized tooltip example
Icon=icon_name_no_extension or full_path_to_icon_file_with_extension
Type=Directory
Categories=
# Format applies to contained items, and cascades.
Format=background="purple" etc.
# You can also apply direct (local) formatting to Name= and Comment=
# (label and tooltip), i.e.
# Name=<span>background="green">submenu name</span>
\fR
.fi
.SH Launchersubmenu
.sp 1
.nf
\fC
launchersubmenu=launcher_dirfile
\fR
.fi
.LP
«\fClaunchersubmenu=\fR» describes a submenu as an alternative to «\fCsubmenu=\fR».
.LP
Label, icon, and tooltip are read from «\fClauncher_dirfile\fR» instead of being
specified through «\fCitem=\fR», «\fCicon=\fR», etc.  In all other aspects
«\fClaunchersubmenu\fR» works like «\fCsubmenu=\fR».
.SH Launcherargs
.sp 1
.nf
\fC
launcherargs=arguments
\fR
.fi
.LP
After this line is encountered, in all subsequent «\fClauncher{sub}=\fR» lines, the
«\fCarguments\fR» string will be appended to the launcher command entry for the shell
to execute. Quote «\fCarguments\fR» as needed.
.LP
«\fClauncherargs=\fR» followed by no text clears out the arguments string for all
subsequent «\fClauncher=\fR» lines.
.LP
There can be multiple «\fClauncherargs\fR» lines; each one sets the arguments for all
«\fClauncher{sub}=\fR» lines that follow, until the next «\fClauncherargs=\fR» line.
.SH Launcherdir, Launcherdirectory
.sp 1
.nf
\fC
launcherdirectory=path_to_launcher_directory

launcherdir=path_to_launcher_directory
\fR
.fi
.LP
After this line is encountered, in all subsequent
«\fClauncher=path_to_launcher(s)\fR» lines, if «\fCpath_to_launcher(s)\fR»  doesn\(cqt begin
with a tilde or forward slash, it\(cqs assumed to be relative to
«\fCpath_to_launcher_directory\fR».
.LP
«\fCpath_to_launcher_directory\fR» follows the rules for paths referred to in menu
configuration files (see above). 
.LP
If «\fCpath_to_launcher_directory\fR» doesn\(cqt begin with a tilde or forward slash,
it\(cqs assumed to be relative to the path in which the configuration file was
found (as specified on command line).
.LP
«\fClauncherdirectory=\fR» followed by no text reverts the base path for icons to the
path in which the configuration file was found (as specified on command line).
.LP
There can be multiple «\fClauncherdirectory\fR» lines; each one sets the base
directory for all «\fClauncher=\fR» that follow, until the next «\fClauncherdirectory=\fR»
line.
.SH Activationlogfile
.sp 1
.nf
\fC
activationlogfile=logfile_path
\fR
.fi
.LP
After this line is encountered and «\fClogfile_path\fR» specifies a valid file path,
three things happen:
.sp 1.0v
.RS
.ti -\w'1.  'u
1.  File «\fClogfile_path\fR» is created if it doesn\(cqt exist.
.RE
.RS
.ti -\w'2.  'u
2.  All parsed menu items and launchers encountered after this line and before
an «\fCactivationlogfile=\fR» (null path) line are flagged as \(lqloggable\(rq.
.RE
.RS
.ti -\w'3.  'u
3.  Activating a \(lqloggable\(rq entry writes its attributes («\fCitem=\fR», «\fCcmd=\fR»,
«\fCicon=\fR», «\fCtooltip=\fR» or, for launchers, \(lqName=\(rq, \(lqExec=\(rq, \(lqIcon=\(rq,
\(lqComment=\(rq) to the log file «\fClogfile_path\fR».
.RE
.LP
The log file is formatted as a gtkmenuplus «\fCmenu_configuration_file\fR» and can be
included in other menu configuration files with «\fCinclude=logfile_path\fR».
.LP
If «\fClogfile_path\fR» doesn\(cqt begin with a tilde or forward slash, it\(cqs assumed to
be relative to the path in which the configuration file was found (as specified
on command line).
.LP
Generally speaking the log file shouldn\(cqt be edited, although some changes are
allowed within the limits explained in the project repository (see git commit
message 8bd8abf, which documents log file format and application development
policies).
.SH Include
.LP
First form:
.sp 1
.nf
\fC
include=menu_configuration_file [parameter1 [parameter2 ...]]
\fR
.fi
.LP
Second form (explained further down):
.sp 1
.nf
\fC
include=path_to_directory[/file_glob] [directory_glob] 
\fR
.fi
.LP
The first form inserts the contents of a «\fCmenu_configuration_file\fR» into the one
in which the line occurs, at the point at which it occurs.
.LP
«\fCmenu_configuration_file\fR» follows the rules for paths referred to in menu
configuration files (see above). 
.LP
If you want the contents of a «\fCmenu_configuration_file\fR» to appear in a submenu,
indent the «\fCinclude=\fR» line as well as all the lines of the
«\fCmenu_configuration_file\fR» just as you would if the contents of the file were
found in the including file.
.LP
Be careful not to include recursively, directly or indirectly, a
«\fCmenu_configuration_file\fR» in itself.
.LP
Parameters can be referred to as «\fC$1\fR», «\fC$2\fR», etc. anywhere in the included
«\fCmenu_configuration_file\fR».  See section \fIParameter references\fR» above for more
detail.
.LP
The following rules apply as the included «\fCmenu_configuration_file\fR» is
processed:
.LP
Any paths (see section \fIPaths\fR above) beginning with a dot are taken to be
relative to the directory in which the included file lives; this will of course
change nothing if the including and included file are in the same directory.
.LP
If «\fCicondirectory=path_to_icon_directory\fR» and/or
«\fClauncherdirectory=path_to_launcher_directory\fR» directives are in force in the
including file, the «\fCpath_to_icon_directory\fR» or «\fCpath_to_launcher_directory\fR»
remain in force within the included file.
.LP
If «\fCicondirectory=path_to_icon_directory\fR» and/or
«\fClauncherdirectory=path_to_launcher_directory\fR» lines are encountered in an
included file, the «\fCpath_to_icon_directory\fR» or «\fCpath_to_launcher_directory\fR»
remain in force only within the included file; they revert to the values set in
the including file once the included file is processed.
.LP
If the most recently encountered «\fCconfigure=\fR» line in the menu configuration
file included the word «\fCformattinglocal\fR», the effects of any «\fCformat=\fR» or
«\fCtooltipformat=\fR» lines that occur within the included menu configuration file
will persist only until the end of that included file.  Formatting then reverts
to that specified by the last encountered «\fCformat=\fR» and «\fCtooltipformat=\fR» lines
in the including file.
.LP
This behaviour can be turned off with a «\fCconfigure=\fR» line containing the word
«\fCformattinglocal\fR».
.LP
Second form:
.sp 1
.nf
\fC
include=path_to_directory[/file_glob] [directory_glob] 
\fR
.fi
.LP
«\fCpath_to_directory\fR» follows the rules for paths referred to in menu
configuration files.
.LP
The second form inserts a series of menu entries, one per file, including only
those files to which the user has read access matching the «\fCfile_glob\fR»
specified (e.g. «\fC*.txt\fR», «\fCd?t*\fR», «\fC[a-f]*.txt\fR»).  
.LP
(??) Extended globbing patterns can be used: see
.LP
\fIhttp://www.linuxjournal.com/content/bash-extended-globbing\fR
.LP
The generated menu item name will be the file name; if chosen the command
executed will be the full path to the file.
.LP
There is no recursion into subdirectories under «\fCpath_to_directory\fR» unless
there\(cqs a «\fCdirectory_glob\fR».  If one exists it\(cqs applied only to subdirectories
within «\fCpath_to_directory\fR», not to the matching of subdirectories further down
the directory tree.
.LP
Only subdirectories containing a file matching «\fCfile_glob\fR» appear in the
generated menu.  Subdirectories to which the user doesn\(cqt have read access are
ignored.
.LP
The second form may be immediately followed by any or all of «\fCicon=\fR»,
«\fCtooltip=\fR» and «\fCcmd=\fR» lines, in any order.  If it is, the icon and tooltip will
be applied to each of the menu entries created; if there\(cqs a command, it will
be prepended to the path associated with the chosen item in the menu generated
by the «\fCinclude=\fR» line.
.SH Absolute Path
.sp 1
.nf
\fC
/path_to/file, \(ti/path_to/file
\fR
.fi
.LP
A line in a menu configuration file can be an absolute path to a file,
beginning with a forward slash or tilde.  No directive is expected or required,
nor is it to be followed by «\fCicon=\fR», «\fCtooltip=\fR» or «\fCcmd=\fR» lines.  
.LP
By default, menu items generated from such lines will display the file name
prefixed by its immediately containing subdirectory.
.LP
Each generated item\(cqs tooltip will display the full path to the file, as
provided in the menu configuration file, before tilde expansion.
.LP
If a previously encountered «\fCconfigure=\fR» line includes «\fCabspathparts n\fR», the
lowest n elements of the path (the filename counts as one element) will be
displayed.  If «\fCn\fR» is zero, the whole path will be displayed.
.LP
The most likely use of such lines in a menu configuration file is to make it
possible to generate a configuration file on the fly and pipe it into
gtkmenuplus, with e.g. something like:
.sp 1
.nf
\fC
{ echo "configure abspathparts 3" ; find \(ti -name *.conf } | gtkmenuplus -
\fR
.fi
.SH Submenu
.sp 1
.nf
\fC
submenu=submenu_description
\fR
.fi
.LP
It denotes a «\fCsubmenu_description\fR» to show in the menu listing. See also
«\fClaunchersubmenu=\fR».
.LP
It may be followed by «\fCicon=\fR» and/or «\fCtooltip=\fR» lines, which, if they are to
relate to a given «\fCsubmenu=\fR», must precede lines with any other directive except
«\fCif=\fR», «\fCelseif=\fR», «\fCelse\fR» or «\fCendif\fR».
.LP
By default, (but see «\fCconfigure=endsubmenu\fR», below):
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  The «\fCicon=\fR» and/or «\fCtooltip=\fR» must be indented using the tab character.  They
must be indented by one more tabs than the «\fCsubmenu=\fR» line, as must all menu
entries in the submenu.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  The first line that is not indented with the same number of tabs signals the
end of this submenu.
.RE
.RS
.ti -\w'\(bu  'u
\(bu  The indentation of lines with directives like «\fCiconsize=\fR», «\fCmenupos=\fR»,
«\fCicondirectory=\fR», «\fCformat=\fR», «\fCtooltipformat=\fR», «\fCif=\fR», etc, don\(cqt make up part
of the definition of a menu item or submenu definition, and therefore is
ignored and has no effect on when a submenu ends.
.RE
.LP
Submenus can be nested up to a maximum of 5 levels. Changing this limit
requires recompiling the source code: look for and change the value of
«\fCMAX_SUBMENU_DEPTH\fR».
.LP
A «\fCsubmenu=\fR» line marks the end of any menu item or submenu that precede it.
.SH Configure
.sp 1
.nf
\fC
configure= keywords
\fR
.fi
.LP
Any of the keywords «\fCendsubmenu\fR», «\fCnoendsubmenu\fR», «\fCicons\fR», «\fCnoicons\fR»,
«\fCformattinglocal\fR», «\fCnoformattinglocal\fR», «\fClaunchernodisplay\fR»,
«\fCnolaunchernodisplay\fR», «\fClaunchernullcategory\fR», «\fCnolaunchernullcategory\fR»,
«\fClauncherlistfirst\fR», «\fCnolauncherlistfirst\fR», «\fCerrormsgbox\fR» , «\fCnoerrormsgbox\fR»,
«\fCabspathparts\fR», «\fCmenuposition\fR», and «\fCiconsize\fR» can occur on this line.  
.LP
«\fCabspathparts\fR» and «\fCiconsize\fR» must be immediately followed by whitespace, then
an integer; «\fCmenuposition\fR» must be followed by whitespace, then two
whitespace-separated integers.
.LP
For the effects of «\fCendsubmenu\fR»/«\fCnoendsubmenu\fR», see the «\fCendsubmenu\fR» line.
.LP
For the effects of «\fCicons\fR»/«\fCnoicons\fR», see the «\fCicon=\fR» line.
.LP
For the effects of «\fCformattinglocal\fR»/«\fCnoformattinglocal\fR», see the
«\fCinclude=menu_configuration_file\fR» line.
.LP
For the effects of «\fClaunchernodisplay\fR»/«\fCnolaunchernodisplay\fR» and
«\fClaunchernullcategory\fR» / «\fCnolaunchernullcategory\fR», see \fILauncher Exclusion
Cases\fR» in section \fILauncher\fR», which also applies to the «\fClaunchersub=\fR» line.
.LP
For the effects of «\fClauncherlistfirst\fR»/«\fCnolauncherlistfirst\fR» see the
«\fClauncher=\fR» and «\fClaunchersub=\fR» lines.
.LP
For the effects of «\fCabspathparts n\fR», see section \fIPlain File Path\fR».
.LP
«\fCmenuposition x y\fR» has the same effect as the «\fCmenuposition=x y\fR» line.  Only
one x y menu position, specified by either method, may occur in a menu
configuration file.
.LP
«\fCiconsize n\fR» has the same effect as the «\fCiconsize=size\fR» line, overrides the
effect of that line, and is overridden by any such following line.
.LP
By default when gtkmenuplus is \fInot\fR launched via a CLI, fatal errors are
displayed in a message box.  «\fCerrorconsoleonly\fR» prevents such message boxes
from appearing. «\fCnoerrorconsoleonly\fR» reverts to the default behaviour.
.SH Onexit
.sp 1
.nf
\fC
onexit=command
\fR
.fi
.LP
Shell command «\fCcommand\fR» is executed after the menu gets deactivated.  onexit is
a hook for a menu script to clean up after the menu ends.
.LP
A script can include «\fConexit=command\fR» multiple times.  Only the last «\fCcommand\fR»
will be executed. Use «\fConexit=\fR» to clear an established «\fCcommand\fR».
.LP
If you need to run multiple shell commands, wrap them in a \(lqsh -c\(rq invocation.
Note that «\fCcommand\fR» is executed regardless of a menu entry being selected, and
it isn\(cqt synchronized with the execution/termination of an item or launcher.
.SH Endsubmenu
.sp 1
.nf
\fC
endsubmenu
\fR
.fi
.LP
Once «\fCendsubmenu\fR» is encountered on a «\fCconfigure=\fR» line, indentation of lines
no longer signals which menu entries belong to which submenu.  Instead
indentation is ignored, and everything after a «\fCsubmenu=\fR» line belongs to that
submenu until the occurrence of an «\fCendsubmenu\fR» line.  Behaviour reverts to
default when «\fCnoendsubmenu\fR» occurs on a subsequent «\fCconfigure=\fR» line.
.LP
Ignoring indentation means that leading whitespace can be used cosmetically,
e.g.  to mark lines within «\fCif=\fR»/«\fCelseif=\fR»/«\fCelse\fR»/«\fCendif\fR» blocks (and of course
to continue to clarify what belongs to which submenu).
.SH Separator
.sp 1
.nf
\fC
separator
\fR
.fi
.LP
It displays a line in the menu.
.LP
A separator marks the end of any menu item or submenu preceding it.
.SH Iconsize
.sp 1
.nf
\fC
iconsize=size
\fR
.fi
.LP
An optional line that changes the dimensions of the image used for succeeding
menu items.  There can be multiple «\fCiconsize=\fR» lines; each one sets the icon
size for all menu entries that follow, until the next «\fCiconsize=\fR» line.
.LP
Size must be between 20 and 200.
.LP
Standard icons are typically 16, 24, 48 or 96 pixels square.
.LP
If no «\fCiconsize=\fR» is in force size will be 30 unless the gtk framework returns
a different size.
.LP
To speed execution, all icon files associated with a menu configuration file
should be of the image size specified by the most recent «\fCiconsize=\fR» line.
.LP
An «\fCiconsize=\fR» line marks the end of any menu item or submenu preceding it.
.LP
You can get the same result by putting «\fCiconsize size\fR» on a «\fCconfigure=\fR» line.
.SH Menupos, Menuposition
.sp 1
.nf
\fC
menupos=x y

menuposition=x y
\fR
.fi
.LP
An optional line to force the menu to open at a given x-y position (the program
xev can help you find coordinates - see its man page).  If no «\fCmenupos=\fR» is
encountered, the menu is shown at the mouse cursor position.  Only one
«\fCmenupos=\fR» is allowed per configuration file.
.LP
An «\fCmenupos=\fR» line marks the end of any menu item or submenu preceding it.
.LP
You can get the same result by putting «\fCmenuposition x y\fR» on a «\fCconfigure=\fR»
line.
.SH Icondirectory
.sp 1
.nf
\fC
icondirectory=path_to_icon_directory
\fR
.fi
.LP
After this line is encountered, in all subsequent «\fCicon=path_to_image_file\fR»
lines, if «\fCpath_to_image_file\fR», doesn\(cqt begin with a tilde or forward slash
it\(cqs assumed to be relative to  «\fCpath_to_icon_directory\fR».
.LP
«\fCpath_to_icon_directory\fR» follows the rules for paths referred to in menu
configuration files (see above). 
.LP
«\fCicondirectory=\fR» followed by no text reverts the base path for icons to the
path in which the configuration file was found (as specified on command line).
.LP
There can be multiple «\fCicondirectory=\fR» lines; each one sets the icon directory
for all menu entries that follow, until the next «\fCicondirectory=\fR» line.
.LP
An «\fCicondirectory=\fR» line marks the end of any menu item or submenu preceding
it.
.SH If, Elseif, Else, Endif, Fi
.sp 1
.nf
\fC
if=condition
elseif=condition or elif=condition
else
endif or fi
\fR
.fi
.LP
«\fCcondition\fR» may be either
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  A reference to an argument following the menu configuration file on the
command line when gtkmenuplus was called, the arguments referred to by the
reference «\fC$1\fR», «\fC$2\fR»,... etc, e.g.
.LP
if= $2  # referring to the third argument on the gtkmenuplus command line
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  A valid command that the shell can execute that produces a value on «\fCstdout\fR».
.RE
.sp 1.0v
.RS
.ti -\w'\(bu  'u
\(bu  A variable previously defined by a previous «\fCvar=\fR» line in the menu
configuration file.
.RE
.LP
In either case the value is expected to be an integer, \(lqyes\(rq, \(lqtrue\(rq, \(lqno\(rq or
\(lqfalse\(rq, all case insensitive.
.LP
If the value (either the result of command execution sent to «\fCstdout\fR» or
received as a parameter) is non-zero, \(lqtrue\(rq or \(lqyes\(rq, the menu entries
following the «\fCif=\fR» up to the following «\fCelse\fR» or «\fCendif\fR» will be displayed.
.LP
If that value is zero, \(lqfalse\(rq or \(lqno\(rq , the menu entries following the «\fCif=\fR»
up to the following «\fCelse\fR» or «\fCendif\fR» will \fInot\fR» be displayed, but any after a
following «\fCelse\fR» line will be.
.LP
An «\fCif=/[elseif=]/[else]endif\fR» block can be embedded within another.
.LP
If «\fCif=$n\fR» or «\fCelseif=$n\fR» lines are read when there are less than «\fCn\fR»
parameters on the gtkmenuplus command line, all lines from the line up to the
matching «\fCelseif\fR» or «\fCendif\fR» will be processed into the menu.
.LP
If you want to test some condition requiring a call to the shell, and you want
to use the same condition in various «\fCif=\fR» lines in your menu configuration
file, you might be best to invoke the shell command within an argument on the
command line; that way the shell needs to be invoked only once, instead of
multiple times for multiple «\fCif=\fR» statements.
.LP
«\fCif=\fR», «\fCelseif=\fR», «\fCelse\fR» and «\fCendif\fR» lines do \fInot\fR» mark the end of any menu
item or submenu preceding it.  So you can have «\fCtooltip=\fR» or «\fCicon=\fR» lines
apply to any of several «\fCitem=\fR»s that might appear conditionally before them
e.g.
.sp 1
.nf
\fC
if= [ \(gadate +%H\(ga -lt 18 ]; printf $?  # if past 18:00 hours
  item = evening game
  cmd = mahjongg
else
 item = daytime game
 cmd = mines
endif
tooltip = the item you see here depends on the time of day
icon=games_package.png
\fR
.fi
.LP
«\fCif=\fR», «\fCelseif=\fR», «\fCelse\fR» and «\fCendif\fR» lines are scoped to each menu
configuration file.  If you «\fCinclude=\fR» a menu configuration file, an «\fCendif\fR»
line must follow an «\fCif=\fR» line within that file, and won\(cqt relate to a «\fCif=\fR»
line  in the including file.
.LP
«\fCerror=message\fR» can be used to stop menu configuration file processing, the
need for which would generally be detected by «\fCif=\fR», «\fCelseif=\fR», «\fCelse\fR» and
«\fCendif\fR» lines.
.LP
Sample conditions in «\fCif=condition\fR», «\fCelseif=condition\fR» or command line
parameters:
.LP
Show menu entries following the if= line only in PM hours:
.sp 1
.nf
\fC
if= ! [ \(gadate +%p\(ga = 'PM' ]; printf $?
\fR
.fi
.LP
On the command line:
.sp 1
.nf
\fC
gtkmenuplus path_to_configuration_file "! [ \(gadate +%p\(ga = 'PM' ]; printf $?"
\fR
.fi
.LP
and then use «\fCif= $1\fR» inside the configuration file.
.LP
The date command can be used to show menu items on certain days of week, days
of the month, week of the year, etc.
.LP
Show menu entries following the «\fCif=\fR» line only if using a particular physical
screen:
.sp 1
.nf
\fC
if= xrandr --current | grep "VGA-0 connected" | wc -l
\fR
.fi
.LP
Show menu entries following the «\fCif=\fR» line only if firefox is running:
.sp 1
.nf
\fC
if= xdotool search --name Firefox  | wc -l
\fR
.fi
.LP
Test if a particular memory stick is mounted:
.sp 1
.nf
\fC
if= ! [ -d '/media/VOL_LABEL'  ]; printf $?
\fR
.fi
.LP
Test if the partition «\fC$HOME\fR» resides on is more than 90% full:
.sp 1
.nf
\fC
if=  df $HOME | awk 'NR==2{split($5,A,/%/);print (A[1]+0>90)}'
\fR
.fi
.SH BUGS
.LP
Please report defects in the \fIIssues\fR page of the gtkmenuplus project home.
.SH AUTHOR
.LP
copyright \(co 2013 Alan Campbell, \(co 2016-2018 step
.LP
step is the current maintainer.
.LP
\fBAcknowledgements\fR
.LP
Thanks to John Vorthman for providing myGtkMenu code.
.LP
The idea of importing .desktop files was borrowed from popdown
.SH SEE ALSO
.LP
gtkmenuplus(1) - usage
.LP
Gtkmenuplus home page and project repository (current version):
.LP
\fIhttps://github.com/step-/gtkmenuplus\fR
.LP
Gtkmenuplus 1.0 home page (old version):
.LP
\fIhttps://sites.google.com/site/entropyreduction/gtkmenuplus\fR
.LP
myGtkMenu home page (old version):
.LP
\fIhttps://sites.google.com/site/jvinla/home\fR
.LP
Popdown home page:
.LP
\fIhttp://www.manatlan.com/page/popdown\fR
