From 82fa3eaa95b8fff8b7fa084f6ce76d75e963c610 Mon Sep 17 00:00:00 2001 From: speedie Date: Tue, 16 May 2023 20:50:08 +0200 Subject: [PATCH] add separate man page for spmenu_run --- docs/docs.md | 21 ++-- docs/run-docs.md | 131 +++++++++++++++++++++++++ meson.build | 1 + scripts/make/generate-docs.sh | 5 + scripts/make/generate-pkg.sh | 1 + scripts/spmenu_run | 18 ++-- spmenu.1 | 24 +++-- spmenu.html | 21 ++-- spmenu_run.1 | 174 ++++++++++++++++++++++++++++++++++ 9 files changed, 360 insertions(+), 36 deletions(-) create mode 100644 docs/run-docs.md create mode 100644 spmenu_run.1 diff --git a/docs/docs.md b/docs/docs.md index a390f02..a4bd852 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -1,17 +1,17 @@ spmenu ====== -spmenu is a program for X11 that reads standard input and allows the user to -select items separated by a newline. It's a fork of -[suckless's dmenu](https://tools.suckless.org/dmenu) which is a good more -minimal alternative to spmenu. +spmenu is an X11 menu application which takes standard input, parses +it, and lets the user choose an option and sends the +selected option to standard output. -What makes spmenu different from all the dmenu forks is that spmenu has -features like color support, Vim-like modes, image support, -proper mouse/keybind configuration, and more. +In addition to this, it also serves as a run launcher through the included +shell script `spmenu_run`, which handles both $PATH listing, .desktop entries +and file listing. See spmenu_run(1) for more information related to +using spmenu as a run launcher. -It should be noted that most of these features may be disabled by the user, either -during compile time or through configuration. +While spmenu is based on dmenu, and is also fully compatible with dmenu, +spmenu introduces many new features which can be useful in shell scripting. ## Usage @@ -23,6 +23,9 @@ This allows things like `printf "Apple\nOrange\nPear\n" | spmenu`. This command will spawn an spmenu window with three items, 'Apple', 'Orange' and 'Pear'. This can be used in shell scripts to create interactive menus. +spmenu doesn't strictly read standard input, it can read from files too using +the `-lf` or `--list-file` argument. + On top of this, you can specify arguments to change the behavior of spmenu. See a list below for a list. diff --git a/docs/run-docs.md b/docs/run-docs.md new file mode 100644 index 0000000..905c560 --- /dev/null +++ b/docs/run-docs.md @@ -0,0 +1,131 @@ +spmenu_run +========== + +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. + +By default it also saves history, which can be viewed by calling +`viewhistory` in your spmenu config. By default the keybind +is Ctrl+h in normal mode. + +The selected option is then piped to /bin/sh (by default). This component +allows you to select multiple entries by calling `markitem`. 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: + +- Prepending `#` will spawn it in a terminal instead of just a shell. +- Prepending `?` will run the command in a function, most of the time used to +display the man page. +- Prepending `magnet` will open a magnet link in $TORRENT +- Prepending `www` will open a page in $BROWSER + +Most of the time you don't need to prepend `www` though, for example +typing in `https://gnu.org` will open gnu.org in $BROWSER even +without the prefix. Same goes for magnet links. + +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. + +Finally, it also comes with a file manager component. Out of the box +this is very basic, but could be expanded to allow for features +proper file managers usually have. It is intended to be used in +your shell scripts with the `-o` flag to select a file. You can +see this in action in the spmenuify theme manager. + +It can be configured through editing `~/.config/spmenu/run/config`. The +configuration file can also be moved by setting `${XDG_CONFIG_HOME}`. +For more information regarding configuration, see 'Configuration'. + +## Usage + +Running `spmenu_run` 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. + +## Arguments + +You may use long, descriptive arguments or the shorter arguments. + +`-x, --run` +: List entries in $PATH + +`-f, --fm dir` +: List files and directories in dir + +`-d, --desktop` +: List .desktop entries + +`-p, --full-path` +: Print the full path to the file selected (-fm) + +`-np, --no-full-path` +: Don't print the full path to the file selected (-fm) + +`-cc, --clear-cache` +: Clear cache, useful if you just installed/uninstalled a program. (-d) + +`-dm, --dmenu` +: Run spmenu_run using dmenu instead of spmenu + +`-ndm, --no-dmenu` +: Run spmenu_run using spmenu instead of dmenu + +`-h, --help` +: Print help + +`-o, --stdout` +: Print to standard input and do not execute the selected item + +`-no, --no-stdout` +: Don't print to standard input, execute the selected item + +`-a, --args args` +: Pass args to spmenu + +## Configuration + +When spmenu_run is started for the first time, a default configuration file +is created at `~/.config/spmenu/run/config`. This configuration file unlike +the spmenu configuration file is configured in Bash, allowing you to use +POSIX compliant features as well as Bash features. + +Most 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. + +spmenu_run will execute the following functions +(from your `~/.config/spmenu/run/config` file) if they are found: + +- `run_pre_func` before spawning spmenu. +- `run_post_func` after spawning spmenu, selected item passed as an argument. +- `desktop_pre_func` before spawning spmenu. +- `desktop_post_func` after spawning spmenu, selected item passed as an argument. +- `fm_pre_func` before spawning spmenu. +- `fm_post_func` after spawning spmenu, selected item passed as an argument. +- `fm_pre_list_func` right before listing out files. +- `fm_post_list_func` right after listing out files. +- `fm_dir_func` before changing directory to the selected directory. +- `fm_line_func` for each line in ls output, the line is passed as an argument, +including SGR colors. +- `read_man` when reading a man page, selected item passed as an argument. + +More detailed documentation regarding this is available in the spmenu wiki including +example functions that can be copied into your configuration. + +## License + +spmenu_run is licensed under the MIT license just like spmenu itself because +that's the original suckless license. See the included LICENSE file for more information. + +## Reporting issues + +Please report issues on the +[Codeberg repository](https://codeberg.org/speedie/spmenu) or alternatively +email me. diff --git a/meson.build b/meson.build index 4012326..da19618 100644 --- a/meson.build +++ b/meson.build @@ -83,6 +83,7 @@ project_target = executable( ) install_man('spmenu.1') +install_man('spmenu_run.1') install_data(sources : 'docs/docs.md', install_dir : 'share/spmenu') install_data(sources : 'docs/code-docs.md', install_dir : 'share/spmenu') install_data(sources : 'docs/example.Xresources', install_dir : 'share/spmenu') diff --git a/scripts/make/generate-docs.sh b/scripts/make/generate-docs.sh index 180f4eb..07bff84 100755 --- a/scripts/make/generate-docs.sh +++ b/scripts/make/generate-docs.sh @@ -7,5 +7,10 @@ pandoc --standalone --to man .man.md -o spmenu.1 pandoc --standalone .man.md -o spmenu.html rm -f .man.md +printf "%% spmenu_run(1) ${version} | \$PATH/.desktop launcher and file manager\n" > .man.md +grep -v docs/preview.png docs/run-docs.md >> .man.md +pandoc --standalone --to man .man.md -o spmenu_run.1 +rm -f .man.md + scripts/make/generate-code-docs.sh docs/code-docs.md code.html || return pandoc --standalone README.md -o README.html diff --git a/scripts/make/generate-pkg.sh b/scripts/make/generate-pkg.sh index 5cd5638..891496d 100755 --- a/scripts/make/generate-pkg.sh +++ b/scripts/make/generate-pkg.sh @@ -9,6 +9,7 @@ cp -rf LICENSE meson.build meson.options *.h *.c scripts/ docs/ libs/ themes/ PK [ -f host.mk ] && cp host.mk spmenu-${version} || : [ -f toggle.mk ] && cp toggle.mk spmenu-${version} || : [ -f spmenu.1 ] && cp spmenu.1 spmenu-${version} || : +[ -f spmenu_run.1 ] && cp spmenu_run.1 spmenu-${version} || : tar -cf spmenu-${version}.tar spmenu-${version} gzip spmenu-${version}.tar rm -rf spmenu-${version} diff --git a/scripts/spmenu_run b/scripts/spmenu_run index 8422874..9f5cfea 100755 --- a/scripts/spmenu_run +++ b/scripts/spmenu_run @@ -160,17 +160,19 @@ print_cli_help() { spmenu_run - Run launcher for spmenu spmenu_run -x, --run List entries in \$PATH. -spmenu_run -f, --fm List files and directories in . +spmenu_run -fm, --fm List files and directories in spmenu_run -d, --desktop List .desktop entries. spmenu_run -p, --full-path Print the full path to the file selected (-fm) spmenu_run -np, --no-full-path Don't print the full path to the file selected (-fm) -spmenu_run -cc, --clear-cache Clear cache, useful if you just installed/uninstalled a program. -spmenu_run -dm, --dmenu Run spmenu_run using dmenu instead of spmenu. -spmenu_run -ndm, --no-dmenu Run spmenu_run using spmenu instead of dmenu. -spmenu_run -h, --help Print this help. -spmenu_run -o, --stdout Print to standard input and do not execute the selected item. -spmenu_run -no, --no-stdout Don't print to standard input, execute the selected item. -spmenu_run -a, --args Pass to spmenu. +spmenu_run -cc, --clear-cache Clear cache, useful if you just installed/uninstalled a program (-d) +spmenu_run -dm, --dmenu Run spmenu_run using dmenu instead of spmenu +spmenu_run -ndm, --no-dmenu Run spmenu_run using spmenu instead of dmenu +spmenu_run -h, --help Print this help +spmenu_run -o, --stdout Print to standard input and do not execute the selected item +spmenu_run -no, --no-stdout Don't print to standard input, execute the selected item +spmenu_run -a, --args Pass to spmenu + +See spmenu(1) and spmenu_run(1) for more information. EOF } diff --git a/spmenu.1 b/spmenu.1 index ef46fcd..36c8a3e 100644 --- a/spmenu.1 +++ b/spmenu.1 @@ -18,18 +18,19 @@ .hy .SH spmenu .PP -spmenu is a program for X11 that reads standard input and allows the -user to select items separated by a newline. -It\[cq]s a fork of suckless\[cq]s -dmenu (https://tools.suckless.org/dmenu) which is a good more minimal -alternative to spmenu. +spmenu is an X11 menu application which takes standard input, parses it, +and lets the user choose an option and sends the selected option to +standard output. .PP -What makes spmenu different from all the dmenu forks is that spmenu has -features like color support, Vim-like modes, image support, proper -mouse/keybind configuration, and more. +In addition to this, it also serves as a run launcher through the +included shell script \f[V]spmenu_run\f[R], which handles both $PATH +listing, .desktop entries and file listing. +See spmenu_run(1) for more information related to using spmenu as a run +launcher. .PP -It should be noted that most of these features may be disabled by the -user, either during compile time or through configuration. +While spmenu is based on dmenu, and is also fully compatible with dmenu, +spmenu introduces many new features which can be useful in shell +scripting. .SS Usage .PP On runtime, spmenu reads from standard input (stdin). @@ -43,6 +44,9 @@ This command will spawn an spmenu window with three items, `Apple', `Orange' and `Pear'. This can be used in shell scripts to create interactive menus. .PP +spmenu doesn\[cq]t strictly read standard input, it can read from files +too using the \f[V]-lf\f[R] or \f[V]--list-file\f[R] argument. +.PP On top of this, you can specify arguments to change the behavior of spmenu. See a list below for a list. diff --git a/spmenu.html b/spmenu.html index 73f6a77..0d9a972 100644 --- a/spmenu.html +++ b/spmenu.html @@ -169,15 +169,16 @@

spmenu(1) 1.1.2 | fancy dynamic menu

spmenu

-

spmenu is a program for X11 that reads standard input and allows the -user to select items separated by a newline. It’s a fork of suckless’s dmenu which is a -good more minimal alternative to spmenu.

-

What makes spmenu different from all the dmenu forks is that spmenu -has features like color support, Vim-like modes, image support, proper -mouse/keybind configuration, and more.

-

It should be noted that most of these features may be disabled by the -user, either during compile time or through configuration.

+

spmenu is an X11 menu application which takes standard input, parses +it, and lets the user choose an option and sends the selected option to +standard output.

+

In addition to this, it also serves as a run launcher through the +included shell script spmenu_run, which handles both $PATH +listing, .desktop entries and file listing. See spmenu_run(1) for more +information related to using spmenu as a run launcher.

+

While spmenu is based on dmenu, and is also fully compatible with +dmenu, spmenu introduces many new features which can be useful in shell +scripting.

Usage

On runtime, spmenu reads from standard input (stdin). spmenu items are separated by a newline (\n). When (by default) Enter is @@ -186,6 +187,8 @@ pressed, the selected item will be piped to stdout.

printf "Apple\nOrange\nPear\n" | spmenu. This command will spawn an spmenu window with three items, ‘Apple’, ‘Orange’ and ‘Pear’. This can be used in shell scripts to create interactive menus.

+

spmenu doesn’t strictly read standard input, it can read from files +too using the -lf or --list-file argument.

On top of this, you can specify arguments to change the behavior of spmenu. See a list below for a list.

Arguments

diff --git a/spmenu_run.1 b/spmenu_run.1 new file mode 100644 index 0000000..7eed3a8 --- /dev/null +++ b/spmenu_run.1 @@ -0,0 +1,174 @@ +.\" Automatically generated by Pandoc 3.0.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" "" "1.1.2" "$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. +.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. +Same goes for magnet links. +.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 +Finally, it also comes with a file manager component. +Out of the box this is very basic, but could be expanded to allow for +features proper file managers usually have. +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. +.PP +It can be configured through editing +\f[V]\[ti]/.config/spmenu/run/config\f[R]. +The configuration file can also be moved by setting +\f[V]${XDG_CONFIG_HOME}\f[R]. +For more information regarding configuration, see `Configuration'. +.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]. +This configuration file unlike the spmenu configuration file is +configured in Bash, allowing you to use POSIX compliant features as well +as Bash features. +.PP +Most 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 Codeberg +repository (https://codeberg.org/speedie/spmenu) or alternatively email +me.