=pod

=head2 NAME

 icewm-menu-fdo - menu generator for .desktop files

=head2 SYNOPSIS

B<icewm-menu-fdo> [I<OPTIONS>] [I<FILENAME>]

=head2 DESCRIPTION

B<icewm-menu-fdo> generates a menu for the B<IceWM> window manager
from XDG menu descriptors (aka FreeDesktop.Org F<.desktop> files).
By including this in the L<icewm-menu(1)>, the system applications
become available in the icewm start menu.

=head2 ARGUMENTS

=over

=item [I<FILENAME>]

The optional I<FILENAME> argument is the location of a F<.desktop> file.
When given, B<icewm-menu-fdo> launches the application using the C<Exec>
line from the desktop file.

=back

=head2 OPTIONS

=over

=item B<-g>, B<--generic>

Include the generic name in parentheses in the title of B<prog> entries.

=item B<--seps>

Print a leading and a trailing separator.

=item B<--sep-before>

Print a leading separator.

=item B<--sep-after>

Print a trailing separator.

=item B<--no-sub-cats>

Don't nest subcategories in submenus. The correctness of the
pigeonholing depends on correct application description which shall
always specify a main category. Incorrectly tagged descriptions will be
sorted into the C<Other> menu.

=item B<-o>, B<--output=FILE>

Write the output to I<FILE>.

=item B<-t>, B<--terminal=NAME>

Use I<NAME> to start a terminal emulator that supports the '-e' option.

=item B<-s>, B<--no-lone-app>

Attempt to detect a single application with no other content in lower
submenus and move this one to the parent submenu. This also detects
menus with just one submenu inside, attempting to move it's application
items to the parent menu where possible.

=item B<-S>, B<--no-lone-hint>

Decorate app entries moved by the B<-s> option with a hint about the
original menu where it would be displayed otherwise. Implies B<-s>.

=item B<-d TIMEOUT>, B<--deadline-apps=TIMEOUT>

Specifies a certain timeout value in milliseconds, so that the reading
of *.desktop files (for applications) is aborted by that time (or soon
after). This can help to avoid extended blocking of the caller.
Also see B<-D> for the subsequent operation.

=item B<-D TIMEOUT>, B<--deadline-all=TIMEOUT>

Specifies a total timeout in milliseconds after which the application
has to terminate, regardless of the final menu construction and
decoration reading (applied after *.desktop file reading) was finished
or not. This would cause a printing of menu contents which were
calculated so far, therefore the timeout should be set a certain time
before the actual hard deadline by which the program should be
terminated. The output may lack translations and icons.

=item B<-l LANGUAGE>, B<--lang=LANGUAGE>

Instead of the environment variable C<LANG> use LANGUAGE for the locale.

=item B<-L MAX>, B<--limit-max-len=MAX>

Cut the calculated program titles (after translation and adding
hints, see C<-C> and C<-g>) at C<MAX> characters, followed by an
ellipsis. This can help to restrict the width of the menus in cases
where some entry length might get out of hand.

=item B<--flat>

Display apps from all categories in one level with the title containing
the category information as prefix.

=item B<-F sep>, B<--flat-sep=sep>

When used with C<--flat>, the specified character sequence is used as
separator between the section titles.

=item B<-m filter>, B<--match=filter>

Specifies a filter to show only apps that contain this as substring
within their title.

=item B<-M filter>, B<--imatch=filter>

Like C<--match> but applied with any letter case. Might deliver
incorrect results with some locale settings.

=item B<--match-sec>

Apply the filter from C<--match> or C<--imatch> to both, apps and
section titles.

=item B<--match-osec>

Apply the filter from C<--match> or C<--imatch> to only to section titles.

=item B<-h>, B<--help>

Print a brief usage statement to F<stdout> and exit.

=item B<-V>, B<--version>

Print the program version to F<stdout> and exit.

=item B<-C>, B<--copying>

Print copying permissions to F<stdout> for the program and exit.

=back

=head2 USAGE

This utility is not normally used directly. It is used as the
executable in a B<menuprog> entry in a L<icewm-menu(5)>.

=head2 EXAMPLES

The following line in a L<icewm-menu(5)> file will dynamically generate
a comprehensive set of menus for easy access to F<.desktop> files, added
in a submenu called C<Desktop Apps>.

    menuprog "Desktop Apps" folder icewm-menu-fdo

It can also be embedded directly into the loading menu like in the
following example. There could be a separator line added before or after
(or both) in case where the program could generate useful content.

    includeprog icewm-menu-fdo --seps

=head2 ENVIRONMENT

B<XDG_DATA_HOME> or B<XDG_DATA_DIRS> are considered as suggested by XDG
Base Directory Specification.

B<TERMINAL> may define a terminal emulator that supports the '-e'
option. The option is ignored if the specified command could not be
found and a default is used instead.

=head2 CONFORMING TO

B<icewm-menu-fdo> complies roughly to the XDG F<.desktop> file and menu
specification, see L<Desktop Entry Specification> (Date: 2020-04-27,
Version: Version 1.5) and L<Desktop Menu Specification> (Date: 20 August
2016, Version: Version 1.1).

=head2 CAVEATS

The B<icewm-menu-fdo> program is only built when the L<icewm(1)> package
is configured with the B<--enable-menus-fdo> option and only works with
B<--enable-i18n> option.

Integration of XDG menu files is somewhat of varying quality, heavily
depending on the correctness of metadata like translations and sections
(menu category) hints.

=head2 SEE ALSO

L<Base Directory Specification|https://www.freedesktop.org/wiki/Specifications/basedir-spec/>,
L<Desktop Entry Specification|https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/>,
L<Desktop Menu Specification|https://www.freedesktop.org/wiki/Specifications/menu-spec/>,
L<icewm(1)>,
L<icewm-menu(5)>,
L<icewm-preferences(5)>,
L<icewm-programs(5)>.

=head2 BUGS

Please report bugs at L<https://github.com/ice-wm/icewm/issues>.

=head2 AUTHOR

Eduard Bloch L<mailto:edi@gmx.de>.

See B<--copying> for full copyright notice and copying permissions.

=head2 LICENSE

B<IceWM> is licensed under the GNU Library General Public License.
See the F<COPYING> file in the distribution or use the B<--copying> flag
to display copying permissions.

=cut

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