.TH xabacus "" "" "X Application"
.PC "Abacus calculator for X"
.fi
\fBxabacus 
[\-beadcolor \fIcolor\^\fB]
[\-beadheight \fIheight\^\fB]
[\-beadwidth \fIwidth\^\fB]
[\-bg \fIcolor\^\fB]
[\-display \fIdisplayname\^\fB]
[\-demo \fIscriptpath\fB \-demofont | -fn \fIXfontstring\^\fB]
[\-framewidth \fIwidth\^\fB]
[\-framecolor \fIcolor\^\fB]
[\-help]
[\-railcolor \fIcolor\^\fB]
[\-script]\fR
.PP
.B xabacus
is a computer implementation of the classic Chinese abacus.
.PP
An abacus has two decks,
an upper deck and a lower deck, which are separated by a beam.
Each deck normally has 13 rods, on which are mounted beads.
Each rod on the upper deck contains two beads;
each rod on the lower deck contains five beads.
Each bead on the upper deck has a value of five,
whereas each bead on the lower deck has value of one.
A bead is counted when you move it
.I toward
the beam that separates the decks:
thus, to count a beam on the upper deck, you slide it down;
whereas to count a bead on the lower deck, you slide it up.
.PP
This classic design,
which
.B xabacus
implements, permits you to count and perform addition and subtraction.
Some ``new and improved'' models of the abacus
have auxilliary decks stacked above the principal decks;
these permit you to perform multiplication and division, and compute
square roots.
.SH "Command-line Options"
.B xabacus
recognizes the following command-line options:
.IP "\fB\-bead-color \fIcolor\fR"
Set the beads to
.IR color .
The default is
.BR green4 .
.IP "\fB\-beadheight \fIheight\fR"
Make each bead
.I height
pixels high.
The default is 20.
.IP "\fB\-beadwidth \fIwidth\fR"
Make each bead
.I width
pixels wide.
The default is 30.
For the sake of authenticity,
a bead's width should be about two thirds greater than height.
If width equals the height, the beads will resemble circles.
.IP "\fB\-bg \fIcolor\fR"
Set the background to
.IR color .
The default is
.BR white .
Specifying a color other than the default results
in the beads having an unpredictable color.
This happens because
.B xabacus
XOR's the bead-image when animating it.
.IP "\fB\-demo \fIscriptpath\fR"
This option invokes a series of interactive tutorials that teach you how
to use the abacus.
.I scriptpath
names the directory in which you have installed the tutorial files
.BR Lesson1.cmd ,
.BR Lesson2.cmd ,
and
.BR Lesson3.cmd .
Customarily these are kept in directory
.BR /usr/X11/doc/xabacus ,
but this is not required.
.IP "\fB\-demofont \fIfont\fR"
.IS "\fB\-fn \fIfont\fR"
Use
.I font
as the font for the text displayed during the tutorials.
The default font is 18-point Times Roman; and the alternate font is
.BR 8x13 .
.IP "\fB\-framecolor \fIcolor\fR"
Give the frame
.IR color .
The default is
.BR brown .
.IP "\fB\-framewidth \fIwidth\fR"
Make the frame
.I width
pixels wide.
The default is ten.
The ``frame'' represents the wooden frame on which the wires are strung
and that separates the two decks.
.IP "\fB\-help\fR
Print a summary of these options.
.IP "\fB\-ncols \fInumber\fR"
Give your abacus
.I number
columns.
The default is 13; the maximum is 100.
.IP "\fB-railcolor \fIcolor\fR"
Set the rails to
.IR color .
The default is
.BR green4 .
.IP \fB\-script\fR
This tells
.B xabacus
to write to stdout a set of
row/column coordinates that record the beads you click.
You can redirect the output script into a file, and edit it to
create new tutorials.
.SH Operation
You can operate
.B xabacus
in either of two modes:
.I "demo mode"
or
.IR "normal mode" .
.PP
In normal mode, you can use
.B xabacus
to count and perform arithmetic, just like a real abacus.
To move a bead, touch it with the mouse cursor and click a mouse button:
the beads shift themselves to vacate the row and column that was clicked.
.B xabacus
beeps when you click a mouse button when the mouse cursor is touching
on an invalid location, such as the middle-frame.
.PP
You can resize the window to accomodate more columns; it resizes in width only.
.B xabacus
adds a column only if that column can be completely displayed within the window.
A maximum of 100 columns is possible; that is, you can use
.B xabacus
to count up to one googol.
You can also shrink the window, but not smaller than 13 columns' width.
.PP
To quit, press `Q' or
.BR <ctrl-C> .
.PP
In demo mode,
.B xabacus
is controlled by the tutorial scripts.
It opens a second window and asks you to move it directly below the abacus
window.
It then displays text in that window, and asks you for prompts.
To quit a demonstration, press `Q'
To restart the tutorials,
move the mouse cursor into the text window and click the left-mouse button.
.SH Resources
The application class name is
.BR XAbacus .
Every command-line option has its equivalent X resource as follows:
.nf
XAbacus
	.beadwidth
	.beadheight
	.framewidth
	.ncols
	.framecolor
	.bg
	.beadcolor
	.railcolor
	.demo
	.demofont
.fi
.SH SCRIPT-FILE FORMAT
The format of the lesson script-file (Lesson\fIn\fP.cmd) is as follows:
.DM
	<number of moves in the script>
	<row> <col> <number-of-text-lines-that-follow>
	text-line1
	    :
	    :
	text-line4
	<row> <col> <number-of-text-lines>
	text-line1
	    :
	    :
	text-line4
		:
		:
.DE
.PP
The text is displayed in the secondary window that appears during
the demonstration.
.B <number-of-text-lines-that-follow>
cannot exceed four lines of text.
Each row/col/text batch represents one ``move.''
Beginning a row with a negative number tells
.B xabacus
to ignore the move and just display the describe the descriptive text.
This is useful for explanatory pauses in the lesson.
.PP
For details, look at any of the tutorial files for
.BR xabacus .
.SH "See Also"
.B
X applications,
xcalc
.R
.SH Notes
.B xabacus
was written by
Luis Fernandes (lfernand@ryelect.uucp).
The author wishes to thank the following persons for their assistance:
.IP \(bu 0.3i
Agustine Lee,
instructor at the Ryerson Electrical Engineering Department,
who provided a real, live abacus and invaluable documentation on its use;
and also provided invaluable comments on improving the program.
.IP \(bu
Nick Colonello alpha-tested
.B xabacus
and provided constructive criticism.
.IP \(bu
Eva Dudova, who beta-tested the application.
.IP \(bu
And those before me who have written X-applications,
from whose code I have learned the art of X.
.PP
Copyright \(bu 1991, Luis Fernandes.
Permission to use, copy, hack, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation. 
This software is presented as is without any implied or written warranty.
