j4-dmenu-desktop.1

.Dd $Mdocdate: January 10 2024$
.Dt J4-DMENU-DESKTOP 1
.Os
.Sh NAME
.Nm j4-dmenu-desktop
.Nd fast desktop menu
.Sh SYNOPSIS
.Nm
.Op OPTIONS
.Sh DESCRIPTION
.Nm
is a faster replacement for i3-dmenu-desktop.
.Pp
It's purpose is to find .desktop files and offer you a menu to start an
application using dmenu.
.Pp
The arguments are as follows:
.Bl -tag -width Ds
.It Fl b , Fl Fl display-binary
Display binary name after each entry (off by default).
.It Fl f , Fl Fl display-binary-base
Display basename of binary name after each entry (off by default).
.It Fl d , Fl Fl dmenu Ar command
Determines the command used to invoke dmenu.
Executed with your shell
.Pq Ev $SHELL
or
.Pa /bin/sh .
.It Fl Fl no-exec
Do not execute selected command, send to stdout instead.
.It Fl Fl no-generic
Do not include the generic name of desktop entries.
.It Fl t , Fl Fl term Ar command
Sets the terminal emulator used to start terminal apps.
.It Fl Fl term-mode Ar mode
Instruct
.Nm
on how it should execute terminal emulator.
This flag also changes the default value of
.Fl Fl term
flag.
.Pp
Possible values are:
.Cm default | xterm | alacritty | kitty | terminator | gnome-terminal | custom
.Pp
See
.Sx TERM MODE
for more info.
.It Fl Fl usage-log Ar file
Must point to a read-writeable file (will create if not exists). In this mode
entries are sorted by usage frequency.
.It Fl Fl prune-bad-usage-log-entries
Remove names marked in usage log for which
.Nm
was unable to find a desktop file.
This can happen when an app marked in usage log no longer exists because it was
uninstalled.
.It Fl x , Fl Fl use-xdg-de
Enables reading
.Ev $XDG_CURRENT_DESKTOP
to determine the desktop environment.
.It Fl Fl wait-on Ar path
Must point to a path where a file can be created.
In this mode no menu will be shown.
Instead the program waits for
.Ar path
to be written to
.Po
use
.Ql echo > path
.Pc .
Every time this happens a menu will be shown.
Desktop files are parsed ahead of time.
Performing
.Ql echo -n q > path
will exit the program.
.It Fl Fl wrapper Ar wrapper
A wrapper binary.
Usage of
.Ql --wrapper Qq i3 exec
and
.Ql --wrapper Qq sway exec
is deprecated, use
.Fl Fl i3-ipc
instead.
.It Fl I , Fl Fl i3-ipc
Execute desktop entries through i3 IPC or Sway IPC.
Requires either i3 or Sway to be running.
.It Fl Fl skip-i3-exec-check
Disable the check for
.Fl Fl wrapper Qq i3 exec
or
.Fl Fl wrapper Qq sway exec .
j4-dmenu-desktop has direct support for i3/Sway through the
.Fl I
flag which should be used instead of the
.Fl Fl wrapper
option. j4-dmenu-desktop detects this and exits.
This flag overrides this behaviour.
.It Fl i , Fl Fl case-insensitive
Sort applications case insensitively
.It Fl v
Be more verbose.
When specified once,
.Cm INFO
is used, when twice,
.Cm DEBUG
is used.
See
.Sx LOG LEVELS .
.It Fl Fl log-level Ar ERROR | WARNING | INFO | DEBUG
A more explicit version of
.Fl v .
This flag takes precedence over
.Fl v .
.It Fl Fl log-file Ar file
Specify a log file.
.Ar file
will be truncated.
By default, the
.Cm INFO
loglevel is used.
.It Fl Fl log-file-level Ar ERROR | WARNING | INFO | DEBUG
Set file log level.
.It Fl Fl desktop-file-quirks Ar ARGS
Modify
.Nm j4-dmenu-desktop's
desktop file parsing mechanism to accomodate desktop files not conforming to the
Desktop Entry Specification.
Several modes may be specified.
They shall be separated by a comma (,).
All modes not specified in
.Fl Fl desktop-file-quirks
are disabled.
To disable all modes, use
.Fl Fl strict-parsing .
A warning is printed when a desktop file makes use of an enabled quirk.
.Ar ARGS
can contain the following modes:
.Bl -tag -width Ds
.It Ar wine
Tolerate invalid escape codes
.Pq such as escaping a space to disable separating arguments
in the
.Cm Exec
key of desktop files.
Enabled by default.
.It Ar multispace
Tolerate the usage of several spaces to separate arguments in the
.Cm Exec
key of desktop files.
Useful for desktop files generated by distrobox.
Enabled by default.
.El
.Pp
This flag is mutaly exclusive with
.Fl Fl strict-parsing .
.Pp
Modes enabled by default may be subject to change in future versions of
.Nm .
.Pp
.\" TODO
.Em This interface is work in progress.
.It Fl Fl strict-parsing
Strictly adhere to the Desktop Entry Specification while parsing desktop files.
Not enabled by default.
.Pp
This flag is mutaly exclusive with
.Fl Fl desktop-file-quirks .
.It Fl Fl version
Display program version.
.It Fl h , Fl Fl help
Display help message.
.El
.Ss LOG LEVELS
Some arguments support setting the log level.
.Nm
uses the following log levels:
.Cm ERROR , WARNING , INFO
and
.Cm DEBUG .
The
.Cm WARNING
(and
.Cm ERROR )
loglevels are displayed by default.
Lower loglevels automatically enable higher ones.
.Ss TERM MODE
There are several modes available for the
.Fl Fl term-mode
flag:
.Bl -tag -width Ds
.It Cm default
The default mode.
A temporary shell script is created containing the chosen command.
The script deletes itself upon execution,
.Nm
never deletes it itself.
It sets the title of terminal emulator using OSC escape sequences
.Pq see Xr console_codes 4 .
Terminal emulator is executed as follows:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl e Bo Cm generated\ temporary\ script Bc
.Pp
Other modes should be preferred.
This approach is universal but fragile.
.Pp
Default value of
.Fl Fl term
is
.Ic i3-sensible-terminal .
.It Cm xterm
Use
.Ic xterm
calling convention:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl title Bo Cm desktop\ app\ Name Bc Fl e \
Bo Cm command\ line Bc
.Pp
Default value of
.Fl Fl term
is
.Ic xterm .
Other compatible terminal emulators include:
.Ic rxvt-unicode .
.It Cm alacritty
Use
.Ic alacritty
calling convention:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl T Bo Cm desktop\ app\ Name Bc Fl e \
Bo Cm command\ line Bc
.Pp
Default value of
.Fl Fl term
is
.Ic alacritty .
Other compatible terminal emulators include:
.Ic st , foot .
.It Cm kitty
Use
.Ic kitty
calling convention:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl T Bo Cm desktop\ app\ Name Bc\
 Bo Cm command\ line Bc
