x  m  c  l  o  c  k         r  e  f  e  r  e  n  c  e
=====================================================

Section Zero - Intro
--------------------
xmclock is a program designed to simulate a clock that is
keeping metric time.  The current version, 1.0, is written
in Tcl/Tk and is the first X program from Anvilsoft.

It is released under the conditions of the GNU General Public
License.  Please click the NO WARRANTY button on the About
Panel for complete information.

This document explains the options available to the user and
discusses some design concerns.  For information on metric time
see "Metric Time Reference" on the Help menu.

xmclock can be invoked from an X menu since it takes no arguments.

Section One - Control Menu
--------------------------
Here is an explanation of each item on the Control menu, where
you can set options that control the entire program:

	1) Precision Radiobuttons
	   This is where you set the accuracy of xmclock.
	   The options available are to display 0, 1, 2, or
	   3 decimal places (minute, deciminute, centiminute,
	   milliminute)

	2) Font Size Radiobuttons
	   These let you select the font size of the main display.
	   For your information, Big is 400 point, Medium is 250
	   point and Small is 175 point.  All are in Courier Bold

	3) Kill Menu
	   This allows you to get everything set just right and
	   then destroy the menubar in order to shrink the window.

	4) Quit
	   This is one way to leave the program.

Section Two - Options Menu
--------------------------
From the Options menu, you can turn program features on and off.
Here's a list:

	1) Standard Time
	   Turning this on will cause a display of the current
	   time in standard format to appear beneath the metric time
	   display (of turn it off, if already on).

	2) Chronograph
	   Turns a small window containing elapsed metric time (since
	   chrono invocation) on or off.  Chronograph is reset every
	   time it is invoked.

	3) Date
	   A simple display of the current date in the format
			   DDD MMM dd , yyyy
	   Where DDD is the 3 letter abbreviation of the day-name,
	   MMM is the month-name TLA, dd is the day-number and yyyy
	   is current year.

	4) Alarm
	   If an alarm is not set, clicking here will ask you when
	   you want the alarm to go off (in metric time) and cause
	   a little red box to display in the bottom right corner
	   of the main display.  When the alarm goes off, it will
	   cause your machine's feeper to go off several times in
	   rapid succession and change the little red box into a
	   bigger red box with a button to push.  The button clears
	   the alarm display and turns off the alarm setting.
	   Clicking the Alarm menu option before the alarm goes off
	   unsets the alarm.

Section Three - Help Menu
-----------------------
This explains the options on the Help menu.

	1) mclock guide
	   Takes you here

	2) Metric Time Ref
	   Access information on the concept of metric time as 
	   envisioned by myself and my friend Josh

	3) Num/Char Ref
	   Scrollable list of the numbers 0 - 127 in decimal, hex,
	   octal and binary as well as ASCII graphics character
	   and control character reference

	4) About xmclock
	   A small info panel on xmclock

Section Four - Non-Menu Commands
---------------------------------
Here are the commands that do not appear on a menu.

	1) Control-x
	   Exits the program (works with or without menu active)

	2) Control-m
	   Brings back the menu if you have killed it

Section Five - Design Concerns
------------------------------
This is not intended to be a hyperprecise timekeeping tool.
It is really just a proof-of-concept application for metric time
itself using calls to date and a timiing loop to minimize system load.
Having said that, let me say that I enjoyed creating this program
immensely and I hope you enjoy using it.

I tried to design this program to be as efficient as possible,
which isn't extremely efficient, but is acceptable to me.  Early
unreleased versions of this program consumed 20-25% of my machine's
CPU cycles and would automatically cause system load average to
jump by 1.  This version eats 7-10% of my CPU cycles but only
increases load by about 0.05-0.1.  It does, however, consistently
consume 8-10% of my memory (16MB).

I also tried to put the user in command as much as possible.
My first publicly released program, rot13, suffered badly from
creeping featurism.  I coded a lot of silly features into the
program just because I could and made bad decisions about which
options would be the default ones.
I got some good feeback from some good people and cut out all the
stupid features and issued a fixed version.  I didn't want to make
the same mistake twice so although this program is laden with
features that occurred to me during the 2 years I wanted to write
it, all of them are turned off by default and I tried to choose
logical values for the control settings as well.  Let me know
how I did.

anvil@gnat.net
http://www.gnat.net/~anvil

Section Six - Ghosts of (x)mclocks Past and Future
---------------------------------------------------
There is an early version of this program, version 0.6 still available.
It is the only available DOS version and it it a compiled Qbasic program.
It is, of course, called mclock, and is available at my web site only.
Development is stopped on it.

I have no plans to support a Win3.x/95/NT version of this program.
My friend Josh (zorak@mindspring.com) said he was thinking about
it.  So if you want one, either do it yourself of bug him about it.

Another friend, jetty@gnat.net expressed interest in an OS/2 port
of xmclock.  So bother him if you want one.

I plan on taking some electonics engineering classes soon and my first
project in that area is a digital clock that keeps (antici-pation)
METRIC TIME!  Bwaaaa-hahahahaha!

On a quasi-related note, xmclock has a helper app that reads and
displays text files (this one, for example).  It is called xb for
X Browse.  I would like to publicly state that it is totally 
unoriginal and derivative of example code from Eric F. Johnson's
book, "Graphical Applications with Tcl & Tk".  You can invoke it by
itself to read text files in X.  Either start it at a command line with
	xb <filename>
or put it on your X menu and it will ask you for a filename when
invoked without one (actually, a meta-helper app called xbgf gets the
filename from you and starts up a second copy of xb, then kills the parent
xb (and thus itself and its child xb) when you click 'Done').  Be aware
that it reads the entire file into memory so be careful with large files!

I am totally open to suggestions/criticisms about this program and
future versions of it.  I really wanted to add a dual-time display,
but I need some time to work out all the timezone stuff.  Please, if
you like this program let me know and tell me how to make it better.

Thank you,

Shawn Boyette (anvil@gnat.net)
Lone Programmer, Anvilsoft [TM]
