wip: man pages

doc/CMakeLists.txt

@@ -27,4 +27,12 @@ function(add_man_pages)
   add_custom_target(man-pages ALL SOURCES ${ARGN} DEPENDS ${out})
 endfunction()
 
-add_man_pages(f00bar.1.scd f00bar.5.scd)
+add_man_pages(
+  f00bar.1.scd
+  f00bar.5.scd
+
+  f00bar-modules.5.scd
+  f00bar-module-alsa.5.scd
+
+  f00bar-particles.5.scd
+  )

doc/f00bar-module-alsa.5.scd

@@ -0,0 +1,47 @@
+f00bar-module-alsa(5)
+
+# NAME
+f00bar-module-alsa - configuration file
+
+# DESCRIPTION
+
+Monitors an alsa soundcard for volume and mute/unmute changes.
+
+# TAGS
+
+[[ *Name*
+:[ *Type*
+:[ *Description*
+|  volume
+:  range
+:  Volume level, with min and max as start and end range values
+|  muted
+:  bool
+:  True if muted, otherwise false
+
+
+# CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  card
+:  string
+:  yes
+:  The soundcard name. _Default_ might work.
+|  mixer
+:  string
+:  yes
+:  Mixer channel to monitor. _Master_ might work.
+
+# EXAMPLES
+
+```
+bar:
+  left:
+    - alsa:
+        card: hw:PCH
+        mixer: Master
+        content: {string: {text: "{volume}"}}
+```

doc/f00bar-modules.5.scd

@@ -0,0 +1,71 @@
+f00bar-modules(5)
+
+# NAME
+f00bar-modules - configuration file
+
+# DESCRIPTION
+
+Modules are what monitors your system and provides data for the status
+bar.
+
+All modules expose their data through *tags*. Each tag has a *name*,
+*type* and *value*. The name and type is fixed, while the value
+typically changes over time. See *TAGS*.
+
+The tags are rendered by _particles_. Each particle has its own way of
+representing tag values. The simplest one is the _string_ particle,
+which renders a text representation of the tag value. See
+*f00bar-particles*(5).
+
+# FORMAT
+
+Each module defines its own configuration format. However, the
+following attributes are supported by all modules:
+
+[[ *Name*
+:[ *Type*
+:[ *Description*
+|  content
+:  particle
+:  A particle describing how the module's information is to be rendered.
+   See *f00bar-particles*(5)
+|  anchors
+:  associative array
+:  Free-to-use associative array, where you can put yaml anchor definitions
+
+# TAGS
+
+Tags are the data carriers; it is through tags that modules expose
+their information. Each module defines its own set of tags.
+
+The available tag *types* are:
+
+[[ *Type*
+:[ *Description*
+|  string
+:  Value is a string. Rendered as-is by the _string_ particle.
+|  int
+:  Value is an integer. Rendered in base 10 by the _string_ particle.
+|  bool
+:  Value is true or false. Rendered as "true" or "false" by the _string_
+   particle
+|  float
+:  Value is a float. Rendered in base 10, with two decimal digits by the
+   _string_ particle
+|  range
+:  Value is an integer, with a minimum and maximum value associated
+   with it. By default, the _string_ particle renders the value. The
+   _:min_ or _:max_ suffixes by be added to instead render the mininum
+   or maximum value (_\"{tag_name:min}\"_).
+|  realtime
+:  Value is an integer that changes in a predictable manner (in
+   "realtime"). This allows the particle to update itself
+   periodically. Only supported by the
+   *f00bar-particle-progress-bar*(5). Other particles can still render
+   the tag's value. And, the _string_ particle recognizes the _:unit_
+   suffix, which will be translated to a "s" for a tag with "seconds"
+   resolution, or "ms" for one with "milliseconds" resolution.
+
+# MODULES
+
+- *f00bar-module-alsa*(5)

doc/f00bar-particles.5.scd

@@ -0,0 +1,259 @@
+f00bar-particles(5)
+
+# NAME
+f00bar-particles - configuration file
+
+# DESCRIPTION
+
+Particles are what renders the tags provided by modules. Each particle
+defines its own set of configuration attributes. However, the
+following attributes are supported by all particles:
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  left-margin
+:  int
+:  no
+:  Space, in pixels, on the left side of the particle
+|  right-margin
+:  int
+:  no
+:  Space, in pixels, on the right side of the particle
+|  margin
+:  int
+:  no
+:  Short-hand for setting both _left-margin_ and _right-margin_
+|  font
+:  font
+:  no
+:  Font to use. Note that this is an inherited attribute; i.e. you can
+   set it on e.g. a _list_ particle, and it will apply to all
+   particles in the list.
+|  foreground
+:  color
+:  no
+:  Foreground (text) color. Just like _font_, this is an inherited attribute.
+|  on-click
+:  string
+:  no
+:  Command to execute when the particle is clicked. Note that the
+   string is *not* executed in a shell.
+|  deco
+:  decoration
+:  no
+:  Decoration to apply to the particle. See *f00bar-decorations*(5)
+
+# STRING
+
+## DESCRIPTION
+
+This is the most basic particle. It takes a format string, consisting
+of free text mixed with tag specifiers.
+
+## CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  text
+:  string
+:  yes
+:  Format string. Tags are spcified with _{tag_name}_. Some tag types
+   have suffixes that can be appended (e.g. _{tag_name:suffix}_). See
+   *f00bar-modules*(5)).
+|  max
+:  int
+:  no
+:  Sets the rendered string's maximum length. If the final string's
+   length exceeds this, the rendered string will be truncated, and
+   "..."  will be appended. Note that the trailing "..." are
+   *included* in the maximum length. I.e. if you set _max_ to '5', you
+   will only get *2* characters from the string.
+
+## EXAMPLES
+
+```
+content:
+  string:
+    text: "hello, this is footag's value: {footag}"
+```
+
+# EMPTY
+
+## DESCRIPTION
+
+This particle is a place-holder. While it does not render any tags,
+margins and decortions are rendered.
+
+## CONFIGURATION
+
+None
+
+## EXAMPLES
+
+```
+content:
+  empty: {}
+```
+
+# 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.
+
+## CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  items
+:  list
+:  yes
+:  List of sub particles
+|  left-spacing
+:  int
+:  no
+:  Space, in pixels, *between* the sub particles.
+|  right-spacing
+:  int
+:  no
+:  Space, in pixels, *between* the sub particles. Note: default=2
+|  spacing
+:  int
+:  no
+:  Short-hand for setting both _left-spacing_ and _right-spacing_
+
+## EXAMPLES
+
+```
+content:
+  list:
+    spacing: 5
+    items:
+      - string: {text: hello}
+      - string: {text: world}
+```
+
+# MAP
+
+## DESCRIPTION
+
+This particle maps the values of a specific tag to different
+particles. In addition to explicit tag values, you can also specify a
+default/fallback particle.
+
+## CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  tag
+:  string
+:  yes
+:  The tag (name of) which values should be mapped
+|  values
+:  associative array
+:  yes
+:  An associative array of tag values mapped to particles
+|  default
+:  particle
+:  no
+:  Default particle to use, when tag's value does not match any of the
+   mapped values.
+
+## EXAMPLES
+
+```
+content:
+  map:
+    tag: tag_name
+    default:
+      string:
+        text: this is the default particle; the tag's value is now {tag_name}
+    values:
+      one_value:
+        string:
+          text: tag's value is now one_value
+      another_value:
+        string:
+          text: tag's value is now another_value
+
+```
+
+# 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
+indicator.
+
+## CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  tag
+:  string
+:  yes
+:  The range tag (name of) to use as index
+|  items
+:  list
+:  yes
+:  List of particles. Note that the tag value is *not* used as-is; its
+   minumum and maximum values are used to map the tag's range to the
+   particle list's range.
+
+## EXAMPLES
+
+```
+content:
+  ramp:
+    tag: capacity
+    items:
+      - string: {text: }
+      - string: {text: }
+      - string: {text: }
+      - string: {text: }
+      - string: {text: }
+```
+
+# PROGRESS-BAR
+
+## DESCRIPTION
+
+This particle 
+
+## EXAMPLES