.Pp
Default value of
.Fl Fl term
is
.Ic kitty .
Other compatible terminal emulators include:
.Ic foot .
.It Cm terminator
Use
.Ic terminator
calling convention:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl T Bo Cm desktop\ app\ Name Bc\
 Fl x Bo Cm command\ line Bc
.Pp
Default value of
.Fl Fl term
is
.Ic terminator .
Other compatible terminal emulators include:
.Ic xfce4-terminal .
.It Cm gnome-terminal
Use
.Ic gnome-terminal
calling convention:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl Fl title Bo Cm desktop\ app\ Name Bc Fl \- \
Bo Cm command\ line Bc
.Pp
Default value of
.Fl Fl term
is
.Ic gnome-terminal .
.It Cm custom
Allow for completely custom handling of
.Fl Fl term .
When
.Fl Fl term-mode Cm custom
is passed, an alternative system for handling
.Fl Fl term
is used.
It is handled as a list of arguments separated by space
.Pq " " .
No other whitespace characters act as an argument separator (this behavior
differs from the shell).
.Pp
Multiple consecutive space characters will be treated as a single space (except
for escaped spaces).
Leading and trailing spaces in
.Fl Fl term
will be ignored.
This means that it is
.Em not
possible to pass zero-length arguments to
.Fl Fl term .
.Pp
The contents of
.Fl Fl term
are
.Em not
executed through a shell.
This means that shell constructs like redirection,
.Ic &&
and
.Ic ||
chaining and more will not work.
If you need this, you can either create a wrapper shell script and call it from
.Fl Fl term
or you can call
.Cm /bin/sh -c
or some other shell directly from
.Fl Fl term
(although using a wrapper script should be preferred, because it is clearer and
simpler to use).
.Pp
The following placeholders are recognised:
.Bl -tag -width indent-two
.It Brq Ic name
Name of desktop app.
Useful for setting the title.
.It Brq Ic cmdline@
Command line to be executed expanded as separate arguments.
This must be an independent argument;
.Ql Cm j4-dmenu-desktop Fl Fl term-mode Cm custom Fl Fl term Qq Fl e= Ns Brq cmdline@
is invalid.
.It Brq Ic cmdline*
Command line to be executed expanded as a single argument.
.Brq Ic cmdline@
should be preferred.
Arguments will be escaped; Contents of
.Brq Ic cmdline*
can be passed to
.Cm /bin/sh -c
safely.
.It Brq Ic script
Filename of a script generated by
.Nm .
This is the same script used by
.Fl Fl term-mode Cm default .
The script will be generated only if this placeholder is specified at least once
in
.Fl Fl term .
The script sets terminal title itself, it souldn't be necessary to set it
manually.
.Pp
.Brq Ic cmdline@
and
.Brq Ic cmdline*
should be preferred over
.Brq Ic script .
.El
.Pp
The following escape sequences are recognised:
.Bl -tag -width indent-two
.It Sy \e\e
Literal
.Sy \e
character.
.It Sy \e{
Literal
.Sy {
character.
.It Sy \e\  Ns
.Pq backslash with space
Do not handle the following space as an argument separator.
.El
.Pp
Undefined escape sequences and placeholders will result in an error message and
program termination.
.Pp
Default value of
.Fl Fl term
is same as of
.Cm default
term mode.
.Pp
.\" The following list should be in sync with pytest testsuite!
.\" =========================================================
This is how other modes look when written using
.Cm custom
mode:
.Bl -hang -width indent-two
.It Cm default
.Ql j4-dmenu-desktop --term-mode custom --term Qq i3-sensible-terminal -e Brq\
 script
.It Cm xterm
.Ql j4-dmenu-desktop --term-mode custom --term Qq xterm -title Bro name Brc\
 -e Brq cmdline@
.It Cm alacritty
.Ql j4-dmenu-desktop --term-mode custom --term Qq alacritty -T Bro name Brc\
 -e Brq cmdline@
.It Cm kitty
.Ql j4-dmenu-desktop --term-mode custom --term Qq kitty -T Bro name Brc Brq\
 cmdline@
.It Cm terminator
.Ql j4-dmenu-desktop --term-mode custom --term Qq terminator -T Bro name Brc\
 -x Brq cmdline@
.It Cm gnome-terminal
.Ql j4-dmenu-desktop --term-mode custom --term Qq gnome-terminal --title Bro\
 name Brc -- Brq cmdline@
.El
.Pp
This is how the deprecated -e flag of gnome-terminal could be used:
.Pp
.Dl j4-dmenu-desktop --term-mode custom --term Qq gnome-terminal --title Bro name Brc -e Brq cmdline*
.Pp
This is how placeholders can be escaped:
.Pp
.Dl j4-dmenu-desktop --term-mode custom --term Qq echo \e Ns Bro name Brc Ns \e \e Ns Brq cmdline*
.Pp
.Fl Fl term
receives two arguments:
.Ql echo
and
.Ql Bro name Brc Brq cmdline* ,
no placeholders are replaced.
.Nm
would see three arguments instead of two if the second
.Sy \e
had not been passed.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev I3SOCK
This variable overwrites the i3/Sway IPC socket path.
.It Ev XDG_DATA_HOME
Primary directory containing desktop files.
.It Ev XDG_DATA_DIRS
Additional directories containing desktop files.
.It Ev XDG_CURRENT_DESKTOP
Current desktop environment used for enabling/disabling desktop environemnt
dependent desktop files.
Must be enabled by
.Fl Fl use-xdg-de .
.El
.Pp
Standard environmental variables for locales are acknowledged in addition to
those listed above.
The exact environmental variables used are implementation-dependent, but setting
.Ev LC_MESSAGES , LC_ALL
or
.Ev LANG
should generally work.
.Sh SEE ALSO
.Lk https://github.com/enkore/j4-dmenu-desktop
.Sh COPYRIGHT
Copyright (C) 2013 enkore
.Eo < Mt public+j4-dmenu-desktop@enkore.de Ec >
.Pp
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
.Pp
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.Pp
You should have received a copy of the GNU General Public License along with
this program.
If not, see
.Eo < Lk http://www.gnu.org/licenses/ Ec > .