J4-DMENU-DESKTOP(1)

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.

    Possible values are: default | xterm | alacritty | kitty | terminator | gnome-terminal | custom

    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.

SEE ALSO
https://github.com/enkore/j4-dmenu-desktop

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/ >.