=pod

=head2 NAME

 icewm-menu - icewm menu configuration file

=head2 SYNOPSIS

 $ICEWM_PRIVCFG/menu
 $XDG_CONFIG_HOME/icewm/menu
 $HOME/.icewm/menu
 /etc/icewm/menu
 /usr/share/icewm/menu

=head2 DESCRIPTION

The F<menu> file is responsible for configuring most of the L<icewm(1)>
root menu and the start menu.

A menu that gives access to applications; usually customized by the user.
The L<icewm-menu-fdo(1)> program generates a default menu
that contains most of the systems desktop applications.
Similar programs are L<xdg_menu(1)>, L<mmaker(1)>,
L<xde-menu(1)> and L<xdgmenumaker(1)>.

=head2 FORMAT

The file contains lines with the following syntax:

=over

=item B<prog> B<">I<title>B<"> I<icon> I<program> I<options>

Specifies a program to execute when the menu item is selected.

=item B<restart> B<">I<title>B<"> I<icon> I<program> I<options>

Specifies a program to replace the window manager when the menu item is
selected.  This is for launching other window managers from within
L<icewm(1)>.

=item B<runonce> B<">I<title>B<"> I<icon> B<">[I<name>][B<.>I<class>]B<"> I<program> I<options>

Specifies a program to execute when the menu item is selected; however,
if a window of the specified I<name> and I<class> is present,
the program will not be run again.

=item B<menu> B<">I<title>B<"> I<icon> B<{>
 # contained items
 B<}>

Specifies a sub-menu.  The lines that appear between the braces can be
any menu item described here.

=item B<menufile> B<">I<title>B<"> I<icon> B<">I<filename>B<">

Specifies a file from which to collect sub-menu items (lines) and place
them at this point in the menu.

=item B<menuprog> B<">I<title>B<"> I<icon> I<program> I<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.

=item B<menuprogreload> B<">I<title>B<"> I<icon> I<timeout>
I<program> I<options>

Similar to B<menuprog>, but after at least I<timeout> seconds
the menu is regenerated.

=item B<include> B<">I<filename>B<">

Read additional entries from the file I<filename>

=item B<includeprog> I<program> I<options>

Read additional entries from the output of I<program> I<options>.

=item B<separator>

A separator for menu items.

=back

Where

=over

=item B<prog>, B<restart>, B<runonce>, B<menu>, B<menufile>,
B<menuprog>, B<menuprogreload>, B<include>, B<includeprog>, B<separator>

These are literal string keywords.

=item B<">I<title>B<">

This is the I<title> string associated with the menu item that is
displayed in the menu.  When the I<title> contains spaces, the title
must be surrounded by double quotes (C<>).

=item I<icon>

Is the name of the icon file (with or without extension) or the full
path to an icon file.

=item B<">[I<name>][B<.>I<class>]B<">

I<name> is the resource name of a window launched by I<program> and
I<class> is the resource class of the window.  Only one of
I<name> or I<class> need be specified.  This is used to determine
whether the program is already running and is used with the
B<runonce> keyword.

=item I<program> I<options>

I<program> 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 B<menuprog> keyword, the I<program> must print on
standard output the contents of the menu and is used for dynamic menus.

I<options> are the options and arguments passed to the I<program>
verbatim.

=item I<filename>

I<filename> is the name of the file relative to one of the L<icewm(1)>
configuration directories, or the full path to a file.  The file is used
with the B<menufile> keyword and specifies the file from which to read
further menu items.

=back

=head2 EXAMPLES

Following is the example F<menu> file that ships with L<icewm(1)>:

 # This is an example for IceWM's menu definition file.
 #
 # Place your variants in @CFGDIR@ 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

=head2 FILES

Locations for the F<menu> file are as follows:

 $ICEWM_PRIVCFG/menu
 $XDG_CONFIG_HOME/icewm/menu
 $HOME/.icewm/menu
 /etc/icewm/menu
 /usr/share/icewm/menu

The locations are searched in the order listed; the first file found is
read and the remainder ignored.

=head2 SEE ALSO

L<icewm(1)>,
L<icewm-menu-fdo(1)>.

=head2 AUTHOR

Brian Bidulock L<mailto:bidulock@openss7.org>.

=head2 LICENSE

B<IceWM> is licensed under the GNU Library General Public License.
See the F<COPYING> file in the distribution.

=cut

# vim: set sw=4 tw=72 nocin spell spelllang=en_ca:
