fill in manpage

1 files changed, 152 insertions, 11 deletions

diff --git a/doc/vtcol.rst b/doc/vtcol.rst
index 860cde4..2e3c533 100644
--- a/doc/vtcol.rst
+++ b/doc/vtcol.rst
@@ -3,30 +3,171 @@
 ===============================================================================
 
 *******************************************************************************
-                  Set the color scheme of the virtual console
+                     color schemes for the Linux™ console 
 *******************************************************************************
 
-
-:Date:                  2017-01-22
-:Copyright:             GPL v3.0
-:Version:               0.42.2
+:Date:                  2021-11-10
+:Version:               0.42.5
 :Manual section:        1
 :Manual group:          console
 
-NAME
+Synopsis
+-------------------------------------------------------------------------------
+
+**vtcol** [--help] [--version] [--verbose] <command> [<args>]
+
+Description
+-------------------------------------------------------------------------------
+
+**vtcol** manipulates and inspects the color map of the Linux console
+using ``ioctl_console(2)`` syscalls.
+
+vtcol commands
+-------------------------------------------------------------------------------
+
+``vtcol`` actions are provided by these these subcommands:
+
+**help**
+
+    Prints this message or the help of the given subcommand(s)
+
+
+**set**
+
+    Set the scheme for the current terminal with ``PIO_CMAP``. ::
+
+        $ vtcol set solarized
+
+**list**
+
+    List predefined schemes. ::
+
+        $ vtcol list
+        4 color schemes available:
+              * solarized
+              * solarized_light
+              * default
+              * phosphor
+
+    These are only the schemes built into the ``vtcol`` binary. Any
+    other scheme can be loaded using the ``--file`` argument.
+
+**dump**
+
+    Print the palette of the specified scheme in more or less human readable
+    representation.
+
+**get**
+
+    Get the current color scheme with ``GIO_CMAP``. The result is matched
+    against the builtin schemes; if a scheme matches, only its preferred name
+    is printed (e. g. ``solarized_light``). ::
+
+        $ vtcol get
+        solarized
+
+    Otherwise the palette is printed as with the ``dump`` subcommand.
+
+**toggle**
+
+    Like ``vtcol 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
+    loaded, otherwise the first one. The effect is that in repeated invocations
+    of the same command the scheme is toggled between the two arguments. E. g.
+    use: ::
+
+        $ vtcol toggle solarized solarized_light
+
+    to cycle the console palette between “dark mode” and “light mode”.
+
+set options
+-------------------------------------------------------------------------------
+::
+
+    vtcol set [--file FILE]
+
+    vtcol set [SCHEME]
+
+``SCHEME``
+
+    Load the predefined color scheme *SCHEME*. For a list of options, use
+    ``vtcol list``. Alternatively, ``-`` can be used to specify *stdin*.
+
+``-f FILE, --file FILE``
+
+    Load color scheme from *FILE* which can be a filesystem path or the special
+    argument ``-`` to specify *stdin*.
+
+    Mutually exclusive with *SCHEME*.
+
+toggle options
 -------------------------------------------------------------------------------
 
-SYNOPSIS
+`vtcol toggle ONE TWO``
+
+``ONE``
+
+    First scheme to alternate between. Will be loaded *unless* it is the active
+    scheme.
+
+``TWO``
+
+    Second scheme to alternate between. Will be loaded if *ONE* is the active
+    scheme.
+
+Scheme file syntax overview
 -------------------------------------------------------------------------------
 
-DESCRIPTION
+.. TODO:: unimplemented!()
+
+Examples
 -------------------------------------------------------------------------------
 
-OPTIONS
+1. Get the current color scheme: ::
+
+    $ vtcol get
+
+2. Turn your screen into an 80s style monochrome lookalike: ::
+
+    $ vtcol set phosphor
+
+3. Reset console to default colors: ::
+
+    $ vtcol set default
+
+4. Set color scheme from stdin: ::
+
+    $ <./schemes/zebra vtcol set -
+
+5. List available builtin schemes: ::
+
+    $ vtcol list
+
+6. Cycle between night mode and day mode: ::
+
+    $ vtcol toggle solarized solarized_light
+
+Copyright
 -------------------------------------------------------------------------------
 
-SEE ALSO
+Copyright: 2015-2021 Philipp Gesang
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License.
+
+See also
 -------------------------------------------------------------------------------
 
-AUTHORS
+**ioctl_console**\(2), **tty**\(4)
+
+The ``setcolors`` utility should be considered prior art, visit
+`<https://github.com/EvanPurkhiser/linux-vt-setcolors>`.
+
+Notes
 -------------------------------------------------------------------------------
+
+Upstream resides at `<https://gitlab.com/phgsgng/vtcol>`.
+