From f2bcdd724a45cc31ec86d799ff3e8a6f340ccdac Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Sun, 12 Dec 2021 00:11:03 +0100
Subject: doc: update manpage for colors/leds split

---
 doc/vtcol.rst | 111 +++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 91 insertions(+), 20 deletions(-)

diff --git a/doc/vtcol.rst b/doc/vtcol.rst
index 2e3c533..8531a18 100644
--- a/doc/vtcol.rst
+++ b/doc/vtcol.rst
@@ -6,8 +6,8 @@
                      color schemes for the Linux™ console 
 *******************************************************************************
 
-:Date:                  2021-11-10
-:Version:               0.42.5
+:Date:                  2021-12-11
+:Version:               0.42.6
 :Manual section:        1
 :Manual group:          console
 
@@ -25,24 +25,35 @@ using ``ioctl_console(2)`` syscalls.
 vtcol commands
 -------------------------------------------------------------------------------
 
-``vtcol`` actions are provided by these these subcommands:
+``vtcol`` actions are grouped into subcommands depending on the functionality
+they operate on:
 
 **help**
 
     Prints this message or the help of the given subcommand(s)
 
+**colors**
+
+    Inspect and manipulate the console palette.
+
+**leds**
+
+    Keyboad LED state.
+
+vtcol colors commands
+#####################
 
 **set**
 
     Set the scheme for the current terminal with ``PIO_CMAP``. ::
 
-        $ vtcol set solarized
+        $ vtcol colors set solarized
 
 **list**
 
     List predefined schemes. ::
 
-        $ vtcol list
+        $ vtcol colors list
         4 color schemes available:
               * solarized
               * solarized_light
@@ -63,14 +74,14 @@ vtcol commands
     against the builtin schemes; if a scheme matches, only its preferred name
     is printed (e. g. ``solarized_light``). ::
 
-        $ vtcol get
+        $ vtcol colors get
         solarized
 
     Otherwise the palette is printed as with the ``dump`` subcommand.
 
 **toggle**
 
-    Like ``vtcol set`` but supports two ``SCHEME`` arguments.
+    Like ``vtcol colors set`` but supports two ``SCHEME`` arguments.
 
     First the active scheme is checked against *the first positional argument*;
     if there is a match, the scheme specified by the *second argument* will be
@@ -78,22 +89,43 @@ vtcol commands
     of the same command the scheme is toggled between the two arguments. E. g.
     use: ::
 
-        $ vtcol toggle solarized solarized_light
+        $ vtcol colors toggle solarized solarized_light
 
     to cycle the console palette between “dark mode” and “light mode”.
 
-set options
+**fade**
+
+    Transition between two color schemes with a fading effect. If no starting
+    color scheme is specified, the current one is used. ::
+
+        $ vtcol colors fade --ms 1337 --from solarized --to solarized_light
+
+vtcol leds commands
+###################
+
+**get**
+
+    Get the current led state. Example: ::
+
+        $ vtcol leds get
+        caps: false, num: false, scroll: false
+
+**set**
+
+.. TODO:: unimplemented!()
+
+colors set options
 -------------------------------------------------------------------------------
 ::
 
-    vtcol set [--file FILE]
+    vtcol colors set [--file FILE]
 
-    vtcol set [SCHEME]
+    vtcol colors set [SCHEME]
 
 ``SCHEME``
 
     Load the predefined color scheme *SCHEME*. For a list of options, use
-    ``vtcol list``. Alternatively, ``-`` can be used to specify *stdin*.
+    ``vtcol colors list``. Alternatively, ``-`` can be used to specify *stdin*.
 
 ``-f FILE, --file FILE``
 
@@ -102,10 +134,10 @@ set options
 
     Mutually exclusive with *SCHEME*.
 
-toggle options
+colors toggle options
 -------------------------------------------------------------------------------
 
-`vtcol toggle ONE TWO``
+`vtcol colors toggle ONE TWO``
 
 ``ONE``
 
@@ -117,6 +149,37 @@ toggle options
     Second scheme to alternate between. Will be loaded if *ONE* is the active
     scheme.
 
+colors fade options
+-------------------------------------------------------------------------------
+::
+
+    vtcol colors fade [--clear] [--frequency HZ] [--ms MS]
+                      [--from START] --to END
+
+``END``
+
+    The scheme to transition to. After completion this will remain the active
+    scheme of the current console.
+
+``START``
+
+    Load the predefined color scheme *SCHEME* before starting the transition.
+
+``-f HZ, --frequency HZ``
+
+    Screen update rate in ``HZ / s``.
+
+``-m MS, --ms MS``
+
+    Duration of the transition in milliseconds.
+
+``-c, --clear``
+
+    Whether to clear the console after each update step. This causes the
+    background color to be applied to the entire screen and not just the parts
+    that changed for a more uniform transition. The downside of ``--clear`` is
+    that all text is erased as well.
+
 Scheme file syntax overview
 -------------------------------------------------------------------------------
 
@@ -127,27 +190,35 @@ Examples
 
 1. Get the current color scheme: ::
 
-    $ vtcol get
+    $ vtcol colors get
 
 2. Turn your screen into an 80s style monochrome lookalike: ::
 
-    $ vtcol set phosphor
+    $ vtcol colors set phosphor
 
 3. Reset console to default colors: ::
 
-    $ vtcol set default
+    $ vtcol colors set default
 
 4. Set color scheme from stdin: ::
 
-    $ <./schemes/zebra vtcol set -
+    $ <./schemes/zebra vtcol colors set -
 
 5. List available builtin schemes: ::
 
-    $ vtcol list
+    $ vtcol colors list
 
 6. Cycle between night mode and day mode: ::
 
-    $ vtcol toggle solarized solarized_light
+    $ vtcol colors toggle solarized solarized_light
+
+7. Transition from dark to light scheme while dumping some data for effect: ::
+
+    $ vtcol colors fade -m 1500 -f solarized -t solarized_light & dmesg
+
+8. Dump current scheme in binary form: ::
+
+    $ vtcol colors get --base64
 
 Copyright
 -------------------------------------------------------------------------------
-- 
cgit v1.2.3