Category : C Source Code
Archive   : QUOTE25B.ZIP
Filename : QUOTE.DOC

QUOTE, v2.5
-------------
from TifaWARE




What's New
----------

The creation of the USENET newsgroup alt.quotations has rekindled my
interest in this little gem. It has not only served as a source for new
material but also encouraged me to have another look at the source code.
The result is a significant performance gain in version 2.5 since quotes
are displayed as a whole rather than one character at a time.

With version 2.4 I have tweaked the code a bit more, adding a few
assertions to aide in debugging and making use of some new library
routines. Users should not see any difference, besides a much larger
datafile of quotes!

Version 2.3 of QUOTE contains an improved algorithm for randomly
indexing into the quote datafile. It should now work ok even with small
quote datafiles. Alas, the approach will mean somewhat slower performance
since (a) two reads are done for each quote displayed and (b) quotes are
displayed one character at a time.

New to version 2.2 is a verbose reporting option - you can see at
what point in the datafile each quote is selected. I now use AT&T's getopt
function for a consistent method of option processing. Finally, I found
and corrected two bugs: The first would cause unpredictable results if the
datafile began with a '$'. The second would have made overflow errors more
likely as the size of the datafile grew.

Version 2.1 of QUOTE fixes a minor bug in the portion of code that
indexes randomly into the quote datafile. Before, the index could be
treated as negative if the datafile exceeded roughly 32K in size. This
would cause QUOTE simply to skip to the next iteration without printing
any error message. QUOTE should now work correctly with files of any size.

As of v2.0, I have ported QUOTE from assembler to C. This should make
it easier to maintain and catch those inevitable bugs. Further, I expect
it will mean the "randomness" of the quotes will improve now that Turbo
C's rand() function is used to generate random numbers. Contrast this with
my feeble assembler routine that merely indexed into memory a few times!
Also new to version 2.0 are commandline options to clear the screen, set
the repetition count, display a brief help message, and (my favourite)
alter QUOTE's default configuration. Refer to the source code for more
specific information on QUOTE's revision history.




Introduction
------------


If you've worked with a mainframe you're probably familiar with
random quote generators; eg, Cookie, Button, Fortune... Reading quotes is
an interesting and thought-provoking way to pass the time. After searching
some software archives, though, I realized an adequate implementation for
DOS machines did not exist.

I wrote QUOTE to fill this void in DOS and designed it so users could
easily modify its behaviour. QUOTE works by "randomly" selecting a quote
from a datafile and then displaying it on the screen. The selection is
"random" only in the sense that if you run the program again you won't
necessarily see the same quote, not in any statistical sense. QUOTE is
also configurable from the commandline, in case you're not happy with its
default behaviour.

As of this writing, the default quote datafile (QUOTE.DAT) contains
over 1000 quotes. Many reflect my inherent cynicism and reveal a lot about
their authors; eg, "All the wastes in a year from a nuclear power plant
could be stored under a desk." or "Abortion is advocated only by persons
who have themselves been born." (both from Ronald Reagan). I've uncovered
many through books, newspapers, the net (esp. alt.quotations on USENET)
etc... as well as in compilations such as _Familiar Quotations_ (Bartlett)
and _The Experts Speak_ (Cerf & Navasky). I have also taken quite a few
from Peter Summers' WISDOM package (currently on SIMTEL20 as WISDOM2.ZIP).
Most are in English; a few are in Latin and Spanish (w/ and w/o
translations).

If you share my sense of humour, you may be content to use QUOTE with
the default datafile. Don't be afraid to make changes though - it's easy.
You'll need only an editor or word processor capable of handling straight
ASCII files. Each quote (except the first) must be delimited by dollar
signs, '$', and be no longer than 512 characters. [Note that quotes cannot
contain a dollar sign as part of the quote.] There are no other
restrictions on the format of the quotes. Quotes can take up 2 lines or 10,
or whatever! Whatever you put between two dollar signs will be treated as a
quote. You can even use ANSI ESCape sequences to give emphasis to certain
quotes or position them on the console. It's that simple!




Usage
-----


QUOTE's operation is straightforward. As distributed, QUOTE will
display a single random quote on the screen if you invoke it without
arguments. Options are provided to permit the user to clear the screen
first, to display multiple quotes, to use an alternate quote datafile, or
even to alter QUOTE's default configuration. After you've placed the
program where DOS can find it, type QUOTE -? at the DOS prompt. You should
see a brief help message similar to the following:

TifaWARE QUOTE, v2.5b, displays randomly selected quotes.
Copyright (c) 1991-1993 by TifaWARE/George A. Theall.

Usage: quote [options] [qdat]

Options:
-c = update program configuration
-rn = set repetition count to n
-s[+,-] = clear/don't clear screen first
-v = verbose reporting
-? = provide this help message

Qdat refers to the quote datafile; it defaults to quote.dat.

[If you don't remember anything else from reading the documentation, at
least remember how to display this help message.]

