summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/vtcol.rst163
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>`.
+