Add commented version of source code

1 files changed, 88 insertions, 0 deletions

diff --git a/xbattext.ms b/xbattext.ms
new file mode 100644
index 0000000..34b5f62
--- /dev/null
+++ b/xbattext.ms
@@ -0,0 +1,88 @@
+.so /home/john/prj/re/re.tmac
+.nr St 6n
+.TL
+.BI xbattext ,
+an X11 battery monitor for NetBSD
+.AU
+John Ankarström
+.AB
+.LP
+.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.
+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),
+two of the most popular X libraries.
+It demonstrates how to access resources from
+.I ~/.Xdefaults ,
+how to display text in various colors and fonts and
+how to set timers outside of the main event loop
+to perform asynchronous tasks that are not triggered by user interaction.
+.PP
+This document is a commented version of the
+.I xbattext
+source code.
+It is generated with
+.I re ,
+a reference-based literate programming system available at the address
+http://git.\:ankarstrom.se/re/.
+.AE
+.Re xbattext.c:/^#include/
+.LP
+.I Xm/Label.h
+contains the definitions for Motif's label widget,
+which is used to display the text.
+That headerf file, in turn, includes
+.I X11/Xlib.h
+for us.
+.PP
+.I machine/apmvar.h
+is needed in order to inspect the battery status on NetBSD.
+.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.
+.PP
+The
+.I res
+structure is going to be filled by the function
+.I XtGetApplicationResources
+using the information defined in
+.I res_opts .\**
+.FS
+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.
+.hy
+.FE
+.Re xbattext.c:/"alertFontList"/
+\&
+.Re xbattext.c:/"chargeForeground"/
+.LP
+.I wargs
+is used by
+.I XtSetArg ,
+which stores arguments in it, and
+.I XtSetValues ,
+which sets new values for a widget
+according to the arguments stored in it.
+.PP
+.I alert
+and
+.I charge
+are boolean variables that are set to true
+whenever
+.I xbattext
+detects that the battery is low or
+that the AC adapter is plugged in.
+.PP
+.I timer
+contains the identifier for the current timer.
+.Re xbattext.c:/^main/