238 lines
8.3 KiB
Groff
238 lines
8.3 KiB
Groff
.\" Automatically generated by Pandoc 2.17.1.1
|
|
.\"
|
|
.\" Define V font for inline verbatim, using C font in formats
|
|
.\" that render this, and otherwise B font.
|
|
.ie "\f[CB]x\f[]"x" \{\
|
|
. ftr V B
|
|
. ftr VI BI
|
|
. ftr VB B
|
|
. ftr VBI BI
|
|
.\}
|
|
.el \{\
|
|
. ftr V CR
|
|
. ftr VI CI
|
|
. ftr VB CB
|
|
. ftr VBI CBI
|
|
.\}
|
|
.TH "spmenu_run" "1" "" "3.5.0" "$PATH/.desktop launcher and file manager"
|
|
.hy
|
|
.SH spmenu_run
|
|
.PP
|
|
spmenu includes a powerful Bash script called spmenu_run.
|
|
It has several different components, but the run launcher component
|
|
lists out executable programs in $PATH and displays them to the user in
|
|
a list.
|
|
Not only that but it optionally shows recently run programs first in the
|
|
list, which is very useful.
|
|
.SS Run launcher component
|
|
.PP
|
|
By default it also saves history, which can be viewed by calling
|
|
\f[V]viewhistory\f[R] in your spmenu config.
|
|
By default the keybind is Ctrl+h in normal mode.
|
|
.PP
|
|
The selected option is then piped to /bin/sh (by default).
|
|
This component allows you to select multiple entries by calling
|
|
\f[V]markitem\f[R].
|
|
By default the keybind is Ctrl+Enter in any mode.
|
|
The selected item(s) are then executed in order one after one.
|
|
The run launcher also has some extra awesome features such as:
|
|
.IP \[bu] 2
|
|
Prepending \f[V]#\f[R] will spawn it in a terminal instead of just a
|
|
shell.
|
|
.IP \[bu] 2
|
|
Prepending \f[V]?\f[R] will run the command in a function, most of the
|
|
time used to display the man page.
|
|
.IP \[bu] 2
|
|
Prepending \f[V]magnet\f[R] will open a magnet link in $TORRENT
|
|
.IP \[bu] 2
|
|
Prepending \f[V]www\f[R] will open a page in $BROWSER
|
|
.PP
|
|
Most of the time you don\[cq]t need to prepend \f[V]www\f[R] though, for
|
|
example typing in \f[V]https://gnu.org\f[R] will open gnu.org in
|
|
$BROWSER even without the prefix.
|
|
If $BROWSER isn\[cq]t set then $BROWSER will be set to xdg-open.
|
|
Same goes for magnet links, although this has limited use.
|
|
.PP
|
|
By default it also saves history, which can be viewed by calling
|
|
\f[V]viewhistory\f[R] in your spmenu config.
|
|
By default the keybind is Ctrl+h in normal mode.
|
|
.SS .desktop entry component
|
|
.PP
|
|
In addition to the $PATH listing, spmenu_run also allows listing out and
|
|
displaying .desktop entries through the desktop component.
|
|
It does this in style too by default, by displaying the program icon.
|
|
.PP
|
|
The .desktop entries are looked for recursively in
|
|
/usr/share/applications, and the icons are looked for recursively in
|
|
/usr/share/icons/hicolor.
|
|
Of course you can change this path or even add multiple.
|
|
This is done in the configuration file for spmenu_run.
|
|
.PP
|
|
Entries are cached, so the first time the component is used spmenu will
|
|
take a while to spawn.
|
|
Just be patient, it will eventually get through all of them.
|
|
To clear the cache (useful if you just installed/uninstalled a program)
|
|
run \f[V]spmenu_run -cc\f[R].
|
|
.PP
|
|
\f[B]NOTE: By default it will hide any entries matching
|
|
\f[VB]spmenu\f[B] (for convenience) but you can unhide these if you wish
|
|
through the configuration file.\f[R]
|
|
.PP
|
|
Flatpaks are also functional, provided they use valid .desktop entries.
|
|
You can use Flatpaks with spmenu_run by passing \f[V]-d\f[R].
|
|
$DESKTOP_DIR and $ICON_DIR must contain Flatpak paths though.
|
|
If you have a new config, these variables should be defined properly
|
|
already.
|
|
.SS Bookmarking
|
|
.PP
|
|
spmenu_run provides bookmarking entries or just general text if
|
|
preferred.
|
|
To view the saved bookmarks, open \f[V]spmenu_run -x\f[R] (the run
|
|
launcher component) and type in \f[V]\[at]\f[R].
|
|
If you have no bookmarks what you\[cq]re going to get is an empty menu.
|
|
To add bookmarks, type \[at] followed by a command.
|
|
For example \f[V]\[at]chromium\f[R] will bookmark an entry called
|
|
\f[V]chromium\f[R], which will open Chromium.
|
|
.PP
|
|
If you want a longer command, you might want a shorter title to be
|
|
displayed .
|
|
In that case you can type \[at] followed by a name and a colon.
|
|
Anything you type \f[I]after\f[R] the colon will be executed using a
|
|
shell.
|
|
For example
|
|
\f[V]\[at]spmenu documentation:chromium https://spmenu.speedie.site\f[R]
|
|
will add an entry called \f[V]spmenu documentation\f[R] which when
|
|
selected will open the spmenu wiki in Chromium.
|
|
.PP
|
|
For traditional bookmarking, consider something like
|
|
\f[V]\[at]spmenu documentation:echo spmenu.speedie.site | xclip -sel clipboard\f[R].
|
|
spmenu_run bookmarks should be treated as shell commands.
|
|
.SS File manager component
|
|
.PP
|
|
Finally, it also comes with a file manager component.
|
|
Out of the box this is very basic and only lists out files and opens
|
|
some default known filetypes in respective programs, but could be
|
|
expanded to allow for features proper file managers usually have.
|
|
.PP
|
|
It is intended to be used in your shell scripts with the \f[V]-o\f[R]
|
|
flag to select a file.
|
|
You can see this in action in the spmenuify theme manager.
|
|
.SS Usage
|
|
.PP
|
|
Running \f[V]spmenu_run\f[R] in a shell will execute spmenu_run using
|
|
the default component (defined in the configuration file).
|
|
You can override this using arguments.
|
|
Note that you can always override this using arguments, see Arguments
|
|
for more information.
|
|
.SS Arguments
|
|
.PP
|
|
You may use long, descriptive arguments or the shorter arguments.
|
|
.TP
|
|
\f[V]-x, --run\f[R]
|
|
List entries in $PATH
|
|
.TP
|
|
\f[V]-f, --fm dir\f[R]
|
|
List files and directories in dir
|
|
.TP
|
|
\f[V]-d, --desktop\f[R]
|
|
List .desktop entries
|
|
.TP
|
|
\f[V]-p, --full-path\f[R]
|
|
Print the full path to the file selected (-fm)
|
|
.TP
|
|
\f[V]-np, --no-full-path\f[R]
|
|
Don\[cq]t print the full path to the file selected (-fm)
|
|
.TP
|
|
\f[V]-cc, --clear-cache\f[R]
|
|
Clear cache, useful if you just installed/uninstalled a program.
|
|
(-d)
|
|
.TP
|
|
\f[V]-dm, --dmenu\f[R]
|
|
Run spmenu_run using dmenu instead of spmenu
|
|
.TP
|
|
\f[V]-ndm, --no-dmenu\f[R]
|
|
Run spmenu_run using spmenu instead of dmenu
|
|
.TP
|
|
\f[V]-h, --help\f[R]
|
|
Print help
|
|
.TP
|
|
\f[V]-o, --stdout\f[R]
|
|
Print to standard input and do not execute the selected item
|
|
.TP
|
|
\f[V]-no, --no-stdout\f[R]
|
|
Don\[cq]t print to standard input, execute the selected item
|
|
.TP
|
|
\f[V]-a, --args args\f[R]
|
|
Pass args to spmenu
|
|
.SS Configuration
|
|
.PP
|
|
When spmenu_run is started for the first time, a default configuration
|
|
file is created at \f[V]\[ti]/.config/spmenu/run/config\f[R].
|
|
If \f[V]${XDG_CONFIG_HOME}\f[R] has been changed this path will differ.
|
|
This configuration file unlike the spmenu configuration file is
|
|
configured in Bash, allowing you to use POSIX compliant features as well
|
|
as Bash features for not only configuration but also to create various
|
|
functions.
|
|
.PP
|
|
All of the variables are already defined, and there are several
|
|
functions you can define yourself which spmenu_run will execute on a
|
|
certain condition.
|
|
This allows for a very customizable run launcher, because it means
|
|
almost anything Bash can do can be done with spmenu_run.
|
|
.PP
|
|
spmenu_run will execute the following functions (from your
|
|
\f[V]\[ti]/.config/spmenu/run/config\f[R] file) if they are found:
|
|
.IP \[bu] 2
|
|
\f[V]run_pre_func\f[R] before spawning spmenu.
|
|
.IP \[bu] 2
|
|
\f[V]run_post_func\f[R] after spawning spmenu, selected item passed as
|
|
an argument.
|
|
.IP \[bu] 2
|
|
\f[V]desktop_pre_func\f[R] before spawning spmenu.
|
|
.IP \[bu] 2
|
|
\f[V]desktop_post_func\f[R] after spawning spmenu, selected item passed
|
|
as an argument.
|
|
.IP \[bu] 2
|
|
\f[V]fm_pre_func\f[R] before spawning spmenu.
|
|
.IP \[bu] 2
|
|
\f[V]fm_post_func\f[R] after spawning spmenu, selected item passed as an
|
|
argument.
|
|
.IP \[bu] 2
|
|
\f[V]fm_pre_list_func\f[R] right before listing out files.
|
|
.IP \[bu] 2
|
|
\f[V]fm_post_list_func\f[R] right after listing out files.
|
|
.IP \[bu] 2
|
|
\f[V]fm_dir_func\f[R] before changing directory to the selected
|
|
directory.
|
|
.IP \[bu] 2
|
|
\f[V]fm_line_func\f[R] for each line in ls output, the line is passed as
|
|
an argument, including SGR colors.
|
|
.IP \[bu] 2
|
|
\f[V]read_man\f[R] when reading a man page, selected item passed as an
|
|
argument.
|
|
.PP
|
|
More detailed documentation regarding this is available in the spmenu
|
|
wiki including example functions that can be copied into your
|
|
configuration.
|
|
.SS License
|
|
.PP
|
|
spmenu_run is licensed under the MIT license just like spmenu itself
|
|
because that\[cq]s the original suckless license.
|
|
See the included LICENSE file for more information.
|
|
.SS Reporting issues
|
|
.PP
|
|
Please report issues on the Git
|
|
repository (https://git.speedie.site/speedie/spmenu) or alternatively
|
|
email me.
|
|
.SS See also
|
|
.IP \[bu] 2
|
|
spmenu(1)
|
|
.IP \[bu] 2
|
|
spmenu_test(1)
|
|
.IP \[bu] 2
|
|
spmenu wiki (https://spmenu.speedie.site)
|
|
.IP \[bu] 2
|
|
spmenu git repository (https://git.speedie.site/speedie/spmenu)
|
|
.IP \[bu] 2
|
|
spmenu GitHub mirror (https://github.com/speediegq/spmenu)
|