From 530e9d71c3c7e93952921a066b2e903bfe55ff2a Mon Sep 17 00:00:00 2001
From: "John Ankarstr\\xf6m" <john@ankarstrom.se>
Date: Thu, 3 Jun 2021 00:45:34 +0200
Subject: xbattext.ms: Add more documentation

---
 Makefile    |   3 ++
 xbattext.ms | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 95 insertions(+), 8 deletions(-)

diff --git a/Makefile b/Makefile
index 527c197..d3c28de 100644
--- a/Makefile
+++ b/Makefile
@@ -9,3 +9,6 @@ install: xbattext
 
 upload: xbattext.c
 	scp xbattext.c root@ankarstrom.se:/var/www/img/htdocs/xbattext.c
+
+xbattext.pdf: xbattext.ms
+	~/prj/re/re xbattext.ms | groff -Tps -ms | ps2pdf - > xbattext.pdf
diff --git a/xbattext.ms b/xbattext.ms
index 34b5f62..06c1269 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -1,5 +1,4 @@
 .so /home/john/prj/re/re.tmac
-.nr St 6n
 .TL
 .BI xbattext ,
 an X11 battery monitor for NetBSD
@@ -26,7 +25,7 @@ This document is a commented version of the
 source code.
 It is generated with
 .I re ,
-a reference-based literate programming system available at the address
+a reference-based literate programming system available at the WWW address
 http://git.\:ankarstrom.se/re/.
 .AE
 .Re xbattext.c:/^#include/
@@ -40,13 +39,16 @@ for us.
 .PP
 .I machine/apmvar.h
 is needed in order to inspect the battery status on NetBSD.
-.Re xbattext.c:/^struct _res/
+.Re xbattext.c:/^\/\* interval in seconds/
+.LP
+By default, the battery status is checked every ten seconds.
+.Re xbattext.c:/^struct res/
 .LP
 Two structures are created to access the application's resources:
 .I res ,
 which will hold the values of the resources, and
 .I res_opts ,
-which defines how those resources should be accessed.
+which defines how those resources should be retrieved.
 .PP
 The
 .I res
@@ -64,8 +66,14 @@ http://lesstif.sourceforge.net/doc/super-ux/g1ae03e/part1/chap9.html.
 .FE
 .Re xbattext.c:/"alertFontList"/
 \&
-.Re xbattext.c:/"chargeForeground"/
+.Re xbattext.c:/^\/\* application state/
 .LP
+There is not space to explain the function of all variables
+used by the program,
+but some of them deserve a special mention:
+.PP
+.ps -1p
+.vs -1p
 .I wargs
 is used by
 .I XtSetArg ,
@@ -74,6 +82,8 @@ which stores arguments in it, and
 which sets new values for a widget
 according to the arguments stored in it.
 .PP
+.ps -1p
+.vs -1p
 .I alert
 and
 .I charge
@@ -82,7 +92,81 @@ whenever
 .I xbattext
 detects that the battery is low or
 that the AC adapter is plugged in.
+.Re xbattext.c:/XtVaAppInitialize(/
+.LP
+Many Xt functions have two variants:
+a non-variadic variant, which uses
+.I XtSetArg
+to collect arguments,
+and a variadic variant, marked by the
+.I Va
+component of its name.
 .PP
-.I timer
-contains the identifier for the current timer.
-.Re xbattext.c:/^main/
+.I toplevel
+contains the
+.Q main
+widget that contains all actual widgets.
+.Re xbattext.c:/open("\/dev\/apm"/
+.LP
+The battery level is queried through
+.I ioctl
+requests to
+.I /dev/apm .
+The file descriptor is closed by the kernel when the program exits.
+.Re xbattext.c:/^	\/\* load application resources/
+.LP
+As mentioned earlier,
+.I XtGetApplicationResources
+uses the
+.I XtResource
+list defined above to fill the
+.I res
+structure with the corresponding resources.
+.bp
+.Re xbattext.c:/^	\/\* create motif label/
+.LP
+The battery level is displayed in a Motif label widget.
+It starts out containing an empty string.
+.Re xbattext.c:/^	update(/
+.LP
+Before starting the main event loop, the
+.I update
+function is called, which registers a timeout that will run
+independently of the event loop.\**
+.FS
+For more information about timeouts, see
+http://motifdeveloper.com/tips/tip16.html.
+.FE
+.Re xbattext.c:/^\/\* update battery status and (re-)add timer/
+.LP
+The
+.I update
+function, which is called at the end of each timeout,
+is responsible for checking the battery status and
+updating the label.
+.PP
+The first argument is a pointer to a value set by the user
+when the timeout is registered.
+The second argument contains a pointer to the timeout ID.
+Neither argument is used in this program.
+.Re xbattext.c:/^	\/\* get battery info/
+.LP
+As mentioned earlier,
+the battery status is retrieved through an
+.I ioctl
+request,
+.CW APM_IOC_GETPOWER .
+It returns an
+.I apm_power_info
+structure (which must be zeroed first).
+.Re xbattext.c:/^	\/\* put battery status into label/
+.LP
+The battery percentage, contained in the
+.I battery_life
+member, is written to an
+.I XmString ,
+which is a special type of string used by Motif.
+It is associated with tag,
+which contains information about the visual characteristics of the text.
+To begin with, the string is set to use the default tag.
+.Re xbattext.c:/^	i = 0;/
-- 
cgit v1.2.3