document status output

2 files changed, 102 insertions, 5 deletions

diff --git a/README.md b/README.md
index b8e3a3a..b876fdb 100644
--- a/README.md
+++ b/README.md
@@ -103,7 +103,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,
diff --git a/dwl.1 b/dwl.1
index fccf569..7fee870 100644
--- a/dwl.1
+++ b/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]
@@ -111,6 +111,103 @@ Toggle focused window between floating and tiled state.
 Resize focused window while dragging.
 Tiled windows will be toggled to the floating state.
 .El
+.Sh STATUS INFORMATION
+.Nm
+writes its status information to standard output.
+If the
+.Fl s
+option is given, the status information is written to the standard input of the
+child process instead.
+.Pp
+Said information has the following format:
+.Bd -ragged -offset indent
+.Ar <monitor>
+.Ar <component>
+.Ar <data>
+.Ed
+.Pp
+.Bl -tag -width 11n -offset 0 -compact
+.It Ar <monitor>
+is the name given to the output.
+.It Ar <component>
+is one of (in order)
+.Em title ,
+.Em appid ,
+.Em fullscreen ,
+.Em floating ,
+.Em selmon ,
+.Em tags ,
+.Em layout .
+.It Ar <data>
+changes depending on
+.Ar <component> .
+.Bl -tag -width 10n -compact
+.It Em title
+The title of the focused window on
+.Ar <monitor>
+or nothing if there is no focused window.
+.It Em appid
+The app_id of the focused window on
+.Ar <monitor>
+or nothing if there is no focused window.
+.It Em fullscreen
+Prints 1 if the focused window on
+.Ar <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
+.Ar <monitor>
+is in floating state, otherwise prints 0. If there is no focused
+window it prints nothing.
+.It Em selmon
+Prints 1 if
+.Ar <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
+.Ar <monitor> .
+.It
+Selected tags of
+.Ar <monitor> .
+.It
+Tags of the focused window on
+.Ar <monitor> .
+.It
+Tags where a window on
+.Ar <monitor>
+requested activation or has urgency hints.
+.El
+The bitmasks are 32-bit unsigned decimal integers.
+.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 \(ti/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 :
@@ -153,9 +250,9 @@ Start
 with s6 in the background:
 .Dl dwl \-s \(aqs6\-svscan <&\-\(aq
 .Sh SEE ALSO
+.Xr dwm 1 ,
 .Xr foot 1 ,
 .Xr wmenu 1 ,
-.Xr dwm 1 ,
 .Xr xkeyboard-config 7
 .Sh BUGS
 All of them.