Better document SGR sequences

docs/docs.md

@@ -673,34 +673,54 @@ for more information.
 
 ## SGR sequences
 
-A basic supported SGR sequence looks like this: `\033[X;YZm`
+SGR sequences (ANSI escape codes) can be used to set the color of spmenu items. Here's
+a simple table of good SGR sequences. Note that sequences can also be combined,
+and that this isn't the only way to format them.
 
-Here, X specifies if you want normal or bright colors. Y specifies if you
+| Sequence           | Description                                                                       |
-want background or foreground. Z specifies the color number. You can add
+| :----------------- | :-------------------------------------------------------------------------------- |
-another separator and background color before Z to also specify a background
+| \033[0m            | Reset foreground and background color and alpha                                   |
-color.
+| \033[0;3nm         | Set foreground color to normal color index 'n' (0-7)                              |
+| \033[1;3nm         | Set foreground color to bright color index 'n' (0-7)                              |
+| \033[0;4nm         | Set background color to normal color index 'n' (0-7)                              |
+| \033[1;4nm         | Set background color to bright color index 'n' (0-7)                              |
+| \033[38;2;r;g;bm   | Set foreground color to a specified RGB color, r is red, g is green, b is blue    |
+| \033[48;2;r;g;bm   | Set background color to a specified RGB color, r is red, g is green, b is blue    |
+| \033[38;5;nm       | Set foreground color to color index 'n' (0-256)                                   |
+| \033[48;5;nm       | Set background color to color index 'n' (0-256)                                   |
+| \033[39m           | Reset foreground color and alpha                                                  |
+| \033[49m           | Reset background color and alpha                                                  |
+| ;                  | Semicolon is used as a separator                                                  |
+| m                  | Ends the sequence                                                                 |
 
-Foreground colors: `30` through `37`
+Other sequences *may* be supported but are not listed here. In any case, this allows
-Background colors: `40` through `47`
+for all RGB colors to be theoretically used all at the same time.
-Reset: `0`
 
-NOTE: `;` is a separator, and in this example it separates the
+For example, to set the foreground color to red and print 'Hello world',
-color number and normal/bright. \033 may also be written as `^]` or simply `ESC`.
+one could do the following: `printf '\033[0;31mHello world\n" | spmenu`
-The separator may be omitted for some sequences, such as `\033[0m` which
+This will set the foreground color to `sgr1` in the config/theme file.
-resets the colorscheme.
+You can do this for `sgr0` through `sgr7`. To access `sgr8` through `sgr15`
+you use `\033[1` rather than `\033[0`, specifying that you want bright
+colors to be used.
 
-spmenu supports most color sequences, although not true color by default
+As for 256 colors, you simply specify a value between 0 and 256. These colors
-(unless -sgr arguments are used).
+are built into spmenu and cannot be overridden. They are only really implemented
+into spmenu for compatibility, in practice you should use true color sequences
+instead, as they are much more flexible.
 
-There are a few arguments, you can override SGR colors on-the-fly
+True color is slightly more complicated. For example, to print black text on a
-using the `-sgrX` arguments. See 'Arguments' for more information.
+white background, one could do something like this:
+`printf "\033[48;2;255;255;255;38;2;0;0;0mTest\033[0m\n" | spmenu`
 
-Just as a tip, you can pipe your colored spmenu output to
+This might look confusing if you aren't familiar with these sequences, but it's fairly
-`sed -e 's/\x1b\[[0-9;]*m//g'`. This will clear the SGR sequences from
+simple. First we set the background color and specify that this is a true color
-the output. This is useful when you want to check what the output actually is.
+sequence. (`48;2`) Then we set the red, green and blue channel to fully
+opaque (`255;255;255` for red;green;blue), resulting in white. Then we repeat this
+for a foreground color (`38;2`) but replace `255` with `0`, which results in
+black. Do however note that you don't need to specify *both* a foreground and
+background color.
 
-256 color sequences are also supported, but due to the complexity involved, they
+**Note: Background colors will used until a reset sequence is found.**
-will not be covered in this man page.
 
 ## Pango markup and text formatting
 

spmenu.1

@@ -722,38 +722,128 @@ It should be noted that font sequences are not yet supported.
 See `SGR sequences' for more information.
 .SS SGR sequences
 .PP
-A basic supported SGR sequence looks like this: \f[V]\[rs]033[X;YZm\f[R]
+SGR sequences (ANSI escape codes) can be used to set the color of spmenu
+items.
+Here\[cq]s a simple table of good SGR sequences.
+Note that sequences can also be combined, and that this isn\[cq]t the
+only way to format them.
 .PP
-Here, X specifies if you want normal or bright colors.
+.TS
-Y specifies if you want background or foreground.
+tab(@);
-Z specifies the color number.
+lw(12.7n) lw(57.3n).
-You can add another separator and background color before Z to also
+T{
-specify a background color.
+Sequence
+T}@T{
+Description
+T}
+_
+T{
+\[rs]033[0m
+T}@T{
+Reset foreground and background color and alpha
+T}
+T{
+\[rs]033[0;3nm
+T}@T{
+Set foreground color to normal color index `n' (0-7)
+T}
+T{
+\[rs]033[1;3nm
+T}@T{
+Set foreground color to bright color index `n' (0-7)
+T}
+T{
+\[rs]033[0;4nm
+T}@T{
+Set background color to normal color index `n' (0-7)
+T}
+T{
+\[rs]033[1;4nm
+T}@T{
+Set background color to bright color index `n' (0-7)
+T}
+T{
+\[rs]033[38;2;r;g;bm
+T}@T{
+Set foreground color to a specified RGB color, r is red, g is green, b
+is blue
+T}
+T{
+\[rs]033[48;2;r;g;bm
+T}@T{
+Set background color to a specified RGB color, r is red, g is green, b
+is blue
+T}
+T{
+\[rs]033[38;5;nm
+T}@T{
+Set foreground color to color index `n' (0-256)
+T}
+T{
+\[rs]033[48;5;nm
+T}@T{
+Set background color to color index `n' (0-256)
+T}
+T{
+\[rs]033[39m
+T}@T{
+Reset foreground color and alpha
+T}
+T{
+\[rs]033[49m
+T}@T{
+Reset background color and alpha
+T}
+T{
+;
+T}@T{
+Semicolon is used as a separator
+T}
+T{
+m
+T}@T{
+Ends the sequence
+T}
+.TE
 .PP
-Foreground colors: \f[V]30\f[R] through \f[V]37\f[R] Background colors:
+Other sequences \f[I]may\f[R] be supported but are not listed here.
-\f[V]40\f[R] through \f[V]47\f[R] Reset: \f[V]0\f[R]
+In any case, this allows for all RGB colors to be theoretically used all
+at the same time.
 .PP
-NOTE: \f[V];\f[R] is a separator, and in this example it separates the
+For example, to set the foreground color to red and print `Hello world',
-color number and normal/bright.
+one could do the following:
-\[rs]033 may also be written as \f[V]\[ha]]\f[R] or simply
+\f[V]printf \[aq]\[rs]033[0;31mHello world\[rs]n\[dq] | spmenu\f[R] This
-\f[V]ESC\f[R].
+will set the foreground color to \f[V]sgr1\f[R] in the config/theme
-The separator may be omitted for some sequences, such as
+file.
-\f[V]\[rs]033[0m\f[R] which resets the colorscheme.
+You can do this for \f[V]sgr0\f[R] through \f[V]sgr7\f[R].
+To access \f[V]sgr8\f[R] through \f[V]sgr15\f[R] you use
+\f[V]\[rs]033[1\f[R] rather than \f[V]\[rs]033[0\f[R], specifying that
+you want bright colors to be used.
 .PP
-spmenu supports most color sequences, although not true color by default
+As for 256 colors, you simply specify a value between 0 and 256.
-(unless -sgr arguments are used).
+These colors are built into spmenu and cannot be overridden.
+They are only really implemented into spmenu for compatibility, in
+practice you should use true color sequences instead, as they are much
+more flexible.
 .PP
-There are a few arguments, you can override SGR colors on-the-fly using
+True color is slightly more complicated.
-the \f[V]-sgrX\f[R] arguments.
+For example, to print black text on a white background, one could do
-See `Arguments' for more information.
+something like this:
+\f[V]printf \[dq]\[rs]033[48;2;255;255;255;38;2;0;0;0mTest\[rs]033[0m\[rs]n\[dq] | spmenu\f[R]
 .PP
-Just as a tip, you can pipe your colored spmenu output to
+This might look confusing if you aren\[cq]t familiar with these
-\f[V]sed -e \[aq]s/\[rs]x1b\[rs][[0-9;]*m//g\[aq]\f[R].
+sequences, but it\[cq]s fairly simple.
-This will clear the SGR sequences from the output.
+First we set the background color and specify that this is a true color
-This is useful when you want to check what the output actually is.
+sequence.
+(\f[V]48;2\f[R]) Then we set the red, green and blue channel to fully
+opaque (\f[V]255;255;255\f[R] for red;green;blue), resulting in white.
+Then we repeat this for a foreground color (\f[V]38;2\f[R]) but replace
+\f[V]255\f[R] with \f[V]0\f[R], which results in black.
+Do however note that you don\[cq]t need to specify \f[I]both\f[R] a
+foreground and background color.
 .PP
-256 color sequences are also supported, but due to the complexity
+\f[B]Note: Background colors will used until a reset sequence is
-involved, they will not be covered in this man page.
+found.\f[R]
 .SS Pango markup and text formatting
 .PP
 Because spmenu uses Pango and Cairo for text drawing, Pango markup can