formatting and slight modifications

docs/build.sh

@@ -0,0 +1,12 @@
+rm -rf build
+mkdir build
+scdoc < sketchybar-animate.5.scd > build/sketchybar-animate.5
+scdoc < sketchybar-components.5.scd > build/sketchybar-components.5
+scdoc < sketchybar-events.5.scd > build/sketchybar-events.5
+scdoc < sketchybar-items.5.scd > build/sketchybar-items.5
+scdoc < sketchybar-popup.5.scd > build/sketchybar-popup.5
+scdoc < sketchybar-query.5.scd > build/sketchybar-query.5
+scdoc < sketchybar-tips.5.scd > build/sketchybar-tips.5
+scdoc < sketchybar-types.5.scd > build/sketchybar-types.5
+scdoc < sketchybar.1.scd > build/sketchybar.1
+scdoc < sketchybar.5.scd > build/sketchybar.5

docs/sketchybar-animate.5.scd

@@ -14,42 +14,42 @@ _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.
+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 be 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.
+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
 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
 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
 ```
@@ -58,12 +58,12 @@ 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

@@ -13,30 +13,24 @@ _DATA_POINT_ ... _DATA_POINT_ ++
 *sketchybar --add alias* _APPLICATION_NAME_|"_WINDOW_OWNER_,_WINDOW_NAME_" _POSITION_ ++
 *sketchybar --add slider* _NAME_ _POSITION_ _WIDTH_
 
-*sketchybar --set* _NAME_ _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++
-*sketchybar --default* _PROPERTY_=_VALUE_ ... _PROPERTY_=_VALUE_ ++
-*sketchybar --reorder* _NAME_ ... _NAME_ ++
-*sketchybar --move* _NAME_ *before*|*after* _REFERENCE_NAME_ ++
-*sketchybar --clone* _PARENT_NAME_ _NAME_ [*before*|*after*] ++
-*sketchybar --rename* _OLD_NAME_ _NEW_NAME_ ++
-*sketchybar --remove* _NAME_
-
 # DESCRIPTION
 
-Components are essentially items, but with special properties.
-Currently, there available components include
+Components are essentially items (see *sketchybar-items*(5)), but with special
+properties.
+
+Currently, the available components include
 - *graph*: shows a graph
 - *space*: represents a mission control space
-- *bracket*: brackets other items together
+- *bracket*: creates a shared background for any number of items
 - *alias*: aliases a menu bar item from the macOS bar
 - *slider*: shows a progression and can be clicked/dragged to set a new value.
 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 +67,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, the graph will draw
+inside of the background (i.e. scaled in height to fit 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
 ```
 
 
@@ -94,15 +90,16 @@ sketchybar --set graph_name background.color=0xff00ff00 background.height=20 y_o
 	Change the properties of the component. Inherits the usual *--set* command
 	usage. Overriden properties include:
 	- *space*: which space this item represents
-	- *display*: (optional) on which display the space is shown. The space property
-	  must be set to properly associate this item with the corresponding mission
-	  control space. Optionally, a display to force a space item to stay on a specific
-	  display can be provided. Otherwise the item will draw on the screen on which the
-	  space is currently located.
+	- *display*: (optional) on which display the space is shown.
+
+	The space property must be set to properly associate this item with the
+	corresponding mission control space. Optionally, a display to force a space
+	item to stay on a specific display can be provided. Otherwise the item will
+	draw on the screen on which the space is currently located.
 
 ## Notes
 
-This component provides dditional variables available for *script* and
+This component provides additional variables available for *script* and
 *click_script*:
 - *$SELECTED*: has the value *true* if the associated space is selected;
   otherwise *false*
@@ -113,7 +110,7 @@ By default, this component invokes the script
 ```
 sketchybar --set $NAME icon.highlight=$SELECTED
 ```
-which can then be freely configured by supplying a different script:
+which can be freely configured by supplying a different script:
 ```
 sketchybar --set space_name script=path/to/script
 ```
@@ -140,16 +137,16 @@ 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,
@@ -158,9 +155,9 @@ 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
 
@@ -175,7 +172,8 @@ those items.
 	bar item to be aliased.
 
 	If an application has multiple menu bar widgets, the command can be overloaded
-	by providing a _WINDOW_OWNER_ and _WINDOW_NAME_.
+	by providing a _WINDOW_OWNER_ and _WINDOW_NAME_. See the note below how to
+	list all available widgets.
 
 	Then, say, the default system items can be aliased as in:
 	- "Control Center,Bluetooth"
@@ -210,7 +208,7 @@ those items.
 
 ## Notes
 
-All other macOS menu bar items currently available on the system with their
+All 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 +259,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)