You probably won't find the '-v' option of much interest. It's mostly
for debugging purposes, in case QUOTE claims some quotes are invalid. When
you select this option, QUOTE reports the name of the datafile and the
point at which it begins searching for a quote.

The '-s' option is used to clear the screen before displaying any
quotes. Note that QUOTE looks for an argument following this option. Only
if this begins with a '+', the screen will be cleared. Just the first
character matters; ie., "-s+", "-s +", "-s+c" and "-s +junk" all mean the
same to QUOTE.

If you're really bored with work, you'll probably get a lot of use
out of the '-r' option. Simply specify the repetition count immediately
after the '-r' (eg, '-r3') and QUOTE will display as many as you want.
Note: if you call for 25000 quotes that's how many you'll get!

The '-c' option lets you alter QUOTE's default configuration (except
for the '-?', '-v' and '-c' options). Assuming the program itself is on a
disk with write-access (and, if you're running DOS v2.xx, that it's in the
current directory), you can update QUOTE's configuration by specifying '-c'
with whatever arguments you'd like. For example, suppose you'd like to scan
C:\USR\ETC\Quote.Dat for quotes and clear the screen first by default.
Simply type "QUOTE -c -s+ C:\USR\ETC\Quote.Dat" once. From then on QUOTE
will read from the specified file and erase the screen first unless you
explicitly tell it otherwise with a different set of commandline arguments.

Only one other argument can be used with QUOTE - the name of an
alternate quote datafile. And this must follow any options you might
specify. If more than one name is found, it's assumed you need help with
QUOTE's usage.

QUOTE writes all regular output to a device called stdout, normally
your computer's screen. Using the DOS redirection characters '>' and '|',
you could send this output to a disk file, printer, or even use it as
input into another program. [Refer to your DOS manual for more
information on output redirection.] The flexibility of this approach
should be clear.




If You Have Any Trouble
-----------------------


QUOTE will attempt to let you know of any problems that arise. Here
are the messages you might see and how you should deal with them:

quote: illegal option -- x.
- Type "QUOTE -?" for a list of valid options.

quote: option requires an argument -- x.
- Type "QUOTE -?" for a list of valid options and supply
supplemental arguments as necessary.

quote: invalid rep count; 1 used instead.
- You must specify a positive integer when invoking QUOTE
with the '-r' option. Note the program makes no attempt
to second-guess the user here; ie, it's just as happy
with a repetition count of 9381 as with one of 2.

quote: can't write to QUOTE.COM.
- To configure the program, QUOTE needs write-access to a
copy of itself. If you're not running DOS v3.x or
better, QUOTE.COM must be in the current directory when
configuring; otherwise, this message probably means the
drive with QUOTE.COM is write-protected.

quote: can't open QUOTE.DAT.
- QUOTE was unable to open the specified quote datafile.
Check the spelling and make sure the file actually
exists. If it does, your drive's likely bad.

quote: invalid quote found around ==>blah, blah, blah...<==.
- When QUOTE finds a bad quote, it prints the contents
of its buffer. Make sure that the offending quote is
is delineated by '$'s and that no quote is larger than
512 characters; some editing may be necessary to meet
this limit. Also, don't forget the first quote must
*not* begin with a '$'.

quote: error reading from QUOTE.DAT.
- This error should never occur, but... It means QUOTE
managed to open the datafile but encountered an error
when selecting a random quote.

These error messages are written to the standard error device. In this
way, they won't disappear down a pipe or into a file should you try to
redirect QUOTE's output.

Additionally, QUOTE uses a return code to convey information about
the success or failure of its operation. Possible return values are:

Code Meaning
---- -------
0 Success
1 Help message was displayed
10 Unable to open file
15 Trouble reading from file
20 Unable to write to device

You can test for these codes using the ERRORLEVEL variable in a batch file.




Requirements
------------


TifaWARE QUOTE runs on machines operating under DOS v2.xx or later,
and requires under 20K of memory. It uses a BIOS call to clear the screen
but does not otherwise require PC-compatibility.




Who Owns It?
---------------


The source code for QUOTE is public domain. I do, however, retain the
copyright on the compiled program to abide by the license agreement for
Borland C++. You may freely redistribute and use it.

QUOTE carries no obligation on my part to support users or provide
future upgrades. I have tried to write clean code and believe it to be
"bug-free". Nevertheless, you must use this program ***AT YOUR OWN
RISK***.

As author of QUOTE, I ask that you keep together my original source
code, documentation, and executable if you redistribute this package.
Also, please let me hear what you think of QUOTE - I'd appreciate a
postcard with your comments. Enjoy!




Kudos
-----


Borland deserves much credit for its compiler and standalone
debugger. Together these products make C programming a joy.

And thanks also to Peter Summers ([email protected])
for allowing me to borrow freely from his WISDOM package, another random
quote generator.






George A. Theall

TifaWARE
610 South 48th St
Philadelphia, PA. 19143
U.S.A.

[email protected]
[email protected]
[email protected]
[email protected]