xbattext.ms: Re-organize documentation

2 files changed, 107 insertions, 52 deletions

diff --git a/xbattext.c b/xbattext.c
index 36c093e..66e29fe 100644
--- a/xbattext.c
+++ b/xbattext.c
@@ -83,12 +83,13 @@ Widget toplevel, label;
 XmString xms;
 XtAppContext app_context;
 
+/* program start */
 int
 main(int argc, char* argv[])
 {
 	toplevel = XtVaAppInitialize(
 		&app_context,
-		"XBat",
+		"xbattext",
 		NULL, 0,
 		&argc, argv,
 		NULL,
diff --git a/xbattext.ms b/xbattext.ms
index 44cdde8..39ffcdd 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -13,7 +13,7 @@ John Ankarström
 .I xbattext
 is a simple X11 program that displays, in text,
 the current battery level.
-Its source code serves as a good introduction to X11 programnming.
+Its source code serves as a good introduction to X11 programming.
 It is short, simple and easy to follow,
 as it accounts only for a single system \(en NetBSD.
 It makes use of both Xt (X toolkit intrinsics) and Xm (Motif),
@@ -36,64 +36,111 @@ If you want to see a screenshot of
 .I xbattext ,
 skip ahead to the last page.
 .AE
+.SH
+.ce
+.sp -1v
+Definitions
+.sp 1v
 .Re xbattext.c:/^#include/
 .LP
+Most of the includes regard standard C features,
+but there are two special ones worth mentioning:
+.PP
 .I Xm/Label.h
 contains the definitions for Motif's label widget,
-which is used to display the text.
-That file, in turn, includes
-.I X11/Xlib.h
-for us.
+which is used to display the battery percentage.
+It includes the rest of the relevant X11 headers for us.
 .PP
 .I machine/apmvar.h
-has definitions needed in order to inspect the battery status on NetBSD.
+defines the
+.I apm_power_info
+structure,
+which is needed in order to inspect the battery status on NetBSD.
+It will be retrieved via an
+.I ioctl
+request, so
+.I sys/ioctl.h
+is included as well.
 .Re xbattext.c:/^\/\* interval in seconds/
 .LP
-By default, the battery status is checked every five seconds.
+The battery status is checked every five seconds by default.
 .Re xbattext.c:/^\/\* low battery level/
 .LP
-By default, the battery level is considered to be low
+The battery level is considered to be
+.Q low
 if it is below 30 percent.
-.Re xbattext.c:/^struct res/
+.PP
+The user is encouraged to modify this and the previous constant
+according to his own preferences.
+.bp
+.Re xbattext.c:/^void update(/
+\&
+.Re xbattext.c:/^\/\* resources/
 .LP
-Two structures are created to access the application's resources:
+Two structures are needed 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 retrieved.
-.PP
-The
+which de\%fines the manner in which the re\%sources should be assigned
+to the members of the
 .I res
-structure is going to be filled by the function
-.I XtGetApp\%licationResources
-using the information defined in
-.I res_opts .\**
+strcture.\**
 .FS
+.Q Resources
+are the settings set by the user in
+.I ~/.Xdefaults
+or
+.I ~/.Xresources .
 For more information about resource management and the structure of the
 .I XtResource
 type, see
 .nh
-http://lesstif.\:sourceforge.net/doc/super-ux/g1ae03e/part1/chap9.html.
+http://lesstif.sourceforge.net/doc/super-ux/g1ae03e/part1/\:chap9.html.
 .hy
 .FE
-.Re xbattext.c:/"alertFontList"/
-\&
+.PP
+At the beginning of the program's execution, the
+.I res
+structure is filled by the function
+.I XtGetApp\%licationResources
+according to the definitions in
+.I res_opts .
+.PP
+The
+.I Pixel
+type is an unsigned long value representing a color, like
+.I black
+or
+.I red3 .
+The
+.I XmFont\%List
+type
+technically represents a list of fonts,
+but for all intents and purposes,
+it will be used here only to represent a single font selection.
+.PP
+As you might guess from these resource definitions,
+.I xbattext
+allows the user to control the color and font of the battery display
+depending on the battery status.
 .Re xbattext.c:/^\/\* state changes/
 .LP
-The
-.I change
-variable represents the possible changes in battery state.
 .I xbattext
-updates the font and color of the battery display
-whenever one of these state changes occur.
+inspects the state of the battery every five seconds.
+On every iteration, it updates the percentage displayed,
+but the font and color are changed only
+when it detects a relevant change in the battery's state.
+.PP
+When such a change is de\%tected,
+the
+.I change
+variable is set.
+Its possible values represent the range of relevant changes in battery state.
+The program then changes the color and font depending on the value of
+.I change .
+.bp
 .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 an array used by
 .I XtSet\%Arg ,
@@ -102,8 +149,6 @@ which stores arguments in it, and
 which applies new settings to a given widget
 according to the arguments stored in it.
 .PP
-.ps -1p
-.vs -1p
 The boolean values
 .I alerting
 and
@@ -113,20 +158,27 @@ whenever
 .I xbattext
 detects that the battery is low or
 that the AC adapter is plugged in.
+.PP
+The other variables will be explained as we go along.
+.Rr
+.SH
+.ce
+Initial setup
+.sp 1v
+.Re xbattext.c:/\/\* program start/
+\&
 .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.
+The application is initialized.
+.I top\%level
+is set, which will serve as the parent for all widgets.
 .PP
-.I toplevel
-is the
-.Q main
-widget that contains all actual widgets.
+Note that many Xt functions have two variants:
+one that uses
+.I Xt\%SetArg
+to collect arguments,
+and a variadic variant, marked by
+.I Va .
 .Re xbattext.c:/open("\/dev\/apm"/
 .LP
 The battery level is queried through
@@ -134,19 +186,16 @@ The battery level is queried through
 requests to
 .I /dev/apm .
 The file descriptor is closed by the kernel when the program exits.
-.bp
 .Re xbattext.c:/^	\/\* load application resources/
 .LP
-As mentioned above,
 .I XtGetApplicationResources
-uses the
-.I XtResour\%ce
-list defined earlier to fill the
+fills the
 .I res
-structure with the corresponding resources.
+structure with the resources set in
+.I res_opts .
 .Re xbattext.c:/^	\/\* create motif label/
 .LP
-The battery level is displayed in a Motif label widget.
+The battery level will be displayed in a Motif label widget.
 It starts out containing an empty string.
 .Re xbattext.c:/^	update(/
 .LP
@@ -158,6 +207,11 @@ independently of the event loop.\**
 For more information about timeouts, see
 http://motifdeveloper.com/tips/tip16.html.
 .FE
+.Rr
+.SH
+.ce
+Operation
+.sp 1v
 .Re xbattext.c:/^\/\* update battery status and (re-)add timer/
 .LP
 The