Ubuntu Manpage: j4-dmenu-desktop

Provided by: j4-dmenu-desktop_3.2-1build1_amd64

NAME

       j4-dmenu-desktop — fast desktop menu

SYNOPSIS

       j4-dmenu-desktop [OPTIONS]

DESCRIPTION

j4-dmenu-desktop is a faster replacement for i3-dmenu-desktop.

It's purpose is to find .desktop files and offer you a menu to start an application using dmenu.

The arguments are as follows:

-b, --display-binary
Display binary name after each entry (off by default).

-f, --display-binary-base
Display basename of binary name after each entry (off by default).

-d, --dmenu command
Determines the command used to invoke dmenu. Executed with your shell ($SHELL) or /bin/sh.

--no-exec
Do not execute selected command, send to stdout instead.

--no-generic
Do not include the generic name of desktop entries.

-t, --term command
Sets the terminal emulator used to start terminal apps.

--term-mode mode
Instruct j4-dmenu-desktop on how it should execute terminal emulator. This flag also changes the
default value of --term flag.

See “TERM MODE” for more info.

--usage-log file
Must point to a read-writeable file (will create if not exists). In this mode entries are sorted
by usage frequency.

--prune-bad-usage-log-entries
Remove names marked in usage log for which j4-dmenu-desktop was unable to find a desktop file.
This can happen when an app marked in usage log no longer exists because it was uninstalled.

-x, --use-xdg-de
Enables reading $XDG_CURRENT_DESKTOP to determine the desktop environment.

--wait-on 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 path to be written to (use ‘echo > path’). Every time this happens a menu
will be shown. Desktop files are parsed ahead of time. Performing ‘echo -n q > path’ will exit
the program.

--wrapper wrapper
A wrapper binary. Usage of ‘--wrapper "i3 exec"’ and ‘--wrapper "sway exec"’ is deprecated, use
--i3-ipc instead.

-I, --i3-ipc
Execute desktop entries through i3 IPC or Sway IPC. Requires either i3 or Sway to be running.

--skip-i3-exec-check
Disable the check for --wrapper "i3 exec" or --wrapper "sway exec". j4-dmenu-desktop has direct
support for i3/Sway through the -I flag which should be used instead of the --wrapper option.
j4-dmenu-desktop detects this and exits. This flag overrides this behaviour.

-i, --case-insensitive
Sort applications case insensitively

-v Be more verbose. When specified once, INFO is used, when twice, DEBUG is used. See “LOG
LEVELS”.

--log-level ERROR | WARNING | INFO | DEBUG
A more explicit version of -v. This flag takes precedence over -v.

--log-file file
Specify a log file. file will be truncated. By default, the INFO loglevel is used.

--log-file-level ERROR | WARNING | INFO | DEBUG
Set file log level.

--desktop-file-quirks ARGS
Modify j4-dmenu-desktop's desktop file parsing mechanism to accommodate desktop files not
conforming to the Desktop Entry Specification. Several modes may be specified. They shall be
separated by a comma (,). Each mode has a nomode counterpart, which disables the named mode. To
disable all modes, use --strict-parsing. A warning is printed when a desktop file makes use of
an enabled quirk. ARGS can contain the following modes:

wine Tolerate invalid escape codes (such as escaping a space to disable separating arguments)
in the Exec key of desktop files. Enabled by default.

multispace
Tolerate the usage of several spaces to separate arguments in the Exec key of desktop
files. Useful for desktop files generated by distrobox. Enabled by default.

If this flag is specified multiple times, only the last one takes effect. They are not merged
nor combined in any way.

This flag is mutually exclusive with --strict-parsing.

--strict-parsing
Strictly adhere to the Desktop Entry Specification while parsing desktop files. Not enabled by
default.

This flag is mutually exclusive with --desktop-file-quirks.

--version
Display program version.

-h, --help
Display help message.

LOG LEVELS
Some arguments support setting the log level. j4-dmenu-desktop uses the following log levels: ERROR,
WARNING, INFO and DEBUG. The WARNING (and ERROR) loglevels are displayed by default. Lower loglevels
automatically enable higher ones.

TERM MODE
There are several modes available for the --term-mode flag:

default
The default mode. A temporary shell script is created containing the chosen command. The script
deletes itself upon execution, j4-dmenu-desktop never deletes it itself. It sets the title of
terminal emulator using OSC escape sequences (see console_codes(4)). Terminal emulator is
executed as follows:

[terminal emulator] -e [generated temporary script]

Other modes should be preferred. This approach is universal but fragile.

Default value of --term is i3-sensible-terminal.

xterm Use xterm calling convention:

[terminal emulator] -title [desktop app Name] -e [command line]

Default value of --term is xterm. Other compatible terminal emulators include: rxvt-unicode.

