document status output

README.md

@@ -102,7 +102,7 @@ automatically, you will need to configure it prior to launching `dwl`, e.g.:
 
 Information about selected layouts, current window title, app-id, and
 selected/occupied/urgent tags is written to the stdin of the `-s` command (see
-the `printstatus()` function for details).  This information can be used to
+the `STATUS INFORMATION` section in `dwl(1)`).  This information can be used to
 populate an external status bar with a script that parses the
 information. Failing to read this information will cause dwl to block, so if you
 do want to run a startup command that does not consume the status information,

dwl.1

@@ -37,7 +37,7 @@ starts a shell process running
 when starting.
 When stopping, it sends
 .Dv SIGTERM
-to the child process and waits for it to exit.
+to the child process group and waits for it to exit.
 .Pp
 Users are encouraged to customize
 .Nm
@@ -55,10 +55,10 @@ Move window to a single tag.
 Toggle tag for window.
 .It Mod-p
 Spawn
-.Nm wmenu-run .
+.Xr wmenu-run 1 .
 .It Mod-Shift-Return
 Spawn
-.Nm foot .
+.Xr foot 1 .
 .It Mod-[jk]
 Move focus down/up the stack.
 .It Mod-[id]
@@ -108,6 +108,105 @@ Move focused window while dragging. Tiled windows will be toggled to the floatin
 Toggles focused window between floating and tiled state.
 .It Mod-Button3
 Resize focused window while dragging. Tiled windows will be toggled to the floating state.
+.Sh STATUS INFORMATION
+.Nm
+prints its status information to standard output. When the -s option is
+given then the status information is printed to the standard input of the child
+process.
+.Pp
+Said information has the following format:
+.Bd -ragged -offset indent
+.Aq Em monitor
+.Aq Em component
+.Aq Em data
+.Ed
+.Pp
+.Bl -tag -width 11n -offset 0 -compact
+.It Aq Em monitor
+is the name given to the output.
+.It Aq Em component
+is one of (in order)
+.Em title
+.Em appid
+.Em fullscreen
+.Em floating
+.Em selmon
+.Em tags
+.Em layout
+\&.
+.It Aq Em data
+changes depending of
+.Aq Em component
+.Bl -tag -width fullscreen -compact
+.It Em title
+The title of the focused window on
+.Aq Em monitor
+or nothing if there is no focused window.
+.It Em appid
+The app_id of the focused window on
+.Aq Em monitor
+or nothing if there is no focused window.
+.It Em fullscreen
+Prints 1 if the focused window on
+.Aq Em monitor
+is in fullscreen state, otherwise prints 0. If there is no focused
+window it prints nothing.
+.It Em floating
+Prints 1 if the focused window on
+.Aq Em monitor
+is in floating state, otherwise prints 0. If there is no focused
+window it prints nothing.
+.It Em selmon
+Prints 1 if
+.Aq Em monitor
+is the selected monitor, otherwise prints 0.
+.It Em tags
+Prints four bitmasks in the following order:
+.Bl -bullet -width 2n -compact
+.It
+Occupied tags of
+.Aq Em monitor
+\&.
+.It
+Selected tags of
+.Aq Em monitor
+\&.
+.It
+Tags of the focused window on
+.Aq Em monitor
+\&.
+.It
+Tags where a where a window on
+.Aq Em monitor
+requested activation or has urgency hints.
+.El
+The bitmasks are a 32-bit unsigned integer.
+.It Em layout
+Prints the symbol of the current layout.
+.El
+.El
+.Ss Examples
+When there is a selected window:
+.Bd -literal -offset indent
+HDMI-A-1 title ~/source/repos/dwl > man -l dwl.1
+HDMI-A-1 appid footclient
+HDMI-A-1 fullscreen 0
+HDMI-A-1 floating 0
+HDMI-A-1 selmon 1
+HDMI-A-1 tags 271 4 4 0
+HDMI-A-1 layout [T]
+.Ed
+.Pp
+When there is no selected window:
+.Bd -literal -offset indent
+HDMI-A-1 title
+HDMI-A-1 appid
+HDMI-A-1 fullscreen
+HDMI-A-1 floating
+HDMI-A-1 selmon 1
+HDMI-A-1 tags 271 512 0 0
+HDMI-A-1 layout [T]
+.Ed
 .Sh ENVIRONMENT
 These environment variables are used by
 .Nm :