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