formatting for animate and component docs

docs/sketchybar-animate.5.scd

@@ -13,57 +13,57 @@ _PROPERTY_=_VALUE_
 
 # DESCRIPTION
 
-All transitions between argb_hex, integer and positive_integer values can be
-animated, by prepending the animation command in front of any regular *--set* or
-*--bar* command.
+All transitions between argb_hex, integer and positive_integer values can be ++
+animated, by prepending the animation command in front of any regular *--set* ++
+or *--bar* command.
 
-A series of animations can be chained together as many as desired. The animation
-function can also changed in between. This is a nice way to create custom
-animations with key-frames.
+A series of animations can be chained together as many as desired. The ++
+animation function can also changed in between. This is a nice way to create ++
+custom animations with key-frames.
 
-Other properties can also be made to wait for their animation until another
-animation is finished. This is done by simply setting the property that should
-wait to its current value in the first animation.
+Other properties can also be made to wait for their animation until another ++
+animation is finished. This is done by simply setting the property that ++
+should wait to its current value in the first animation.
 
-A superseding non-animated *--set* command targeting a currently animated
+A superseding non-animated *--set* command targeting a currently animated ++
 property will cancel the animation queue and immediately set the value.
 
-A superseding animated *--set* command targeting a currently animated property
-will cancel the animation queue and immediately begin with the new animation
-beginning at the current state.
+A superseding animated *--set* command targeting a currently animated ++
+property will cancel the animation queue and immediately begin with the new ++
+animation beginning at the current state.
 
 # OPTIONS
 
 *--animate* _CURVE_ _DURATION_ *--bar* _SETTING_=_VALUE_ ... _SETTING_=_VALUE_ ++
 *--animate* _CURVE_ _DURATION_ *--set* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_
 
 	Animate the bar or an item. _CURVE_ can be any of the following animation
-	curves: *linear*, *quadratic*, *tanh*, *sin*, *exp*, *circ*. _DURATION_ is a
-	positive integer quantifying the number of animation steps. The duration is the
-	frame count on a 60 Hz display such that the temporal duration of the animation
-	in seconds is given by _DURATION_ / 60.
+	curves: *linear*, *quadratic*, *tanh*, *sin*, *exp*, *circ*. _DURATION_ is
+	a positive integer quantifying the number of animation steps. The duration
+	is the frame count on a 60 Hz display such that the temporal duration of
+	the animation in seconds is given by _DURATION_ / 60.
 
-The animation system *always* animates between all *current* values and the
+The animation system *always* animates between all *current* values and the ++
 values specified in a configuration command (i.e. `--bar` or `--set` commands).
 
 # EXAMPLES
 
-To chain two or more animations together, simply change the property multiple
-times in a single call. Consider
+To chain two or more animations together, simply change the property ++
+multiple times in a single call. Consider
 ```
 sketchybar --animate sin 30 --bar y_offset=10 y_offset=0
 ```
-This will animate the bar to the first offset and then to the second offset
+This will animate the bar to the first offset and then to the second offset ++
 afterwards.
 
 # SEE ALSO
 
-*sketchybar*(1)
-*sketchybar*(5)
-*sketchybar-items*(5)
-*sketchybar-components*(5)
-*sketchybar-popup*(5)
-*sketchybar-events*(5)
-*sketchybar-query*(5)
-*sketchybar-types*(5)
+*sketchybar*(1)++
+*sketchybar*(5)++
+*sketchybar-items*(5)++
+*sketchybar-components*(5)++
+*sketchybar-popup*(5)++
+*sketchybar-events*(5)++
+*sketchybar-query*(5)++
+*sketchybar-types*(5)++
 *sketchybar-tips*(5)

docs/sketchybar-components.5.scd

@@ -23,7 +23,7 @@ _DATA_POINT_ ... _DATA_POINT_ ++
 
 # DESCRIPTION
 
-Components are essentially items, but with special properties.
+Components are essentially items, but with special properties.++
 Currently, there available components include
 - *graph*: shows a graph
 - *space*: represents a mission control space
@@ -34,9 +34,9 @@ Refer to *sketchybar-types*(5) when needed.
 
 # OPTIONS
 
-The usual commands for items such as *--add*, *--set*, *--move*, etc. (see
-*sketchybar-items*(5)) can also be used by components as is unless superseded by
-a redefinition below.
+The usual commands for items such as *--add*, *--set*, *--move*, etc. ++
+(see *sketchybar-items*(5)) can also be used by components as is unless ++
+superseded by a redefinition below.
 
 # DATA GRAPH
 
@@ -73,12 +73,14 @@ a redefinition below.
 
 ## Notes
 
-Graphs usually take the entire height of the bar as a drawing canvas. However,
-if a background is set for the graph item and for its height, the graph
-will draw inside of the background. With a background enabled, the graph can
-also be moved via a *y_offset*, say,
+Graphs usually take the entire height of the bar as a drawing canvas. ++
+However, if a background is set for the graph item and for its height, the ++
+graph will draw inside of the background. With a background enabled, the ++
+graph can also be moved via a *y_offset*, say,
 ```
-sketchybar --set graph_name background.color=0xff00ff00 background.height=20 y_offset=2
+sketchybar --set graph_name background.color=0xff00ff00 \\
+					   background.height=20 \\
+					   y_offset=2
 ```
 
 
@@ -102,7 +104,7 @@ sketchybar --set graph_name background.color=0xff00ff00 background.height=20 y_o
 
 ## Notes
 
