|author||John Ankarstr\xf6m <firstname.lastname@example.org>||2021-06-04 13:24:38 +0200|
|committer||John Ankarstr\xf6m <email@example.com>||2021-06-04 13:24:38 +0200|
xbattext.ms: Finish documentation re-organization
2 files changed, 54 insertions, 36 deletions
@@ -2,6 +2,11 @@
* This is a simple X11 program that displays the battery percentage
* on NetBSD.
+ * If you are curious about how it works, you can download the commented
+ * version of the source code at the following address:
+ * http://img.ankarstrom.se/xbattext.pdf
* It should be compiled with the following flags:
* CFLAGS = -I/usr/X11R7/include -I/usr/pkg/include
diff --git a/xbattext.ms b/xbattext.ms
index 39ffcdd..e01225f 100644
@@ -216,14 +216,16 @@ Operation
-function, which is also called at the end of each timeout,
-is responsible for checking the battery status and
-updating the label.
+both sets up the timer and is called at the end of each timeout.
+Along the way, it checks the battery status
+and updates the text displayed in the label widget.
-The first argument is a pointer to a value set by the user
+The first argument to
+is a pointer to an arbitrary 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.
+The second argument contains a pointer to the timeout identifier.
+Neither argument is used here.
.Re xbattext.c:/^ \/\* get battery info/
As mentioned above,
@@ -249,12 +251,12 @@ We just use the default.
-array mentioned above starts to be filled with arguments
+array mentioned above now starts being filled with arguments
that determine the state of the label widget.
The number of arguments set is kept track of in the
-To begin with, the widget's label string is set to the
+To begin with, the label string is set to the
value defined earlier.
.Re xbattext.c:/^ \/\* check charging status/
@@ -269,16 +271,16 @@ bitmap when a change in
-Note that the value of
+(The value of
-is used in order to prevent these font and color changes
-from unnecessarily being applied every timeout
-regardless of whether the charging status has changed.
+is checked and updated in order to prevent the font and color changes
+from unnecessarily being applied at every timeout
+regardless of whether the charging status has changed.)
.Re xbattext.c:/^ \/\* check low battery/
The same applies when the program checks whether the battery level is below
-.CW ALERT ,
-which is set to 30 by default.
+.CW ALERT .
.Re xbattext.c:/^ \/\* prioritize/
Before the bits in
@@ -294,24 +296,38 @@ if the battery rises above the
but the AC adapter is still plugged in.
+variable reflects a
+It does not reflect the
+.B state .)
.Re xbattext.c:/^ \/\* act on state changes/
After collecting and prioritizing the state changes,
-the foreground color and font of the label widget is set accordingly.
+the foreground color and font of the label widget are set accordingly.
Note that if a
-(color) resource is not defined,
+resource is not defined,
gives it the integer value zero,
-which also signifies the color black
-(thus, the program cannot differentiate
+which also signifies the color black.
+Thus, the program cannot tell the difference
between a missing value and a value of
-.I black ).
+.I black .
Font lists, however, are set to null if undefined.
-If a font list resource is undefined,
+font list is undefined,
-uses the default font list instead.
+uses the main font list instead.
.Re xbattext.c:/^ case SET_CHARGE:/
@@ -339,22 +355,23 @@ That is the totality of the
(almost; a long comment at the beginning of the file, explaining
what the program does and how it should be compiled, was excluded).
-Hopefully, it shows that graphical UNIX programming is nothing to be scared of.
+Hopefully, it shows that graphical UNIX programming is nothing to be afraid of.
While Xlib, Xt and Xm tend nowadays not to be considered
.Q "best practice" ,
they have a low barrier to entry,
-require little resources from the computer and
+require little resources of the computer and
are often installed by default on UNIX systems.
It is better to use worse practices to create
-than to use best practices and create nothing at all;
+than it is to use best practices and create nothing at all;
if those are the alternatives,
then perhaps best practices aren't.
-If, after reading the source code, you are still wondering
-why anyone would want a small window displaying the current battery level,
+If, after reading all this, you are still wondering
+why anyone would want a small window on their screen
+displaying the current battery level,
then you should get acquainted with the X11 window manager
-.I jwm \\*
+.I jwm \**
is available at https://joewing.net/projects/jwm/.
@@ -368,20 +385,16 @@ and its
which removes the border from a given X11 program and displays it in the tray.
-You can look at it as tray icons according to the UNIX philosophy.
-In my tray,
-sits right beside
-.I xload .
+You can regard it as tray icons according to the UNIX philosophy.
.B "Figure 1."
-.I xload ,
+In my tray,
+sits right beside
-.I xclock .
+.I xload .