home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: OtherApp / OtherApp.zip / quot100x.zip / doc / quoter.txt < prev   
Text File  |  1997-04-06  |  13KB  |  269 lines
  1. ================================================================================
  2.                           The Quoteriser, Version 1.00
  3.                                  User's Guide
  4. ================================================================================
  5.  
  6.   Contents:
  7.  
  8.     1. Installation
  9.     2. How the Quoteriser Works
  10.        (a) Quote Databases
  11.        (b) Author Databases
  12.     3. Using the Quoteriser
  13.        (a) Using Databases
  14.        (b) Managing Quotes
  15.        (c) Managing Authors
  16.        (d) Quoteriser HTML
  17.        (e) Settings
  18.     4. Quotes of the Day
  19.     5. The Future
  20.  
  21. --------------------------------------------------------------------------------
  22.  
  23. 1. Installation
  24.  
  25. The zip file, when expanded (with -d if using PKZIP), automatically creates the
  26. directory structure assumed by the Quoteriser. The files are:
  27.  
  28.   doc\COPYING    - a copy of the GNU General Public License
  29.   doc\intro.txt  - an introduction to the Quoteriser
  30.   doc\quoter.txt - this file
  31.   bin\quoter.exe - the Quoteriser's main program
  32.   bin\qotd.exe   - the Quote-of-the-Day program
  33.   bin\quoter.ico - the Quoteriser icon
  34.  
  35. Of course, you don't need the documentation to run the program. However, the
  36. Quoteriser expects a file "..\doc\COPYING" to exist when you try to view the
  37. license from within the program and if you move the .EXE's, this function will
  38. no longer work correctly.
  39.  
  40. You will probably want to create icons on your desktop to start up quoter.exe
  41. (the interface to the database manager) and qotd.exe. Put a shadow of the
  42. qotd.exe object in your StartUp folder if you want a quote to be displayed every
  43. time you boot up.
  44.  
  45. If you decide to move the Quoteriser, the other file you will need to move is
  46. bin\QUOTER.INI. This contains the settings information for the Quoteriser. It
  47. is created by the Quoteriser main program when it needs it (i.e. when you
  48. select non-default settings or set a Quote-of-the-Day database).
  49.  
  50. --------------------------------------------------------------------------------
  51.  
  52. 2. How the Quoteriser Works
  53.  
  54. Every quote in a Quoteriser database is associated with a unique alpha-numeric
  55. code that can be up to 19 characters long. Every author in an author database
  56. similarly has a unique code up to 19 characters long. These codes are what the
  57. program uses to uniquely identify the information stored in a database.
  58.  
  59.  
  60.   (a) Quote Databases
  61.  
  62. A quote database is composed of two files, <database>.qdb and <database>.tdb,
  63. where <database> can be any valid file name stem. Both files are GNU DBM files.
  64.  
  65. The .qdb file stores the following information about the quote:
  66.  
  67.     * a code identifying the quote's author [up to 19 characters]
  68.     * a string containing information about the quote's source [up to 99
  69.          characters]
  70.     * up to five keywords describing the subject matter of the quote [each
  71.       keyword can be up to 19 characters long]
  72.  
  73. The author code is the one assigned to the quote's author in the author
  74. database being used. Of course, there is nothing stopping anyone from having
  75. the same author in two different databases with a different code, and this
  76. may cause trouble when using the system. It is not recommended that the user
  77. keeps more than one author database.
  78.  
  79. The .tdb file stores the text of the quote itself, which can be typeset using
  80. simple HTML commands (see below).
  81.  
  82.  
  83.   (b) Author Databases
  84.  
  85. An author database is also composed of two files, <database>.adb and
  86. <database>.ddb, where <database>, again, can be any valid file name stem.
  87. Both these files are also GDBM files.
  88.  
  89. The .adb file stores the following information about the author:
  90.  
  91.     * the author's given name [up to 49 characters]
  92.     * the author's surname [up to 49 characters]
  93.     * the author's year of birth
  94.     * the author's year of death
  95.  
  96. The .ddb file contains a free-form biographical entry for the author, which can
  97. also be typeset with simple HTML commands.
  98.  
  99. --------------------------------------------------------------------------------
  100.  
  101. 3. Using the Quoteriser
  102.  
  103.  
  104. All real interaction with the Quoteriser is done via the main program. This
  105. application allows the user to manage quote and author databases in all the
  106. obvious ways.
  107.  
  108.   (a) Using Databases
  109.  
  110.   Quote and author databases are open and closed like any other file using the
  111. File menu. You must have a quote database open to be able to use to use quote
  112. management functions, and you must have an author database open to be able to
  113. use author management functions. Only one database of each type may be open at
  114. once.
  115.   When you try to open a database, you will be presented with the standard OS/2
  116. file dialogue, which shows *.qdb files (for quote databases) or *.adb files (for
  117. author databases). You can open a database that already exists, or create a new
  118. one by typing in the name of your new database. The *.tdb and *.ddb files are
  119. assumed from the *.qdb or *.adb file you are using; hence, you should not rename
  120. your database files to a non-standard convention.
  121.   In addition to the open and close functions on the file menu, you will see two
  122. more options to re-organise the quote database and the author database. These
  123. functions will de-fragment the open database. When data is deleted from a
  124. database, it leaves a gap. The Quoteriser will try to fill these gaps when new
  125. information is stored in the database; however, if you have done a lot of
  126. deletions without any additions, you might wish to pack your database to save
  127. some disk space.
  128.  
  129.   (b) Managing Quotes
  130.  
  131.   Once you have opened a quote database, you can manipulate the quotes within
  132. by adding more quotes, editing old quotes or deleting old quotes. You can also
  133. view quotes, and perform some simple searches on them.
  134.  
  135.   To add a new quote, choose "Add" from the Quote menu. A dialogue box will
  136. pop up into which you can enter information about the quote. You *must* enter
  137. a quote code; everything else is optional. If there is already a quote with
  138. the same code in your database, that quote will be overwritten with the new one.
  139.   In the "Keywords" box, type in your chosen keywords separated by spaces.
  140.   If you press the "Text" button, you will be able to edit the text of the quote
  141. itself using the editor of your choice (see "Settings" below). Text can be
  142. entered in a simple HTML format, described below. Save the text and exit the
  143. editor to come back to the Quoteriser.
  144.   Press "Okay" to add your new quote to the database, or "Cancel" if you have
  145. changed your mind. Warning: you will not be warned if a quote this code already
  146. exists.
  147.  
  148.   To edit a pre-existing quote, choose "Edit" from the Quotes menu. You will
  149. be given a list of all the codes of quotes in the database, and asked to choose
  150. one to edit. Once you have chosen one, you will be taken to the same dialogue
  151. box as for adding a quote, where you can edit the information as you see fit.
  152.  
  153.   To delete a pre-existing quote, choose "Delete" from the Quotes menu. As for
  154. editting, you will be presented with a list of codes to choose from. Choose the
  155. offending code and the quote will be deleted.
  156.  
  157.   You can view quotes by choosing "View" from the Quotes menu. A sub-menu will
  158. appear, allowing to choose which codes are displayed:
  159.  
  160.   "List all"   lists all quotes in the database.
  161.   "By keyword" lists only quotes with a given keyword, which you will be asked
  162.                to type in.
  163.   "By text"    lists only quotes with a given sub-string, which you will be
  164.                asked to type in.
  165.   "By author"  lists all quotes by a given author; you will need to supply the
  166.                program with the appropriate author code.
  167.  
  168.   (c) Managing Authors
  169.  
  170.   Once you have opened an author database, you can manipulate the authors within
  171. exactly the same way as you edit the quote database.
  172.  
  173.   When viewing authors, you are able to choose which codes are displayed:
  174.  
  175.   "List all"        lists all authors in the database.
  176.   "By name"         lists only the authors with a name you type in; this can be
  177.                     either their first or last name.
  178.   "By description"  lists only the authors containing a given sub-string in
  179.                     their description.
  180.  
  181.   (d) Quoteriser HTML
  182.  
  183.   Both quote texts and author descriptions can be typeset using simple HTML
  184. tags:
  185.  
  186.   <i> ... </i> - enclosed text is in italics
  187.   <b> ... </b> - enclosed text is in bold
  188.   <br>         - insert a line break here
  189.   <p>          - insert a paragraph break here
  190.  
  191.   These tags are hopefully sufficient for the purpose of reproducing quotes
  192. in their original form. At this stage, I may add the <pre> tag in a later
  193. version, but I will not add any other tags unless someone can convince me
  194. that they would be useful in reproducing quotes.
  195.   You can also use HTML macros beginning with the '&' character, such as:
  196.  
  197.   &   - ampersand
  198.   <    - less-than sign
  199.   >    - greater-than sign
  200.  
  201.   Since '&', '<', and '>' have special meaning in HTML, you *must* use the above
  202. macros to be able to typeset these characters. In fact, all of ISO Latin-1 is
  203. supported; however, the program blindly sends characters to the screen using
  204. their ISO Latin-1 number. Hence, non-ASCII characters may not turn out correctly
  205. if your font and codepage do not match ISO Latin-1 (which, I'm afraid, counts
  206. for most of them, I think). Other character sets are not supported at all, I'm
  207. afraid.
  208.   You can find the complete list of ISO Latin-1 characters and HTML macros from
  209. the W3 Consortium at http://www.w3.org.
  210.  
  211.   (e) Settings
  212.  
  213.   This release of the Quoteriser has just one setting, albeit a setting that
  214. comes in two parts. This is the selection of the editor to be used to edit
  215. quote text and author biographies. If this is not set, the Quoteriser will
  216. use the OS/2 system editor, E.EXE. Any editor that saves its output in normal
  217. plain text or HTML format should do; however, many HTML editors add a lot of
  218. extra code that the Quoteriser does not understand and will only use up your
  219. disk space and memory area to no purpose.
  220.   In the "Editor" field of the settings box, type in the name of the program
  221. you want to use as your editor. In the "Paramaters" field, type in the
  222. command-line parameters to pass to your editor. The % symbol represents the
  223. name of the temporary file used by the Quoteriser (i.e. the file to be editted).
  224.  
  225. --------------------------------------------------------------------------------
  226.  
  227. 4. Quotes of the Day
  228.  
  229.   Like any other quote-of-the-day program, the Quoteriser's Quote-of-the-Day
  230. program is simply a program which chooses a random quote from a database and
  231. displays it on the screen.
  232.   Use the Quoteriser main program to set up the Quote-of-the-Day utility by
  233. choosing the Quote-of-the-Day option on the main menu. This will present you
  234. with a dialogue box which allows you to enter the name of the quote database
  235. and the author database.
  236.   The quote database must be set (obviously). The author database is optional;
  237. if you do not set it, your quote will appear without its author. It will also
  238. appear without its author if you don't set an author code, or its author code
  239. is not found in the specified database.
  240.   When the quote appears on the screen, you have only one choice of action:
  241. choose "Exit".
  242.  
  243. --------------------------------------------------------------------------------
  244.  
  245. 5. The Future
  246.  
  247.   I hope future versions of the Quoteriser will be improvements upon the humble
  248. version 1.00. In no particular order:
  249.  
  250.   - more friendly choose-quote and choose-author dialogue boxes
  251.   - a scrolling main window (for long quotes and biographies)
  252.   - regular expression searching of databases
  253.   - DLLs to cut executable duplication in quoter.exe and qotd.exe
  254.   - better handling of non-English text (but non-Latin languages will probably
  255.     have to wait for the W3 Consortium to finalise Unicode).
  256.   - various utilities for merging databases, fixing broken databases, etc.
  257.   - font and colour selection
  258.   - many little improvements to the interface
  259.  
  260.  On-line documentation will also come if I one day decide to part with enough
  261. of my money to buy a copy of IPFC. At the moment, I'm far too stingy. Maybe
  262. I'll HTML it one day...
  263.  
  264.   I will accept feature requests and suggestions at nps@modemss.brisnet.org.au;
  265. whether or not I act them, and how quickly I act them, depends on how desirable
  266. I consider the features, how difficult they are to implement and how much time
  267. I have on my hands (in that order). Please refer to the source code
  268. documentation (qsource.txt) if you want to fiddle with the source code yourself.
  269.