-This component provides dditional variables available for *script* and
+This component provides dditional variables available for *script* and ++
 *click_script*:
 - *$SELECTED*: has the value *true* if the associated space is selected;
   otherwise *false*
@@ -118,8 +120,8 @@ which can then be freely configured by supplying a different script:
 sketchybar --set space_name script=path/to/script
 ```
 
-For performance reasons the space script is only run on a change in the
-$SELECTED variable, i.e. if the associated space has become active or has
+For performance reasons the space script is only run on a change in the ++
+$SELECTED variable, i.e. if the associated space has become active or has ++
 resigned being active.
 
 
@@ -140,27 +142,27 @@ resigned being active.
 
 ## Notes
 
-It is now possible to set properties for the bracket, just as for any item or
-component, although support is only for background as of yet. 
+It is now possible to set properties for the bracket, just as for any item ++
+or component, although support is only for background as of yet. 
 
-To set a colored background around the space components (which are, say, named
-space.1, space.2, space.3), the setup would be:
+To set a colored background around the space components (which are, say, ++
+named space.1, space.2, space.3), the setup would be:
 ```
 sketchybar --add bracket spaces space.1 space.2 space.3 \\
-	--set spaces background.color=0xffffffff \\
-		background.corner_radius=4 \\
-		background.height=20
+		 --set spaces background.color=0xffffffff \\
+				    background.corner_radius=4 \\
+				    background.height=20
 ```
 
-Alternatively, if there are a number of spaces, say, named space.1, space.2,
+Alternatively, if there are a number of spaces, say, named space.1, space.2, ++
 etc., the regex syntax comes in handy:
 ```
 sketchybar --add bracket spaces '/space\..*/'
 ```
 
-Brackets are very flexible with their members, i.e. it is no problem to bracket
-a left and a center item together. The background will span all the way between
-those items.
+Brackets are very flexible with their members, i.e. it is no problem to ++
+bracket a left and a center item together. The background will span all the ++
+way between those items.
 
 # ITEM ALIAS
 
@@ -210,7 +212,7 @@ those items.
 
 ## Notes
 
-All other macOS menu bar items currently available on the system with their
+All other macOS menu bar items currently available on the system with their ++
 respective owners and names can be listed via (see *sketchybar-query*(5))
 ```
 sketchybar --query default_menu_items
@@ -261,64 +263,43 @@ sketchybar --query default_menu_items
 
 ## Notes
 
-The slider can be enabled to receive *mouse.clicked* events by subscribing
+The slider can be enabled to receive *mouse.clicked* events by subscribing ++
 to this event. 
 
-A slider will receive the additional environment variable *$PERCENTAGE* on a
-click in its script, which represents the percentage corresponding to the click
-location.
+A slider will receive the additional environment variable *$PERCENTAGE* on a ++
+click in its script, which represents the percentage corresponding to the ++
+click location.
 
-If a slider is dragged by the mouse it will only send a single event
+If a slider is dragged by the mouse it will only send a single event ++
 on drag release and track the mouse during the drag.
 
 # EXAMPLES
 
-To add mission control space indicators to indicate active and available spaces
-in posix shell and without yabai scripting additions:
-
-```
-pos=left
-name=space
-set -- 1 2 3 4 5 6 7 8 9
-sid=0
-for win in "$@"
-do sid=$((sid+1))
-	sketchybar --add $name $name.$sid $pos \\
-		--set $name.$sid associated_space=$sid icon.drawing=off label="$win" \\
-			script='sketchybar --set $NAME background.border_width=1 \\
-				background.padding_left=5 background.drawing=$SELECTED' \\
-			click_script="skhd -k ctrl\\ -\\ $sid"
-done
-sketchybar --add bracket spaces "/$name\..*/"
-```
-
-Or, in bash and with scripting additions:
+To add mission control space indicators to indicate active and available ++
+spaces in bash:
 
 ```
 SPACE_ICONS=("1" "2" "3" "4" "5" "6" "7" "8" "9" "10")
 for i in "${!SPACE_ICONS[@]}"
 do sid=$(($i+1))
 	sketchybar --add space space.$sid left \\
-		--set space.$sid space=$sid \\
-			icon=${SPACE_ICONS[i]}               \\
-			background.color=0x44ffffff          \\
-			background.corner_radius=5           \\
-			background.height=20                 \\
-			background.drawing=off               \\
-			label.drawing=off                    \\
-			script="CONFIG_DIR/plugins/space.sh" \\
-			click_script="yabai -m space --focus $sid"
+		\--set space.$sid space=$sid icon=${SPACE_ICONS[i]} \\
+		script='sketchybar --set $NAME icon.highlight=$SELECTED'
 done
 ```
+Should you wish to focus the respective spaces with a click on the item in ++
+the bar, you can add a click_script to the items which triggers a space ++
+change (e.g. via yabai or by synthetically emitting the space focus keyboard ++
+shortcuts via skhd)
 
 # SEE ALSO
 
-*sketchybar*(1)
-*sketchybar*(5)
-*sketchybar-items*(5)
-*sketchybar-popup*(5)
-*sketchybar-events*(5)
-*sketchybar-query*(5)
-*sketchybar-animate*(5)
-*sketchybar-types*(5)
+*sketchybar*(1)++
+*sketchybar*(5)++
+*sketchybar-items*(5)++
+*sketchybar-popup*(5)++
+*sketchybar-events*(5)++
+*sketchybar-query*(5)++
+*sketchybar-animate*(5)++
+*sketchybar-types*(5)++
 *sketchybar-tips*(5)