home *** CD-ROM | disk | FTP | other *** search
/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / TEXT / UTILITY / QUOTE24.ZIP / QUOTE.DOC < prev    next >
Encoding:
Text File  |  1991-04-04  |  12.2 KB  |  291 lines
  1.  
  2.  
  3.                                  QUOTE, v2.4
  4.                                 -------------
  5.                                 from TifaWARE
  6.  
  7.  
  8.  
  9.  
  10. What's New
  11. ----------
  12.  
  13.      With version 2.4 I have tweaked the code a bit more, adding a few
  14. assertions to aide in debugging and making use of some library routines I
  15. have developed. Users should not see any difference, apart from a much
  16. larger database of quotes included with the package!
  17.  
  18.      Version 2.3 of QUOTE contains an improved algorithm for randomly
  19. indexing into the quote database. It should now work ok even with small
  20. quote databases. Alas, the approach will mean somewhat slower performance
  21. since (a) two reads are done for each quote displayed and (b) quotes are
  22. displayed a character at a time. (Better buy that 486 machine now! :-)
  23.  
  24.      New to version 2.2 is a verbose reporting option - you can see at what
  25. point in the database each quote is selected. AT&T's getopt function is now
  26. used for a consistent method of option processing. Finally, two bugs were
  27. found and corrected: The first would cause unpredictable results if the
  28. database began with a '$'. The second would have made overflow errors more
  29. likely as the size of the database grew.
  30.  
  31.      Version 2.1 of QUOTE fixes a minor bug in the portion of code which
  32. computes a random location in the quote database. Previously, the index
  33. could be regarded as negative if the database exceeded roughly 32K in size.
  34. This would cause QUOTE to simply skip to the next iteration without
  35. printing any error message. This behaviour has been corrected, and QUOTE
  36. should now work correctly with files of any size.
  37.  
  38.      As of v2.0, QUOTE has been ported from assembler to C. This should
  39. make it easier to maintain and catch those inevitable bugs. Further, I
  40. expect it will mean the "randomness" of the quotes will improve now that 
  41. Turbo C's rand() function is used to generate random numbers; contrast this
  42. with my feeble assembler routine which merely indexed into memory a few
  43. times!  Also new to version 2.0 are commandline options to clear the
  44. screen, set the repetition count, display a brief help message, and (my
  45. favourite) alter QUOTE's default configuration. Refer to the source code
  46. for more specific information on QUOTE's revision history.
  47.  
  48.  
  49.  
  50.  
  51. Introduction
  52. ------------
  53.  
  54.  
  55.      If you've used a mainframe computer then you're probably familiar
  56. with some type of random quote generator; eg, Cookie, Button, Fortune,
  57. etc... Reading quotes is an interesting and thought-provoking way to pass
  58. the time.  After searching some software archives, though, I didn't find
  59. an adequate implementation for MS-DOS machines.  
  60.  
  61.      I wrote QUOTE to fill this void in MS-DOS and designed it so users
  62. could easily modify its behaviour.  QUOTE works by "randomly" selecting a
  63. quote from a database and then displaying it on the screen.  The selection
  64. is "random" only in the sense that if you run the program again you won't
  65. necessarily see the same quote, not in a strict statistical sense. QUOTE
  66. is also configurable from the commandline, in case you're not happy with
  67. its default behaviour.
  68.  
  69.      As of this writing, the default quote database (QUOTE.DAT) contains
  70. over 750 quotes.  Many of these reflect my inherent cynicism and reveal a
  71. lot about their authors; eg, "All the wastes in a year from a nuclear power
  72. plant could be stored under a desk." or "Abortion is advocated only by
  73. persons who have themselves been born." (both from Ronald Reagan).  I've
  74. found them while reading books, magazines, newspapers, etc...  as well as
  75. in compilations such as _Familiar Quotations_ (Bartlett) and _The Experts
  76. Speak_ (Cerf & Navasky).  Most are in English, some in Latin (with
  77. translations), and a few are in Spanish (w/ and w/o translations). 
  78.  
  79.      If you share my sense of humour, you may be content to use QUOTE with
  80. the database distributed with the program.  Don't be afraid to make
  81. changes though - it's quite easy.  The only thing you'll need is an editor
  82. or word processor capable of handling straight ASCII files.  Each quote
  83. (except the first) must be delimited by dollar signs, '$', and be no longer
  84. than 512 characters.  [Note that quotes cannot contain a dollar sign as
  85. part of the quote.] There are no other restrictions on the format of the
  86. quotes.  Quotes can take up 2 lines or 10, or whatever! Whatever you put
  87. between two dollar signs will be treated as a quote.  You can even use ANSI
  88. ESCape sequences to give emphasis to certain quotes or position them on the
  89. console! It's that simple!
  90.  
  91.  
  92.  
  93.  
  94. Usage
  95. -----
  96.  
  97.  
  98.      QUOTE's operation is straightforward. As distributed, QUOTE will
  99. display a single random quote on the screen if it's invoked with no
  100. arguments. Options are provided to permit the user to clear the screen
  101. first, to display multiple quotes, to use an alternate quote database, or
  102. even to alter QUOTE's default configuration. After you've placed the
  103. program where DOS can find it, type QUOTE -? at the DOS prompt. You should
  104. see a brief help message similar to the following:
  105.  
  106.      TifaWARE QUOTE, v2.4a, displays randomly selected quotes.
  107.      Copyright (c) 1991 by TifaWARE/George A. Theall.
  108.      
  109.      Usage:  quote [options] [qdat]
  110.      
  111.      Options:
  112.        -c      = configure program using current arguments
  113.        -rn     = set the repetition count to n quotes
  114.        -s[+,-] = clear/don't clear screen first
  115.        -v      = verbose reporting
  116.        -?      = provide this help message
  117.      
  118.      Qdat refers to the quote database. If it's not specified, then file
  119.      QUOTE.DAT will be used.
  120.  
  121. [If you don't remember anything else from reading the documentation, at
  122. least remember how to display this help message.]
  123.  
  124.      You probably won't find the '-v' option of must interest. It's mostly
  125. for debugging purposes - in case QUOTE claims some quotes are invalid.
  126. When you select this option, QUOTE will tell you the name of the database
  127. as well as what part of the database (in terms of characters) it has
  128. selected.
  129.  
  130.      The '-s' is used to clear the screen before displaying any quotes.
  131. Note that QUOTE looks for a supplemental argument following this option. If
  132. this argument begins with a '+', the screen will be cleared; otherwise, it
  133. will not. Only the first character matters; ie., "-s+", "-s +", "-s+c" and
  134. "-s +junk" all mean the same to QUOTE.
  135.  
  136.      If you're really bored with work, you'll probably get a lot of use out
  137. of the '-r' option. Simply specify the repetition count immediately after
  138. the '-r'; eg, '-r3', and QUOTE will display as many as you want. Note: if
  139. you call for 25000 quotes, you'll get 'em!
  140.  
  141.      The '-c' option lets you alter QUOTE's default configuration (with the
  142. exception of the '-?', '-v' and '-c' options). Assuming the program itself
  143. is on a disk with write-access (and, if you're running MS-DOS v2.xx, that
  144. it's in the current directory), you can update QUOTE's configuration by
  145. specifying '-c' along with whatever arguments you'd like. For example,
  146. suppose you'd like to scan C:\USR\ETC\Quote.Dat for quotes and clear the
  147. screen first by default. Simply type "QUOTE -c -s+ C:\USR\ETC\Quote.Dat"
  148. once; from then on, QUOTE will read from the specified file and erase the
  149. screen first unless you explicitly override this behaviour with a different
  150. set of commandline arguments.
  151.  
  152.      Only one other argument can be used with QUOTE - the name of an
  153. alternate quote database. And this must follow any options you might
  154. specify.  If more than one name is found, it's assumed you need help with
  155. QUOTE's usage.
  156.  
  157.      All regular output from QUOTE is written to a device called stdout,
  158. which is normally your computer's screen.  Using the DOS redirection
  159. characters '>' and '|', you could send this output to a disk file, printer,
  160. or even use it as input into another program.  [Refer to your DOS manual
  161. for more information on output redirection.] The flexibility of this
  162. approach should be clear. 
  163.  
  164.  
  165.  
  166.  
  167. If You Have Any Trouble
  168. -----------------------
  169.  
  170.  
  171.      QUOTE will attempt to let you know of any problems that arise.  Here
  172. are the messages you might see and how you should deal with them:
  173.  
  174.      quote: illegal option -- x.
  175.           - Type "QUOTE -?" for a list of valid options.
  176.  
  177.      quote: option requires an argument -- x.
  178.           - Type "QUOTE -?" for a list of valid options and supply
  179.             supplemental arguments as necessary.
  180.  
  181.      quote: invalid rep count; 1 used instead.
  182.           - You must specify a positive integer when invoking QUOTE
  183.             with the '-r' option. Note the program makes no attempt
  184.             to second-guess the user here; ie, it's just as happy
  185.             with a repetition count of 9381 as with one of 2.
  186.  
  187.      quote: unable to write new configuration to QUOTE.COM.
  188.           - To configure the program, QUOTE needs write-access to a
  189.             copy of itself. If you're not running MS-DOS v3.x or
  190.             better, QUOTE.COM must be in the current directory when
  191.             configuring; otherwise, this message probably means the
  192.             drive with QUOTE.COM is write-protected.
  193.  
  194.      quote: new configuration of QUOTE.COM accepted.
  195.           - This is only an informative message, not an error. It
  196.             means exactly what it says.
  197.  
  198.      quote: can't open QUOTE.DAT.
  199.           - QUOTE was unable to open the specified quote database.
  200.             Check the spelling and make sure the file actually 
  201.             exists. If it does, your drive's likely bad.
  202.  
  203.      quote: invalid quote found around ==>blah, blah, blah...<==.
  204.           - When QUOTE finds a bad quote, it prints the contents
  205.             of its buffer. Make sure that the offending quote is
  206.             is delineated by '$'s and that no quote is larger than
  207.             512 characters; some editing may be necessary to meet 
  208.             this limit. Also, don't forget the first quote must 
  209.             *not* begin with a '$'.
  210.  
  211.      quote: error while reading from QUOTE.DAT.
  212.           - This error should never occur, but... It means QUOTE
  213.             managed to open the database but encountered an error
  214.             when selecting a random quote.
  215.  
  216. These error messages are written to the standard error device.  In this
  217. way, they won't disappear down a pipe or into a file should you try to
  218. redirect QUOTE's output. 
  219.  
  220.      Additionally, QUOTE uses a return code to convey information about
  221. the success or failure of its operation.  Possible return values are:
  222.  
  223.      Code      Meaning
  224.      ----      -------
  225.      0         Success
  226.      1         Help message was displayed
  227.      2         Program was configured
  228.      10        Unable to open file
  229.      15        Trouble reading from file
  230.      20        Unable to write to device
  231.  
  232. You can test for these codes using the ERRORLEVEL variable in a batch file. 
  233.  
  234.  
  235.  
  236.  
  237. Requirements
  238. ------------
  239.  
  240.  
  241.      TifaWARE QUOTE runs on machines operating under MS-DOS v2.xx or later,
  242. and requires roughly 15K of memory.  It uses a BIOS call to clear the
  243. screen but does not otherwise require PC-compatibility.
  244.  
  245.  
  246.  
  247.  
  248. Who Owns It?
  249. ---------------
  250.  
  251.  
  252.      The source code for QUOTE is public domain. I do, however, retain the
  253. copyright on the compiled program in order to abide by the license
  254. agreement for TURBO C++; you may freely redistribute and use it.
  255.  
  256.      QUOTE carries no obligation on my part to support users or provide
  257. future upgrades. I have tried to write clean code and believe it to be
  258. "bug-free". Nevertheless, you must use this program ***AT YOUR OWN
  259. RISK***.
  260.  
  261.      As author of QUOTE, I ask of you two things: First, if you
  262. redistribute this program please keep together my original source code,
  263. documentation, and executable.  This just makes it easier for others to
  264. use the software. Second, let me hear what you think of QUOTE - your
  265. comments on a postcard would be appreciated. Enjoy!
  266.  
  267.  
  268.  
  269.  
  270. Kudos
  271. -----
  272.  
  273.  
  274.      Borland deserves a great deal of credit for its compiler and stand-
  275. alone debugger. Together these products make C programming a joy. 
  276.  
  277.  
  278.  
  279.  
  280.  
  281.                           George A. Theall
  282.  
  283.                              TifaWARE
  284.                        506 South 41st St., #3M
  285.                       Philadelphia, PA.  19104
  286.                               U.S.A.
  287.  
  288.                          +1 215 662 0558
  289.  
  290.                 GTHEALL@PENNDRLS.UPENN.EDU (Internet)
  291.