=pod

=head1 NAME

 icewm-menu - icewm menu configuration file

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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

A menu of applications; usually customized by the user.  B<icewm>
provides the L<icewm-menu-fdo(1)> program to generate a default menu.
Similar programs are L<xdg_menu(1)>, L<mmaker(1)> (MenuMaker),
L<xde-menu(1)>, L<xdgmenumaker(1)>.

=head1 FORMAT

The format of the file contains one of the following line 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<res_name>][B<.>I<res_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<res_name> and I<res_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
and 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 which is
displayed in the menu.  When the I<title> contains spaces, the title
must be surrounded by double quotes (C<">), although the I<title> may
always be surrounded by double quotes if preferred.

=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<res_name>][B<.>I<res_class>]B<">

I<res_name> is the resource name of a window launched by I<program> and
I<res_class> is the resource class of the window.  Only one of
I<res_name> or I<res_class> need be specified.  This is used to identify
whether the program is already running and is for use 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> is 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

=head1 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

=head1 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.

=head1 SEE ALSO

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

=head1 AUTHOR

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

=head1 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:
