wip: man pages

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