speedie/spmenu
2
0
Fork 1
Code Issues 1 Pull requests Packages Projects Releases 15 Wiki Activity

various docs changes to represent last few commits

Browse source
This commit is contained in:
speedie 2023-04-25 18:11:49 +02:00
parent 0457a53478
commit f94f1ce9ab
9 changed files with 256 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
Makefile
View file

@ -98,6 +98,7 @@ man:
docs: man docs: man
command -v weasyprint || exit 1 command -v weasyprint || exit 1
scripts/make/generate-code-docs.sh docs/code-docs.md code.html || exit 1 scripts/make/generate-code-docs.sh docs/code-docs.md code.html || exit 1
pandoc --standalone README.md -o README.html
weasyprint code.html code.pdf || exit 1 weasyprint code.html code.pdf || exit 1
weasyprint README.html README.pdf || exit 1 weasyprint README.html README.pdf || exit 1
weasyprint spmenu.html spmenu.pdf || exit 1 weasyprint spmenu.html spmenu.pdf || exit 1

184
README.html
View file

@ -1,3 +1,170 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<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>
<style>
html {
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 12px;
}
h1 {
font-size: 1.8em;
}
}
@media print {
html {
background-color: white;
}
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
font-size: 85%;
margin: 0;
hyphens: manual;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
ul.task-list li input[type="checkbox"] {
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1 id="spmenu">spmenu</h1> <h1 id="spmenu">spmenu</h1>
<figure> <figure>
<img src="docs/preview.png" alt="image" /> <img src="docs/preview.png" alt="image" />
@ -8,8 +175,9 @@
href="https://tools.suckless.org/dmenu">dmenu</a> which takes standard href="https://tools.suckless.org/dmenu">dmenu</a> which takes standard
input, parses it, and lets the user choose an option and sends the input, parses it, and lets the user choose an option and sends the
selected option to standard output.</p> selected option to standard output.</p>
<p>In addition to this, it also serves as a run launcher through the included <p>In addition to this, it also serves as a run launcher through the
shell script `spmenu_run`, which handles both $PATH listing and .desktop entries.</p> included shell script <code>spmenu_run</code>, which handles both $PATH
listing and .desktop entries.</p>
<p>It is designed to integrate well with my <a <p>It is designed to integrate well with my <a
href="https://dwm.suckless.org">dwm</a> fork, <a href="https://dwm.suckless.org">dwm</a> fork, <a
href="https://git.speedie.site/speedwm">speedwm</a>.</p> href="https://git.speedie.site/speedwm">speedwm</a>.</p>
@ -18,7 +186,7 @@ href="https://git.speedie.site/speedwm">speedwm</a>.</p>
course if you want, this is free software so you can use it in your own course if you want, this is free software so you can use it in your own
build.</p> build.</p>
<ul> <ul>
<li>Proper configuration file support</li> <li>Proper configuration file, including keybinds.</li>
<li>dwm-like key/mouse bind array (See keybinds.h and mouse.h)</li> <li>dwm-like key/mouse bind array (See keybinds.h and mouse.h)</li>
<li>Vim-like modes, including indicator.</li> <li>Vim-like modes, including indicator.</li>
<li>The ability to move around items with keybinds.</li> <li>The ability to move around items with keybinds.</li>
@ -145,8 +313,8 @@ includes <code>x11-misc/spmenu</code> as well as other useful
packages.</p> packages.</p>
<h2 id="installation-arch-gnulinux">Installation (Arch GNU/Linux)</h2> <h2 id="installation-arch-gnulinux">Installation (Arch GNU/Linux)</h2>
<p>If you are on Arch GNU/Linux, you can add <a <p>If you are on Arch GNU/Linux, you can add <a
href="https://git.speedie.site/speedie-repository">my repository</a> which href="https://git.speedie.site/speedie-repository">my repository</a>
includes <code>spmenu</code> as well as other useful packages.</p> which includes <code>spmenu</code> as well as other useful packages.</p>
<p>There’s also a PKGBUILD. To use it, simply <p>There’s also a PKGBUILD. To use it, simply
<code>make install_arch</code> in the directory the PKGBUILD is <code>make install_arch</code> in the directory the PKGBUILD is
located.</p> located.</p>
@ -157,8 +325,6 @@ free to add it to this list.</p>
issues!</p> issues!</p>
<h3 id="general">General</h3> <h3 id="general">General</h3>
<ul> <ul>
<li>Config file: Add configuration file using (probably) libconfig,
allowing keybinds to be configured without recompiling spmenu.</li>
<li>Image support: Stop using OpenSSL for caching images, mostly because <li>Image support: Stop using OpenSSL for caching images, mostly because
MD5() is deprecated as of OpenSSL 3.0, but this would also make it very MD5() is deprecated as of OpenSSL 3.0, but this would also make it very
easy to have LibreSSL compatibility.</li> easy to have LibreSSL compatibility.</li>
@ -189,7 +355,7 @@ state.</li>
markup. Silencing this would be a good idea.</li> markup. Silencing this would be a good idea.</li>
<li>Image support: Images take a long time to load sometimes, <li>Image support: Images take a long time to load sometimes,
particularly when items are selected using the cursor so what we really particularly when items are selected using the cursor so what we really
need is a way to skip over images after a set time limit</li> need is a way to skip over images after a set time limit.</li>
</ul> </ul>
<h2 id="scripts">Scripts</h2> <h2 id="scripts">Scripts</h2>
<p>This build of spmenu should work with all spmenu/dmenu scripts. <a <p>This build of spmenu should work with all spmenu/dmenu scripts. <a
@ -213,3 +379,5 @@ src="https://codeberg.org/speedie/spmenu-screenshots/raw/branch/master/spmenu-gr
alt="image" /> <img alt="image" /> <img
src="https://codeberg.org/speedie/spmenu-screenshots/raw/branch/master/colorscheme3.png" src="https://codeberg.org/speedie/spmenu-screenshots/raw/branch/master/colorscheme3.png"
alt="image" /></p> alt="image" /></p>
</body>
</html>

5
README.md
View file

@ -19,7 +19,7 @@ It is designed to integrate well with my [dwm](https://dwm.suckless.org) fork, [
This build of spmenu has some features written for this build. This build of spmenu has some features written for this build.
Of course if you want, this is free software so you can use it in your own build. Of course if you want, this is free software so you can use it in your own build.
- Proper configuration file support - Proper configuration file, including keybinds.
- dwm-like key/mouse bind array (See keybinds.h and mouse.h) - dwm-like key/mouse bind array (See keybinds.h and mouse.h)
- Vim-like modes, including indicator. - Vim-like modes, including indicator.
- The ability to move around items with keybinds. - The ability to move around items with keybinds.
@ -126,7 +126,6 @@ Pull requests would be greatly appreciated for any of these issues!
### General ### General
- Config file: Add mouse/keybind configuration
- Image support: Stop using OpenSSL for caching images, mostly because MD5() - Image support: Stop using OpenSSL for caching images, mostly because MD5()
is deprecated as of OpenSSL 3.0, but this would also make it very easy to is deprecated as of OpenSSL 3.0, but this would also make it very easy to
have LibreSSL compatibility. have LibreSSL compatibility.
@ -152,7 +151,7 @@ like you will be unable to use spmenu in its current state.
Silencing this would be a good idea. Silencing this would be a good idea.
- Image support: Images take a long time to load sometimes, particularly when - Image support: Images take a long time to load sometimes, particularly when
items are selected using the cursor so what we really need is a way to items are selected using the cursor so what we really need is a way to
skip over images after a set time limit skip over images after a set time limit.
## Scripts ## Scripts

BIN
README.pdf
View file

Binary file not shown.

BIN
code.pdf
View file

Binary file not shown.

61
docs/docs.md
View file

@ -2,7 +2,7 @@ spmenu
====== ======
spmenu is a program for X11 that reads standard input and allows the user to spmenu is a program for X11 that reads standard input and allows the user to
select items separated by a newline. It is a fork of select items separated by a newline. It's a fork of
[suckless's dmenu](https://tools.suckless.org/dmenu) which is a good more [suckless's dmenu](https://tools.suckless.org/dmenu) which is a good more
minimal alternative to spmenu. minimal alternative to spmenu.
@ -13,8 +13,7 @@ proper mouse/keybind configuration, and more.
It should be noted that most of these features may be disabled by the user, either It should be noted that most of these features may be disabled by the user, either
during compile time or through configuration. during compile time or through configuration.
Usage ## Usage
=====
On runtime, spmenu reads from standard input (stdin). spmenu items are On runtime, spmenu reads from standard input (stdin). spmenu items are
separated by a newline (`\n`). When (by default) Enter is pressed, the selected separated by a newline (`\n`). When (by default) Enter is pressed, the selected
@ -27,8 +26,7 @@ This can be used in shell scripts to create interactive menus.
On top of this, you can specify arguments to change the behavior of spmenu. On top of this, you can specify arguments to change the behavior of spmenu.
See a list below for a list. See a list below for a list.
Arguments ## Arguments
=========
You may use long, descriptive arguments or the shorter arguments. You may use long, descriptive arguments or the shorter arguments.
@ -470,13 +468,17 @@ dmenu compatibility can be achieved using these arguments:
`-sf color` `-sf color`
: Set the selected foreground color : Set the selected foreground color
Keybinds ## Keybinds
========
See `keybinds.h` for a list. You can set keybinds through the config file. A default config file is available
after installing spmenu. This configuration file has identical keybindings to the
default hardcoded keybinds.
Modes By default, the configuration file will ignore all hardcoded keybindings to
===== prevent keybind conflicts, but if you do not like this behaviour you can
simply set `ignoreglobalkeys = 1`.
## Modes
One of the features that separate spmenu from dmenu is spmenu's different One of the features that separate spmenu from dmenu is spmenu's different
modes. As of version 0.2, there are two modes. Normal mode and Insert mode. modes. As of version 0.2, there are two modes. Normal mode and Insert mode.
@ -492,15 +494,13 @@ this mode, most keybinds do nothing. When you are in insert mode, you
filter items by typing text into the field. Once you're done filter items by typing text into the field. Once you're done
with insert mode, you can press Escape to enter normal mode again. with insert mode, you can press Escape to enter normal mode again.
-p option ## -p option
=========
spmenu has a -p option, which stands for prompt. It allows you to specify spmenu has a -p option, which stands for prompt. It allows you to specify
text to display next to the item list. It is displayed on the left side of the text to display next to the item list. It is displayed on the left side of the
spmenu window. It should be noted that the prompt is purely visual though. spmenu window. It should be noted that the prompt is purely visual though.
Images ## Images
======
spmenu supports drawing images. This image is placed on the left side of spmenu supports drawing images. This image is placed on the left side of
the menu window. To use an image, pipe `IMG:/path/to/image` to spmenu. the menu window. To use an image, pipe `IMG:/path/to/image` to spmenu.
@ -519,8 +519,7 @@ There are also a few image related arguments, such as:
NOTE: Vector images (such as .svg) can be displayed too. NOTE: Vector images (such as .svg) can be displayed too.
Colored text ## Colored text
============
spmenu supports colored text through SGR sequences. This is the same colors spmenu supports colored text through SGR sequences. This is the same colors
that you might already be using in your shell scripts. This means you can that you might already be using in your shell scripts. This means you can
@ -536,8 +535,7 @@ if you want this.
See 'SGR sequences' for more information. See 'SGR sequences' for more information.
SGR sequences ## SGR sequences
=============
A basic supported SGR sequence looks like this: `\033[X;YZm` A basic supported SGR sequence looks like this: `\033[X;YZm`
@ -563,8 +561,7 @@ Just as a tip, you can pipe your colored spmenu output to
`sed -e 's/\x1b\[[0-9;]*m//g'`. This will clear the SGR sequences from `sed -e 's/\x1b\[[0-9;]*m//g'`. This will clear the SGR sequences from
the output. This is useful when you want to check what the output actually is. the output. This is useful when you want to check what the output actually is.
Pango markup ## Pango markup
============
If spmenu was compiled with Pango enabled (default), you should be able to If spmenu was compiled with Pango enabled (default), you should be able to
utilize Pango markup in every part of spmenu. That is, the mode indicator, utilize Pango markup in every part of spmenu. That is, the mode indicator,
@ -609,8 +606,7 @@ need to parse it manually. Doing so with `sed` is very easy. For example:
See [this page](https://docs.gtk.org/Pango/pango_markup.html) for more information. See [this page](https://docs.gtk.org/Pango/pango_markup.html) for more information.
Configuration ## Configuration
=============
Unlike dmenu, spmenu has a configuration file which can be edited by hand. It Unlike dmenu, spmenu has a configuration file which can be edited by hand. It
is located in ~/.config/spmenu/spmenu.conf, but you can override this by is located in ~/.config/spmenu/spmenu.conf, but you can override this by
@ -623,8 +619,7 @@ This configuration file is loaded on startup.
You can also include other configuration files in the configuration file using You can also include other configuration files in the configuration file using
`@include "path/to/config"`. `@include "path/to/config"`.
.Xresources ## .Xresources
=============
spmenu also has .Xresources (xrdb) support built in. It reads the xrdb spmenu also has .Xresources (xrdb) support built in. It reads the xrdb
(.Xresources database) on runtime. You may disable it by passing -nxrdb, (.Xresources database) on runtime. You may disable it by passing -nxrdb,
@ -638,8 +633,7 @@ as you can just `xrdb -override` any .Xresources file you want.
You can also use wildcards (such as `*`) to achieve a global colorscheme. You can also use wildcards (such as `*`) to achieve a global colorscheme.
Programs like `pywal` do this to apply universal colorschemes. Programs like `pywal` do this to apply universal colorschemes.
Profiles ## Profiles
========
spmenu supports profiles. Profiles are like configuration spmenu supports profiles. Profiles are like configuration
files (See `Configuration`) that can be switched between quickly using a keybind. files (See `Configuration`) that can be switched between quickly using a keybind.
@ -669,8 +663,7 @@ the profile used before will be used in place.
There are a few color schemes for spmenu included in the repository, see There are a few color schemes for spmenu included in the repository, see
the `themes/` directory. Feel free to copy those to your profile directory. the `themes/` directory. Feel free to copy those to your profile directory.
Run launcher ## Run launcher
============
spmenu includes a shell script called spmenu_run. It lists executable programs spmenu includes a shell script called spmenu_run. It lists executable programs
in $PATH and displays them to the user in a list. Not only that but it shows in $PATH and displays them to the user in a list. Not only that but it shows
@ -697,8 +690,7 @@ without the prefix. Same goes for magnet links.
You can also configure the run launcher through editing You can also configure the run launcher through editing
`~/.config/spmenu/run/config` which is configured in shell syntax. `~/.config/spmenu/run/config` which is configured in shell syntax.
spmenu_desktop ## spmenu_desktop
==============
In addition to the aforementioned `spmenu_run`, the spmenu package also provides In addition to the aforementioned `spmenu_run`, the spmenu package also provides
`spmenu_desktop` which instead of reading $PATH only lists out .desktop entries. `spmenu_desktop` which instead of reading $PATH only lists out .desktop entries.
@ -709,8 +701,7 @@ icon for entries that use one.
It can be configured through editing `~/.config/spmenu/desktop/config`. The It can be configured through editing `~/.config/spmenu/desktop/config`. The
configuration file can also be moved by setting `${XDG_CONFIG_HOME}`. configuration file can also be moved by setting `${XDG_CONFIG_HOME}`.
spmenu commands ## spmenu commands
===============
spmenu has a few special commands. These work similar to the images. For example spmenu has a few special commands. These work similar to the images. For example
to list the version, in addition to the `--version` argument you can also simply to list the version, in addition to the `--version` argument you can also simply
@ -726,14 +717,12 @@ run `printf 'spmenu:version' | spmenu`. There are a few of these.
: Print a test script for spmenu which tests various features. Report any : Print a test script for spmenu which tests various features. Report any
weird issues you may have. weird issues you may have.
License ## License
=======
spmenu is licensed under the MIT license because that's the original suckless spmenu is licensed under the MIT license because that's the original suckless
license. See the included LICENSE file for more information. license. See the included LICENSE file for more information.
Reporting issues ## Reporting issues
================
Please report issues on the Please report issues on the
[Codeberg repository](https://codeberg.org/speedie/speediegq) or alternatively [Codeberg repository](https://codeberg.org/speedie/speediegq) or alternatively

48
spmenu.1
View file

@ -20,8 +20,9 @@
.PP .PP
spmenu is a program for X11 that reads standard input and allows the spmenu is a program for X11 that reads standard input and allows the
user to select items separated by a newline. user to select items separated by a newline.
It is a fork of suckless\[cq]s dmenu (https://tools.suckless.org/dmenu) It\[cq]s a fork of suckless\[cq]s
which is a good more minimal alternative to spmenu. dmenu (https://tools.suckless.org/dmenu) which is a good more minimal
alternative to spmenu.
.PP .PP
What makes spmenu different from all the dmenu forks is that spmenu has What makes spmenu different from all the dmenu forks is that spmenu has
features like color support, Vim-like modes, image support, proper features like color support, Vim-like modes, image support, proper
@ -29,7 +30,7 @@ mouse/keybind configuration, and more.
.PP .PP
It should be noted that most of these features may be disabled by the It should be noted that most of these features may be disabled by the
user, either during compile time or through configuration. user, either during compile time or through configuration.
.SH Usage .SS Usage
.PP .PP
On runtime, spmenu reads from standard input (stdin). On runtime, spmenu reads from standard input (stdin).
spmenu items are separated by a newline (\f[V]\[rs]n\f[R]). spmenu items are separated by a newline (\f[V]\[rs]n\f[R]).
@ -45,7 +46,7 @@ This can be used in shell scripts to create interactive menus.
On top of this, you can specify arguments to change the behavior of On top of this, you can specify arguments to change the behavior of
spmenu. spmenu.
See a list below for a list. See a list below for a list.
.SH Arguments .SS Arguments
.PP .PP
You may use long, descriptive arguments or the shorter arguments. You may use long, descriptive arguments or the shorter arguments.
.TP .TP
@ -490,10 +491,17 @@ Set the selected background color
.TP .TP
\f[V]-sf color\f[R] \f[V]-sf color\f[R]
Set the selected foreground color Set the selected foreground color
.SH Keybinds .SS Keybinds
.PP .PP
See \f[V]keybinds.h\f[R] for a list. You can set keybinds through the config file.
.SH Modes A default config file is available after installing spmenu.
This configuration file has identical keybindings to the default
hardcoded keybinds.
.PP
By default, the configuration file will ignore all hardcoded keybindings
to prevent keybind conflicts, but if you do not like this behaviour you
can simply set \f[V]ignoreglobalkeys = 1\f[R].
.SS Modes
.PP .PP
One of the features that separate spmenu from dmenu is spmenu\[cq]s One of the features that separate spmenu from dmenu is spmenu\[cq]s
different modes. different modes.
@ -514,13 +522,13 @@ When you are in insert mode, you filter items by typing text into the
field. field.
Once you\[cq]re done with insert mode, you can press Escape to enter Once you\[cq]re done with insert mode, you can press Escape to enter
normal mode again. normal mode again.
.SH -p option .SS -p option
.PP .PP
spmenu has a -p option, which stands for prompt. spmenu has a -p option, which stands for prompt.
It allows you to specify text to display next to the item list. It allows you to specify text to display next to the item list.
It is displayed on the left side of the spmenu window. It is displayed on the left side of the spmenu window.
It should be noted that the prompt is purely visual though. It should be noted that the prompt is purely visual though.
.SH Images .SS Images
.PP .PP
spmenu supports drawing images. spmenu supports drawing images.
This image is placed on the left side of the menu window. This image is placed on the left side of the menu window.
@ -542,7 +550,7 @@ There are also a few image related arguments, such as:
\f[V]-ic\f[R], \f[V]-itc\f[R] and \f[V]-gc\f[R]. \f[V]-ic\f[R], \f[V]-itc\f[R] and \f[V]-gc\f[R].
.PP .PP
NOTE: Vector images (such as .svg) can be displayed too. NOTE: Vector images (such as .svg) can be displayed too.
.SH Colored text .SS Colored text
.PP .PP
spmenu supports colored text through SGR sequences. spmenu supports colored text through SGR sequences.
This is the same colors that you might already be using in your shell This is the same colors that you might already be using in your shell
@ -561,7 +569,7 @@ For 256 color support to work, you must add to the array.
See \f[V]libs/color.h\f[R] if you want this. See \f[V]libs/color.h\f[R] if you want this.
.PP .PP
See `SGR sequences' for more information. See `SGR sequences' for more information.
.SH SGR sequences .SS SGR sequences
.PP .PP
A basic supported SGR sequence looks like this: \f[V]\[rs]033[X;YZm\f[R] A basic supported SGR sequence looks like this: \f[V]\[rs]033[X;YZm\f[R]
.PP .PP
@ -590,7 +598,7 @@ Just as a tip, you can pipe your colored spmenu output to
\f[V]sed -e \[aq]s/\[rs]x1b\[rs][[0-9;]*m//g\[aq]\f[R]. \f[V]sed -e \[aq]s/\[rs]x1b\[rs][[0-9;]*m//g\[aq]\f[R].
This will clear the SGR sequences from the output. This will clear the SGR sequences from the output.
This is useful when you want to check what the output actually is. This is useful when you want to check what the output actually is.
.SH Pango markup .SS Pango markup
.PP .PP
If spmenu was compiled with Pango enabled (default), you should be able If spmenu was compiled with Pango enabled (default), you should be able
to utilize Pango markup in every part of spmenu. to utilize Pango markup in every part of spmenu.
@ -638,7 +646,7 @@ For example:
.PP .PP
See this page (https://docs.gtk.org/Pango/pango_markup.html) for more See this page (https://docs.gtk.org/Pango/pango_markup.html) for more
information. information.
.SH Configuration .SS Configuration
.PP .PP
Unlike dmenu, spmenu has a configuration file which can be edited by Unlike dmenu, spmenu has a configuration file which can be edited by
hand. hand.
@ -652,7 +660,7 @@ This configuration file is loaded on startup.
.PP .PP
You can also include other configuration files in the configuration file You can also include other configuration files in the configuration file
using \f[V]\[at]include \[dq]path/to/config\[dq]\f[R]. using \f[V]\[at]include \[dq]path/to/config\[dq]\f[R].
.SH .Xresources .SS .Xresources
.PP .PP
spmenu also has .Xresources (xrdb) support built in. spmenu also has .Xresources (xrdb) support built in.
It reads the xrdb (.Xresources database) on runtime. It reads the xrdb (.Xresources database) on runtime.
@ -668,7 +676,7 @@ Of course, you don\[cq]t NEED to use them, as you can just
You can also use wildcards (such as \f[V]*\f[R]) to achieve a global You can also use wildcards (such as \f[V]*\f[R]) to achieve a global
colorscheme. colorscheme.
Programs like \f[V]pywal\f[R] do this to apply universal colorschemes. Programs like \f[V]pywal\f[R] do this to apply universal colorschemes.
.SH Profiles .SS Profiles
.PP .PP
spmenu supports profiles. spmenu supports profiles.
Profiles are like configuration files (See \f[V]Configuration\f[R]) that Profiles are like configuration files (See \f[V]Configuration\f[R]) that
@ -704,7 +712,7 @@ setting in the profile used before will be used in place.
There are a few color schemes for spmenu included in the repository, see There are a few color schemes for spmenu included in the repository, see
the \f[V]themes/\f[R] directory. the \f[V]themes/\f[R] directory.
Feel free to copy those to your profile directory. Feel free to copy those to your profile directory.
.SH Run launcher .SS Run launcher
.PP .PP
spmenu includes a shell script called spmenu_run. spmenu includes a shell script called spmenu_run.
It lists executable programs in $PATH and displays them to the user in a It lists executable programs in $PATH and displays them to the user in a
@ -740,7 +748,7 @@ Same goes for magnet links.
You can also configure the run launcher through editing You can also configure the run launcher through editing
\f[V]\[ti]/.config/spmenu/run/config\f[R] which is configured in shell \f[V]\[ti]/.config/spmenu/run/config\f[R] which is configured in shell
syntax. syntax.
.SH spmenu_desktop .SS spmenu_desktop
.PP .PP
In addition to the aforementioned \f[V]spmenu_run\f[R], the spmenu In addition to the aforementioned \f[V]spmenu_run\f[R], the spmenu
package also provides \f[V]spmenu_desktop\f[R] which instead of reading package also provides \f[V]spmenu_desktop\f[R] which instead of reading
@ -753,7 +761,7 @@ It can be configured through editing
\f[V]\[ti]/.config/spmenu/desktop/config\f[R]. \f[V]\[ti]/.config/spmenu/desktop/config\f[R].
The configuration file can also be moved by setting The configuration file can also be moved by setting
\f[V]${XDG_CONFIG_HOME}\f[R]. \f[V]${XDG_CONFIG_HOME}\f[R].
.SH spmenu commands .SS spmenu commands
.PP .PP
spmenu has a few special commands. spmenu has a few special commands.
These work similar to the images. These work similar to the images.
@ -771,12 +779,12 @@ Print the spmenu license
\f[V]spmenu:test\f[R] \f[V]spmenu:test\f[R]
Print a test script for spmenu which tests various features. Print a test script for spmenu which tests various features.
Report any weird issues you may have. Report any weird issues you may have.
.SH License .SS License
.PP .PP
spmenu is licensed under the MIT license because that\[cq]s the original spmenu is licensed under the MIT license because that\[cq]s the original
suckless license. suckless license.
See the included LICENSE file for more information. See the included LICENSE file for more information.
.SH Reporting issues .SS Reporting issues
.PP .PP
Please report issues on the Codeberg Please report issues on the Codeberg
repository (https://codeberg.org/speedie/speediegq) or alternatively repository (https://codeberg.org/speedie/speediegq) or alternatively

43
spmenu.html
View file

@ -170,7 +170,7 @@
</header> </header>
<h1 id="spmenu">spmenu</h1> <h1 id="spmenu">spmenu</h1>
<p>spmenu is a program for X11 that reads standard input and allows the <p>spmenu is a program for X11 that reads standard input and allows the
user to select items separated by a newline. It is a fork of <a user to select items separated by a newline. It’s a fork of <a
href="https://tools.suckless.org/dmenu">suckless’s dmenu</a> which is a href="https://tools.suckless.org/dmenu">suckless’s dmenu</a> which is a
good more minimal alternative to spmenu.</p> good more minimal alternative to spmenu.</p>
<p>What makes spmenu different from all the dmenu forks is that spmenu <p>What makes spmenu different from all the dmenu forks is that spmenu
@ -178,7 +178,7 @@ has features like color support, Vim-like modes, image support, proper
mouse/keybind configuration, and more.</p> mouse/keybind configuration, and more.</p>
<p>It should be noted that most of these features may be disabled by the <p>It should be noted that most of these features may be disabled by the
user, either during compile time or through configuration.</p> user, either during compile time or through configuration.</p>
<h1 id="usage">Usage</h1> <h2 id="usage">Usage</h2>
<p>On runtime, spmenu reads from standard input (stdin). spmenu items <p>On runtime, spmenu reads from standard input (stdin). spmenu items
are separated by a newline (<code>\n</code>). When (by default) Enter is are separated by a newline (<code>\n</code>). When (by default) Enter is
pressed, the selected item will be piped to stdout.</p> pressed, the selected item will be piped to stdout.</p>
@ -188,7 +188,7 @@ spawn an spmenu window with three items, ‘Apple’, ‘Orange’ and ‘Pear
This can be used in shell scripts to create interactive menus.</p> This can be used in shell scripts to create interactive menus.</p>
<p>On top of this, you can specify arguments to change the behavior of <p>On top of this, you can specify arguments to change the behavior of
spmenu. See a list below for a list.</p> spmenu. See a list below for a list.</p>
<h1 id="arguments">Arguments</h1> <h2 id="arguments">Arguments</h2>
<p>You may use long, descriptive arguments or the shorter arguments.</p> <p>You may use long, descriptive arguments or the shorter arguments.</p>
<dl> <dl>
<dt><code>-mh, --line-height height</code></dt> <dt><code>-mh, --line-height height</code></dt>
@ -779,9 +779,14 @@ Set the selected background color
Set the selected foreground color Set the selected foreground color
</dd> </dd>
</dl> </dl>
<h1 id="keybinds">Keybinds</h1> <h2 id="keybinds">Keybinds</h2>
<p>See <code>keybinds.h</code> for a list.</p> <p>You can set keybinds through the config file. A default config file
<h1 id="modes">Modes</h1> is available after installing spmenu. This configuration file has
identical keybindings to the default hardcoded keybinds.</p>
<p>By default, the configuration file will ignore all hardcoded
keybindings to prevent keybind conflicts, but if you do not like this
behaviour you can simply set <code>ignoreglobalkeys = 1</code>.</p>
<h2 id="modes">Modes</h2>
<p>One of the features that separate spmenu from dmenu is spmenu’s <p>One of the features that separate spmenu from dmenu is spmenu’s
different modes. As of version 0.2, there are two modes. Normal mode and different modes. As of version 0.2, there are two modes. Normal mode and
Insert mode. These modes are of course similar to Vim.</p> Insert mode. These modes are of course similar to Vim.</p>
@ -794,12 +799,12 @@ in normal mode. In this mode, most keybinds do nothing. When you are in
insert mode, you filter items by typing text into the field. Once you’re insert mode, you filter items by typing text into the field. Once you’re
done with insert mode, you can press Escape to enter normal mode done with insert mode, you can press Escape to enter normal mode
again.</p> again.</p>
<h1 id="p-option">-p option</h1> <h2 id="p-option">-p option</h2>
<p>spmenu has a -p option, which stands for prompt. It allows you to <p>spmenu has a -p option, which stands for prompt. It allows you to
specify text to display next to the item list. It is displayed on the specify text to display next to the item list. It is displayed on the
left side of the spmenu window. It should be noted that the prompt is left side of the spmenu window. It should be noted that the prompt is
purely visual though.</p> purely visual though.</p>
<h1 id="images">Images</h1> <h2 id="images">Images</h2>
<p>spmenu supports drawing images. This image is placed on the left side <p>spmenu supports drawing images. This image is placed on the left side
of the menu window. To use an image, pipe of the menu window. To use an image, pipe
<code>IMG:/path/to/image</code> to spmenu. If you want you can specify <code>IMG:/path/to/image</code> to spmenu. If you want you can specify
@ -815,7 +820,7 @@ item. In practice, drawing an image might look like this:</p>
<code>-ib</code>, <code>-ic</code>, <code>-itc</code> and <code>-ib</code>, <code>-ic</code>, <code>-itc</code> and
<code>-gc</code>.</p> <code>-gc</code>.</p>
<p>NOTE: Vector images (such as .svg) can be displayed too.</p> <p>NOTE: Vector images (such as .svg) can be displayed too.</p>
<h1 id="colored-text">Colored text</h1> <h2 id="colored-text">Colored text</h2>
<p>spmenu supports colored text through SGR sequences. This is the same <p>spmenu supports colored text through SGR sequences. This is the same
colors that you might already be using in your shell scripts. This means colors that you might already be using in your shell scripts. This means
you can pipe practically any colored shell script straight into spmenu, you can pipe practically any colored shell script straight into spmenu,
@ -827,7 +832,7 @@ except even more useful. Example:
<p>For 256 color support to work, you must add to the array. See <p>For 256 color support to work, you must add to the array. See
<code>libs/color.h</code> if you want this.</p> <code>libs/color.h</code> if you want this.</p>
<p>See ‘SGR sequences’ for more information.</p> <p>See ‘SGR sequences’ for more information.</p>
<h1 id="sgr-sequences">SGR sequences</h1> <h2 id="sgr-sequences">SGR sequences</h2>
<p>A basic supported SGR sequence looks like this: <p>A basic supported SGR sequence looks like this:
<code>\033[X;YZm</code></p> <code>\033[X;YZm</code></p>
<p>Here, X specifies if you want normal or bright colors. Y specifies if <p>Here, X specifies if you want normal or bright colors. Y specifies if
@ -849,7 +854,7 @@ information.</p>
<code>sed -e 's/\x1b\[[0-9;]*m//g'</code>. This will clear the SGR <code>sed -e 's/\x1b\[[0-9;]*m//g'</code>. This will clear the SGR
sequences from the output. This is useful when you want to check what sequences from the output. This is useful when you want to check what
the output actually is.</p> the output actually is.</p>
<h1 id="pango-markup">Pango markup</h1> <h2 id="pango-markup">Pango markup</h2>
<p>If spmenu was compiled with Pango enabled (default), you should be <p>If spmenu was compiled with Pango enabled (default), you should be
able to utilize Pango markup in every part of spmenu. That is, the mode able to utilize Pango markup in every part of spmenu. That is, the mode
indicator, items, input, prompt, etc.</p> indicator, items, input, prompt, etc.</p>
@ -904,7 +909,7 @@ is very easy. For example:
<code>... | spmenu ... | sed 's/&lt;big&gt;//g; s/&lt;/big&gt;//g'</code></p> <code>... | spmenu ... | sed 's/&lt;big&gt;//g; s/&lt;/big&gt;//g'</code></p>
<p>See <a href="https://docs.gtk.org/Pango/pango_markup.html">this <p>See <a href="https://docs.gtk.org/Pango/pango_markup.html">this
page</a> for more information.</p> page</a> for more information.</p>
<h1 id="configuration">Configuration</h1> <h2 id="configuration">Configuration</h2>
<p>Unlike dmenu, spmenu has a configuration file which can be edited by <p>Unlike dmenu, spmenu has a configuration file which can be edited by
hand. It is located in ~/.config/spmenu/spmenu.conf, but you can hand. It is located in ~/.config/spmenu/spmenu.conf, but you can
override this by exporting <code>$XDG_CONFIG_HOME</code>.</p> override this by exporting <code>$XDG_CONFIG_HOME</code>.</p>
@ -914,7 +919,7 @@ override this by exporting <code>$XDG_CONFIG_HOME</code>.</p>
on startup.</p> on startup.</p>
<p>You can also include other configuration files in the configuration <p>You can also include other configuration files in the configuration
file using <code>@include "path/to/config"</code>.</p> file using <code>@include "path/to/config"</code>.</p>
<h1 id="xresources">.Xresources</h1> <h2 id="xresources">.Xresources</h2>
<p>spmenu also has .Xresources (xrdb) support built in. It reads the <p>spmenu also has .Xresources (xrdb) support built in. It reads the
xrdb (.Xresources database) on runtime. You may disable it by passing xrdb (.Xresources database) on runtime. You may disable it by passing
-nxrdb, or enable it by padding -xrdb. You can also set this in the -nxrdb, or enable it by padding -xrdb. You can also set this in the
@ -927,7 +932,7 @@ Of course, you don’t NEED to use them, as you can just
<p>You can also use wildcards (such as <code>*</code>) to achieve a <p>You can also use wildcards (such as <code>*</code>) to achieve a
global colorscheme. Programs like <code>pywal</code> do this to apply global colorscheme. Programs like <code>pywal</code> do this to apply
universal colorschemes.</p> universal colorschemes.</p>
<h1 id="profiles">Profiles</h1> <h2 id="profiles">Profiles</h2>
<p>spmenu supports profiles. Profiles are like configuration files (See <p>spmenu supports profiles. Profiles are like configuration files (See
<code>Configuration</code>) that can be switched between quickly using a <code>Configuration</code>) that can be switched between quickly using a
keybind.</p> keybind.</p>
@ -955,7 +960,7 @@ the setting in the profile used before will be used in place.</p>
<p>There are a few color schemes for spmenu included in the repository, <p>There are a few color schemes for spmenu included in the repository,
see the <code>themes/</code> directory. Feel free to copy those to your see the <code>themes/</code> directory. Feel free to copy those to your
profile directory.</p> profile directory.</p>
<h1 id="run-launcher">Run launcher</h1> <h2 id="run-launcher">Run launcher</h2>
<p>spmenu includes a shell script called spmenu_run. It lists executable <p>spmenu includes a shell script called spmenu_run. It lists executable
programs in $PATH and displays them to the user in a list. Not only that programs in $PATH and displays them to the user in a list. Not only that
but it shows recently run programs first in the list.</p> but it shows recently run programs first in the list.</p>
@ -980,7 +985,7 @@ $BROWSER even without the prefix. Same goes for magnet links.</p>
<p>You can also configure the run launcher through editing <p>You can also configure the run launcher through editing
<code>~/.config/spmenu/run/config</code> which is configured in shell <code>~/.config/spmenu/run/config</code> which is configured in shell
syntax.</p> syntax.</p>
<h1 id="spmenu_desktop">spmenu_desktop</h1> <h2 id="spmenu_desktop">spmenu_desktop</h2>
<p>In addition to the aforementioned <code>spmenu_run</code>, the spmenu <p>In addition to the aforementioned <code>spmenu_run</code>, the spmenu
package also provides <code>spmenu_desktop</code> which instead of package also provides <code>spmenu_desktop</code> which instead of
reading $PATH only lists out .desktop entries.</p> reading $PATH only lists out .desktop entries.</p>
@ -989,7 +994,7 @@ displaying an icon for entries that use one.</p>
<p>It can be configured through editing <p>It can be configured through editing
<code>~/.config/spmenu/desktop/config</code>. The configuration file can <code>~/.config/spmenu/desktop/config</code>. The configuration file can
also be moved by setting <code>${XDG_CONFIG_HOME}</code>.</p> also be moved by setting <code>${XDG_CONFIG_HOME}</code>.</p>
<h1 id="spmenu-commands">spmenu commands</h1> <h2 id="spmenu-commands">spmenu commands</h2>
<p>spmenu has a few special commands. These work similar to the images. <p>spmenu has a few special commands. These work similar to the images.
For example to list the version, in addition to the For example to list the version, in addition to the
<code>--version</code> argument you can also simply run <code>--version</code> argument you can also simply run
@ -1010,11 +1015,11 @@ Print a test script for spmenu which tests various features. Report any
weird issues you may have. weird issues you may have.
</dd> </dd>
</dl> </dl>
<h1 id="license">License</h1> <h2 id="license">License</h2>
<p>spmenu is licensed under the MIT license because that’s the original <p>spmenu is licensed under the MIT license because that’s the original
suckless license. See the included LICENSE file for more suckless license. See the included LICENSE file for more
information.</p> information.</p>
<h1 id="reporting-issues">Reporting issues</h1> <h2 id="reporting-issues">Reporting issues</h2>
<p>Please report issues on the <a <p>Please report issues on the <a
href="https://codeberg.org/speedie/speediegq">Codeberg repository</a> or href="https://codeberg.org/speedie/speediegq">Codeberg repository</a> or
alternatively email me.</p> alternatively email me.</p>

BIN
spmenu.pdf
View file

Binary file not shown.