alacritty
Use alacritty calling convention:

[terminal emulator] -T [desktop app Name] -e [command line]

Default value of --term is alacritty. Other compatible terminal emulators include: st, foot.

kitty Use kitty calling convention:

[terminal emulator] -T [desktop app Name] [command line]

Default value of --term is kitty. Other compatible terminal emulators include: foot.

terminator
Use terminator calling convention:

[terminal emulator] -T [desktop app Name] -x [command line]

Default value of --term is terminator. Other compatible terminal emulators include:
xfce4-terminal.

gnome-terminal
Use gnome-terminal calling convention:

[terminal emulator] --title [desktop app Name] -- [command line]

Default value of --term is gnome-terminal.

custom Allow for completely custom handling of --term. When --term-mode custom is passed, an
alternative system for handling --term is used. It is handled as a list of arguments separated
by space ( ). No other whitespace characters act as an argument separator (this behavior differs
from the shell).

Multiple consecutive space characters will be treated as a single space (except for escaped
spaces). Leading and trailing spaces in --term will be ignored. This means that it is not
possible to pass zero-length arguments to --term.

The contents of --term are not executed through a shell. This means that shell constructs like
redirection, && and || chaining and more will not work. If you need this, you can either create
a wrapper shell script and call it from --term or you can call /bin/sh -c or some other shell
directly from --term (although using a wrapper script should be preferred, because it is clearer
and simpler to use).

The following placeholders are recognised:

{name} Name of desktop app. Useful for setting the title.

{cmdline@} Command line to be executed expanded as separate arguments. This must be an
independent argument; ‘j4-dmenu-desktop --term-mode custom --term "-e={cmdline@}"’ is
invalid.

{cmdline*} Command line to be executed expanded as a single argument. {cmdline@} should be
preferred over {cmdline*}. Arguments will be escaped; Contents of {cmdline*} can be
passed to /bin/sh -c safely.

{script} Filename of a script generated by j4-dmenu-desktop. This is the same script used by
--term-mode default. The script will be generated only if this placeholder is
specified at least once in --term. The script sets terminal title itself, it
shouldn't be necessary to set it manually.

{cmdline@} and {cmdline*} should be preferred over {script}.

The following escape sequences are recognised:

\\ Literal \ character.

\{ Literal { character.

\ (backslash with space) Do not handle the following space as an argument separator.

Undefined escape sequences and placeholders will result in an error message and program
termination.

Default value of --term is same as of default term mode.

This is how other modes look when written using custom mode:

default ‘j4-dmenu-desktop --term-mode custom --term "i3-sensible-terminal -e {script}"’

xterm ‘j4-dmenu-desktop --term-mode custom --term "xterm -title {name} -e {cmdline@}"’

alacritty ‘j4-dmenu-desktop --term-mode custom --term "alacritty -T {name} -e {cmdline@}"’

kitty ‘j4-dmenu-desktop --term-mode custom --term "kitty -T {name} {cmdline@}"’

terminator ‘j4-dmenu-desktop --term-mode custom --term "terminator -T {name} -x {cmdline@}"’

gnome-terminal ‘j4-dmenu-desktop --term-mode custom --term "gnome-terminal --title {name} --
{cmdline@}"’

This is how the deprecated -e flag of gnome-terminal could be used:

j4-dmenu-desktop --term-mode custom --term "gnome-terminal --title {name} -e {cmdline*}"

This is how placeholders can be escaped:

j4-dmenu-desktop --term-mode custom --term "echo \{name}\ \{cmdline*}"

--term receives two arguments: ‘echo’ and ‘{name} {cmdline*}’, no placeholders are replaced.
j4-dmenu-desktop would see three arguments instead of two if the second \ had not been passed.

ENVIRONMENT

       I3SOCK  This variable overwrites the i3/Sway IPC socket path.

       XDG_DATA_HOME
               Primary directory containing desktop files.

       XDG_DATA_DIRS
               Additional directories containing desktop files.

       XDG_CURRENT_DESKTOP
               Current  desktop  environment  used  for enabling/disabling desktop environment dependent desktop
               files.  Must be enabled by --use-xdg-de.

       Standard environmental variables for locales are acknowledged in addition to  those  listed  above.   The
       exact  environmental variables used are implementation-dependent, but setting LC_MESSAGES, LC_ALL or LANG
       should generally work.

COPYRIGHT

       Copyright (C) 2013 enkore <public+j4-dmenu-desktop@enkore.de>

       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.

       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.

       You should have received a copy of the GNU General Public License along with this program.  If  not,  see
       <http://www.gnu.org/licenses/>.

Debian                                          January 10, 2024$                            J4-DMENU-DESKTOP(1)

NAME

SYNOPSIS

DESCRIPTION

ENVIRONMENT

SEE ALSO

COPYRIGHT