From fa645e1ae70244d781ec702c06a7eb43659cc462 Mon Sep 17 00:00:00 2001
From: speedie <speedie@duck.com>
Date: Wed, 17 May 2023 08:15:21 +0200
Subject: [PATCH] update documentation

---
 README.html                   |  5 +++-
 docs/docs.md                  |  4 +++
 docs/run-docs.md              | 48 +++++++++++++++++++++++++++--------
 scripts/make/generate-docs.sh |  4 +--
 spmenu.1                      |  3 +++
 spmenu.html                   |  8 ++++--
 spmenu_run.1                  | 44 ++++++++++++++++++++++++--------
 7 files changed, 90 insertions(+), 26 deletions(-)
diff --git a/README.html b/README.html
index ff96204..44a0765 100644
--- a/README.html
+++ b/README.html
@@ -4,7 +4,7 @@
   <meta charset="utf-8" />
   <meta name="generator" content="pandoc" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
-  <title>README</title>
+  <title>spmenu README</title>
   <style>
     html {
       color: #1a1a1a;
@@ -165,6 +165,9 @@
   <![endif]-->
 </head>
 <body>
+<header id="title-block-header">
+<h1 class="title">spmenu README</h1>
+</header>
 <figure>
 <img src="docs/spmenu.svg" title="spmenu" style="width:25.0%"
 alt="spmenu logo" />
diff --git a/docs/docs.md b/docs/docs.md
index a4bd852..d73f2f3 100644
--- a/docs/docs.md
+++ b/docs/docs.md
@@ -746,3 +746,7 @@ license. See the included LICENSE file for more information.
 Please report issues on the
 [Codeberg repository](https://codeberg.org/speedie/spmenu) or alternatively
 email me.
+
+## See also
+
+- spmenu_run(1)
diff --git a/docs/run-docs.md b/docs/run-docs.md
index 905c560..521d16a 100644
--- a/docs/run-docs.md
+++ b/docs/run-docs.md
@@ -7,6 +7,8 @@ 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.
 
+## Run launcher component
+
 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.
@@ -27,19 +29,37 @@ 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.
 
+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.
+
+## .desktop entry component
+
 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.
+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.
 
-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'.
+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 `spmenu_run -cc`.
+
+**NOTE: By default it will hide any entries matching `spmenu` (for convenience)
+but you can unhide these if you wish through the configuration file.**
+
+## File manager component
+
+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.
+
+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.
 
 ## Usage
 
@@ -91,11 +111,13 @@ You may use long, descriptive arguments or the shorter arguments.
 ## 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
+is created at `~/.config/spmenu/run/config`. If `${XDG_CONFIG_HOME}` 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.
+POSIX compliant features as well as Bash features for not only
+configuration but also to create various functions.
 
-Most of the variables are already defined, and there are several functions
+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.
@@ -129,3 +151,7 @@ that's the original suckless license. See the included LICENSE file for more inf
 Please report issues on the
 [Codeberg repository](https://codeberg.org/speedie/spmenu) or alternatively
 email me.
+
+## See also
+
+- spmenu(1)
diff --git a/scripts/make/generate-docs.sh b/scripts/make/generate-docs.sh
index 07bff84..556cca9 100755
--- a/scripts/make/generate-docs.sh
+++ b/scripts/make/generate-docs.sh
@@ -4,7 +4,7 @@ version="$(grep "version : '" meson.build | awk '{ print $3 }' | sed "s/'\"//g;
 printf "%% spmenu(1) ${version} | fancy dynamic menu\n" > .man.md
 grep -v docs/preview.png docs/docs.md >> .man.md
 pandoc --standalone --to man .man.md -o spmenu.1
-pandoc --standalone .man.md -o spmenu.html
+pandoc --standalone .man.md -o spmenu.html --metadata title="spmenu man page"
 rm -f .man.md
 
 printf "%% spmenu_run(1) ${version} | \$PATH/.desktop launcher and file manager\n" > .man.md
@@ -13,4 +13,4 @@ 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
+pandoc --standalone README.md -o README.html --metadata title="spmenu README"
diff --git a/spmenu.1 b/spmenu.1
index 36c8a3e..779ff96 100644
--- a/spmenu.1
+++ b/spmenu.1
@@ -810,3 +810,6 @@ See the included LICENSE file for more information.
 Please report issues on the Codeberg
 repository (https://codeberg.org/speedie/spmenu) or alternatively email
 me.
+.SS See also
+.IP \[bu] 2
+spmenu_run(1)
diff --git a/spmenu.html b/spmenu.html
index 0d9a972..c58c7d0 100644
--- a/spmenu.html
+++ b/spmenu.html
@@ -4,7 +4,7 @@
   <meta charset="utf-8" />
   <meta name="generator" content="pandoc" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
-  <title>spmenu(1) 1.1.2 | fancy dynamic menu</title>
+  <title>spmenu man page</title>
   <style>
     html {
       color: #1a1a1a;
@@ -166,7 +166,7 @@
 </head>
 <body>
 <header id="title-block-header">
-<h1 class="title">spmenu(1) 1.1.2 | fancy dynamic menu</h1>
+<h1 class="title">spmenu man page</h1>
 </header>
 <h1 id="spmenu">spmenu</h1>
 <p>spmenu is an X11 menu application which takes standard input, parses
@@ -1061,5 +1061,9 @@ information.</p>
 <p>Please report issues on the <a
 href="https://codeberg.org/speedie/spmenu">Codeberg repository</a> or
 alternatively email me.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li>spmenu_run(1)</li>
+</ul>
 </body>
 </html>
diff --git a/spmenu_run.1 b/spmenu_run.1
index 7eed3a8..43926ef 100644
--- a/spmenu_run.1
+++ b/spmenu_run.1
@@ -24,6 +24,7 @@ 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.
@@ -51,22 +52,40 @@ 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
+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]
+.SS File manager component
+.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.
+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.
-.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
@@ -118,11 +137,13 @@ Pass args to spmenu
 .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.
+as Bash features for not only configuration but also to create various
+functions.
 .PP
-Most of the variables are already defined, and there are several
+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
@@ -172,3 +193,6 @@ See the included LICENSE file for more information.
 Please report issues on the Codeberg
 repository (https://codeberg.org/speedie/spmenu) or alternatively email
 me.
+.SS See also
+.IP \[bu] 2
+spmenu(1)
