From bde34d81fb2def42f14fce262e49ffa6e6df09b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Ekl=C3=B6f?= Date: Sun, 21 Apr 2019 20:24:21 +0200 Subject: [PATCH] wip: man pages --- doc/CMakeLists.txt | 1 + doc/f00bar-decorations.5.scd | 91 +++++++++++++++++++++++++++++ doc/f00bar-particles.5.scd | 108 +++++++++++++++++++++++++---------- 3 files changed, 169 insertions(+), 31 deletions(-) create mode 100644 doc/f00bar-decorations.5.scd diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index c551a61..8b4d486 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -35,4 +35,5 @@ add_man_pages( f00bar-module-alsa.5.scd f00bar-particles.5.scd + f00bar-decorations.5.scd ) diff --git a/doc/f00bar-decorations.5.scd b/doc/f00bar-decorations.5.scd new file mode 100644 index 0000000..8c60eba --- /dev/null +++ b/doc/f00bar-decorations.5.scd @@ -0,0 +1,91 @@ +f00bar-decorations(5) + +# NAME +f00bar-decorations - configuration file + +# DESCRIPTION + +Decorations are optional additions to particles, enabling you to +e.g. change the background color of the entire particle, draw an +underline and so on. + +Decorations are applied to the particle's margins as well. + +All decorations define their own configuration attributes, and there +are no common attributes. + +# BACKGROUND + +This decoration sets the particles background color. + +## CONFIGURATION + +[[ *Name* +:[ *Type* +:[ *Req* +:[ *Description* +| color +: color +: yes +: The background color. See *f00bar*(5) for format. + +## EXAMPLES + +``` +content: + string: + deco: + background: + color: 00ff00ff +``` + +# UNDERLINE + +This decoration renders a line of configurable size and color at the +bottom of the particle. + +## CONFIGURATION + +[[ *Name* +:[ *Type* +:[ *Req* +:[ *Description* +| size +: int +: yes +: The size (height/thickness) of the line, in pixels +| color +: color +: yes +: The color of the line. See *f00bar*(5) for format. + +## EXAMPLES + +``` +content: + string: + deco: + underline: + size: 2 + color: ff0000ff +``` + +# STACK + +This particles combines multiple decorations. + +## CONFIGURATION + +No configuration attributes available. The _stack_ is just a *list* of +the decorations that should be combined. + +## EXAMPLES + +``` +content: + string: + deco: + stack: + - background: ... + - underline: ... +``` diff --git a/doc/f00bar-particles.5.scd b/doc/f00bar-particles.5.scd index f38080f..5a4c2bf 100644 --- a/doc/f00bar-particles.5.scd +++ b/doc/f00bar-particles.5.scd @@ -47,8 +47,6 @@ following attributes are supported by all particles: # STRING -## DESCRIPTION - This is the most basic particle. It takes a format string, consisting of free text mixed with tag specifiers. @@ -83,8 +81,6 @@ content: # EMPTY -## DESCRIPTION - This particle is a place-holder. While it does not render any tags, margins and decortions are rendered. @@ -101,31 +97,11 @@ content: # LIST -## DESCRIPTION - This particle is a list (or sequence, if you like) of other particles. It can be used to render e.g. _string_ particles with different font and/or color formatting. Or ay other particle combinations. -There is a short hand for this particle; instead of - -``` -content: - list: - items: - - string: ... - - string: ... -``` - -you can list the items directly: - -``` -content: - - string: ... - - string: ... -``` - But note that this means you *cannot* set any attributes on the _list_ particle itself. @@ -163,9 +139,26 @@ content: - string: {text: world} ``` -# MAP +Many times, the only attribute you need to set is _items_. In this +case, there is a shorter form. Instead of: -## DESCRIPTION +``` +content: + list: + items: + - string: ... + - string: ... +``` + +you can list the items directly: + +``` +content: + - string: ... + - string: ... +``` + +# MAP This particle maps the values of a specific tag to different particles. In addition to explicit tag values, you can also specify a @@ -212,8 +205,6 @@ content: # RAMP -## DESCRIPTION - This particle uses a range tag to index into an array of particles. This can be used for example to map volume to a volume-level icon, or a battery's capacity level to a battery @@ -252,8 +243,63 @@ content: # PROGRESS-BAR -## DESCRIPTION +This particle renders a range tag's value as a progress bar. You +control the looks of it by defining the particles to use for the +progress bar's start and end, it's size, which particles to use for +the range that has been completed, the range that has yet to be +completed, and the particle to use as the progress bar's current value +indicator. -This particle +This particle also supports _realtime_ tags, and will then auto-update +itself when needed. -## EXAMPLES \ No newline at end of file +## CONFIGURATION + +[[ *Name* +:[ *Type* +:[ *Req* +:[ *Description* +| tag +: string +: yes +: The range or realtime tag (name of) which value will be used as the + progress bar's value. +| length +: int +: yes +: The size/length of the progress bar, in characters. Note that the + _start_, _end_ and _indicator_ particles are *not* included. +| start +: particle +: yes +: The progress bar's starting character +| end +: particle +: yes +: The progress bar's ending character +| fill +: particle +: yes +: Particle to use in the completed range +| empty +: particle +: yes +: Particle to use in the not-yet-completed range +| indicator +: particle +: yes +: Particle representing the progress bar's current value + +## EXAMPLES + +``` +content: + progres-bar: + tag: tag_name + length: 20 + start: {string: {text: ├}} + end: {string: {text: ┤}} + fill: {string: {text: ─}} + empty: {string: {text: ╌}} + indicator: {string: {text: ┼}} +```