.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ICEWM-MENU 5"
.TH ICEWM-MENU 5 2024-05-20 "icewm 3.5.0" "Standards, Environments and Macros"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SS NAME
.IX Subsection "NAME"
.Vb 1
\& icewm\-menu \- icewm menu configuration file
.Ve
.SS SYNOPSIS
.IX Subsection "SYNOPSIS"
.Vb 5
\& $ICEWM_PRIVCFG/menu
\& $XDG_CONFIG_HOME/icewm/menu
\& $HOME/.icewm/menu
\& /etc/icewm/menu
\& /usr/share/icewm/menu
.Ve
.SS DESCRIPTION
.IX Subsection "DESCRIPTION"
The \fImenu\fR file is responsible for configuring most of the \fBicewm\fR\|(1)
root menu and start menu.
.PP
A menu of applications; usually customized by the user.  \fBicewm\fR
provides the \fBicewm\-menu\-fdo\fR\|(1) program to generate a default menu.
Similar programs are \fBxdg_menu\fR\|(1), \fBmmaker\fR\|(1) (MenuMaker),
\&\fBxde\-menu\fR\|(1), \fBxdgmenumaker\fR\|(1).
.SS FORMAT
.IX Subsection "FORMAT"
The file contains lines with the following syntax:
.IP "\fBprog\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4
.IX Item "prog [""]title[""] icon program options"
Specifies a program to execute when the menu item is selected.
.IP "\fBrestart\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4
.IX Item "restart [""]title[""] icon program options"
Specifies a program to replace the window manager when the menu item is
selected.  This is for launching other window managers from within
\&\fBicewm\fR\|(1).
.IP "\fBrunonce\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fB""\fR[\fIres_name\fR][\fB.\fR\fIres_class\fR]\fB""\fR \fIprogram\fR \fIoptions\fR" 4
.IX Item "runonce [""]title[""] icon ""[res_name][.res_class]"" program options"
Specifies a program to execute when the menu item is selected; however,
if a window of the specified \fIres_name\fR and \fIres_class\fR is present,
the program will not be run again.
.IP "\fBmenu\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fB{\fR # contained items \fB}\fR" 4
.IX Item "menu [""]title[""] icon { # contained items }"
Specifies a sub-menu.  The lines that appear between the braces can be
any menu item described here.
.IP "\fBmenufile\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR [\fB""\fR]\fIfilename\fR[\fB""\fR]" 4
.IX Item "menufile [""]title[""] icon [""]filename[""]"
Specifies a file from which to collect sub-menu items (lines) and place
them at this point in the menu.
.IP "\fBmenuprog\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4
.IX Item "menuprog [""]title[""] icon program options"
Specifies a program that will print sub-menu items on standard output,
which will be collected and placed in the sub-menu at this point.
.IP "\fBmenuprogreload\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fItimeout\fR \fIprogram\fR \fIoptions\fR" 4
.IX Item "menuprogreload [""]title[""] icon timeout program options"
Similar to \fBmenuprog\fR, but after at least \fItimeout\fR seconds
the menu is regenerated.
.IP "\fBinclude\fR [\fB""\fR]\fIfilename\fR[\fB""\fR]" 4
.IX Item "include [""]filename[""]"
Read additional entries from the file \fIfilename\fR
.IP "\fBincludeprog\fR \fIprogram\fR \fIoptions\fR" 4
.IX Item "includeprog program options"
Read additional entries from the output of \fIprogram\fR \fIoptions\fR.
.IP \fBseparator\fR 4
.IX Item "separator"
A separator for menu items.
.PP
Where
.IP "\fBprog\fR, \fBrestart\fR, \fBrunonce\fR, \fBmenu\fR, \fBmenufile\fR, \fBmenuprog\fR, \fBmenuprogreload\fR, \fBinclude\fR, \fBincludeprog\fR, \fBseparator\fR" 4
.IX Item "prog, restart, runonce, menu, menufile, menuprog, menuprogreload, include, includeprog, separator"
These are literal string keywords.
.IP "[\fB""\fR]\fItitle\fR[\fB""\fR]" 4
.IX Item "[""]title[""]"
This is the \fItitle\fR string associated with the menu item that is
displayed in the menu.  When the \fItitle\fR contains spaces, the title
must be surrounded by double quotes (\f(CW\*(C`\*(C'\fR).
.IP \fIicon\fR 4
.IX Item "icon"
Is the name of the icon file (with or without extension) or the full
path to an icon file.
.IP "\fB""\fR[\fIres_name\fR][\fB.\fR\fIres_class\fR]\fB""\fR" 4
.IX Item """[res_name][.res_class]"""
\&\fIres_name\fR is the resource name of a window launched by \fIprogram\fR and
\&\fIres_class\fR is the resource class of the window.  Only one of
\&\fIres_name\fR or \fIres_class\fR need be specified.  This is used to identify
whether the program is already running and is for use with the
\&\fBrunonce\fR keyword.
.IP "\fIprogram\fR \fIoptions\fR" 4
.IX Item "program options"
\&\fIprogram\fR is the name of the executable or full path to the executable
file that will be run in response to selecting the menu item.
When used with the \fBmenuprog\fR keyword, the \fIprogram\fR must print on
standard output the contents of the menu and is used for dynamic menus.
.Sp
\&\fIoptions\fR are the options and arguments passed to the \fIprogram\fR
verbatim.
.IP \fIfilename\fR 4
.IX Item "filename"
\&\fIfilename\fR is the name of the file relative to one of the \fBicewm\fR\|(1)
configuration directories, or the full path to a file.  The file is used
with the \fBmenufile\fR keyword and specifies the file from which to read
further menu items.
.SS EXAMPLES
.IX Subsection "EXAMPLES"
Following is the example \fImenu\fR file that ships with \fBicewm\fR\|(1):
.PP
.Vb 10
\& # This is an example for IceWM\*(Aqs menu definition file.
\& #
\& # Place your variants in /etc/icewm or in $HOME/.icewm
\& # since modifications to this file will be discarded when you
\& # (re)install icewm.
\& #
\& prog xterm xterm xterm
\& prog rxvt xterm rxvt \-bg black \-cr green \-fg white \-C \-fn 9x15 \-sl 500
\& prog fte fte fte
\& prog NEdit nedit nedit
\& prog Mozilla mozilla mozilla
\& prog XChat xchat xchat
\& prog Gimp gimp gimp
\& separator
\& menuprog "Desktop Apps" folder icewm\-menu\-fdo
\& menufile Programs folder programs
\& menufile Tool_bar folder toolbar
.Ve
.SS FILES
.IX Subsection "FILES"
Locations for the \fImenu\fR file are as follows:
.PP
.Vb 5
\& $ICEWM_PRIVCFG/menu
\& $XDG_CONFIG_HOME/icewm/menu
\& $HOME/.icewm/menu
\& /etc/icewm/menu
\& /usr/share/icewm/menu
.Ve
.PP
The locations are searched in the order listed; the first file found is
read and the remainder ignored.
.SS "SEE ALSO"
.IX Subsection "SEE ALSO"
\&\fBicewm\fR\|(1),
\&\fBicewm\-menu\-fdo\fR\|(1).
.SS AUTHOR
.IX Subsection "AUTHOR"
Brian Bidulock <mailto:bidulock@openss7.org>.
.SS LICENSE
.IX Subsection "LICENSE"
\&\fBIceWM\fR is licensed under the GNU Library General Public License.
See the \fICOPYING\fR file in the distribution.