xdg-xmenu.1

.TH XDG-XMENU 1 "Jun 2023" VERSION

.SH NAME
xdg-xmenu - show app menu using
.IR xmenu (1)

.SH SYNOPSIS
.B xdg-xmenu
.RB [ -dGIn ]
.RB [ -b
.IR fallback_icon ]
.RB [ -i
.IR icon_theme ]
.RB [ -s
.IR icon_size ]
.RB [ -S
.IR scale ]
.RB [ -t
.IR terminal ]
.RB [ -x
.IR xmenu_cmd ]
.RB [ --
.IR <xmenu_options> ]

.SH DESCRIPTION
.B xdg-xmenu
is a small program that shows an app menu using
.IR xmenu (1).
It tries to follow the specifications of desktop entries and icon themes
provided by freedesktop:
.IP
https://specifications.freedesktop.org/desktop-entry-spec
.IP
https://specifications.freedesktop.org/icon-theme-spec
.P
.B xdg-xmenu
also has the potential to generate menu for other general-purpose
menu utilities.

.SH OPTIONS
.TP
.BI -b " fallback_icon"
Fallback icon in case one can not be found.
Accept either an icon name or a file path.
Default is application-x-executable.
.TP
.B -d
Print the menu to stdout and exit, do not run
.IR xmenu (1)
command.
.TP
.B -G
Do not show app's generic names.
.TP
.BI -i " icon_theme"
Icon theme.
Default value is parsed from gtk3 configuration file.
Fallback to "hicolor" if none are found.
.TP
.B -I
Disable icons. This implies an '-i' option passed to
.IR xmenu (1)
, which also disables icons display
to make it loading faster.
.TP
.B -n
Dry run mode. Do not run the selected app. Instead, the selection will be
printed to stdout, as in the behavior of vanilla xmenu.
.TP
.BI -s " icon_size"
Icon size. This is used when searching for icon files. It's not xmenu's display
size. Default is 24.
.TP
.BI -S " scale"
Scale of icons. Useful in HiDPI screens. For example, 24x24@2x icons looks like
24x24 icons, but with sharper details. While 48x48 icons is at the same
resolution, but possibly with more details.
.TP
.BI -t " terminal"
Terminal emulator to use. Default is xterm.
.TP
.BI -x " xmenu_cmd"
Alternative xmenu command to use, default is xmenu. This is only the
executable, extra command should be passed after `--', see below.
.TP
.B --
Everything after `--' are passed to `xmenu_cmd' command.

.SH EXAMPLES
.P
The -x and -- two options provides infinite possiblity, although not so useful
for now. There is a redundant example equivlant to `xdg-xmenu -I':
.IP
xdg-xmenu -I -x xmenu -- -i
.P
This disables both icons in
.B xdg-xmenu
and
.IR xmenu (1).

.SH RESOURCES
.SS Desktop Files
The script will go through the .desktop files in the following directories:
.IP
$XDG_DATA_DIRS/applications
.IP
$XDG_DATA_HOME/applications
.P
This covers the cases like flatpak, where the flatpak-specific folders
will be appended to the XDG_DATA_DIRS environment variable (by flatpak).
So this program can find them, too.
.SS Icon Files
.B
xdg-xmenu
will find the icons in the following directories (loosely
following the method in the freedesktop.org specification):
.IP
$XDG_DATA_DIRS/icons
.IP
$XDG_DATA_HOME/icons

.SH HISTORY
.P
This program started out to be a shell script. But since the speed was quite
slow (~500ms), the user could only export the menu file, and feed it to xmenu.
.P
Then I wrote a python version of this program. Although python itself is fast
enough, but the startup time takes up majority of the execution time (~50ms).
.P
Finally, I decided to write a C version, even though I am not that fluent in C.
It shouldn't be hard to do, since it mostly involves text processing and file
searching. Finally, with about double the lines of code (SLOC), this version
works quite well and fast. The average time is about 10ms on my machine. The
bottleneck is now file access.

.SH BUGS
The implementation does not cover everything in the freedesktop specifications.
For example the complicated icon search algorithm, and recursive app folder.
So it is possible that a desktop entry is parsed incorrectly or an icon is not
found. However in my own experience, it is better than most menu utilities.
.P
Report any bugs at
.IR https://github.com/xlucn/xdg-xmenu/issues

.SH AUTHOR

Lu Xu <oliver_lew at outlook dot com>

.SH SEE ALSO
.IR xmenu (1)