The Quoteriser, Version 2.10

Contents:

  1. Basic Quoteriser notions
    1. Quote databases
    2. Author databases
  2. Using the Quoteriser
    1. Using databases
    2. Managing quotes
    3. Managing authors
    4. The clipboard
  3. Quoteriser settings
    1. Main settings
    2. Quote-of-the-day settings
  4. A Quoteriser reference
    1. Quoteriser HTML
    2. Regular expressions
  5. Related utilities

Basic Quoteriser notions

Every quote in a Quoteriser database is associated with a unique alpha-numeric code that can be up to 19 characters long. Every author in an author database similarly has a unique code up to 19 characters long. These codes are what the program uses to uniquely identify the information stored in a database.

Databases are have filename extensions of .?db, where ? is one of q, t, a or d, depending on what part of a database this file represents. When specifying names of databases to the Quoteriser, the user must omit this extension; the Quoteriser will fill in the necessary extensions in the process of opening particular files.

The Quoteriser can be made to open databases at start-up by giving it the -q <quote database> and -a <author database> options on the command line.

Quote databases

A quote database is composed of two files, <database>.qdb and <database>.tdb, where <database> can be any valid file name stem. Both files are GNU DBM files.

The .qdb file stores the following information about the quote:

The author code is the one assigned to the quote's author in the author database being used. Of course, there is nothing stopping anyone from having the same author in two different databases with a different code, and this may cause trouble when using the system. It is not recommended that the user keeps more than one author database.

The .tdb file stores the text of the quote itself, which can be typeset using simple HTML commands (see below).

Author databases

An author database is also composed of two files, <database>.adb and <database>.ddb, where <database>, again, can be any valid file name stem. Both these files are also GDBM files.

The .adb file stores the following information about the author:

The .ddb file contains a free-form biographical entry for the author, which can also be typeset with simple HTML commands described below.

Using the Quoteriser

Using Databases

Quote and author databases are open and closed like any other file using the File menu. A quote database must be open to be able to use to use quote management functions, and an author database must be open to be able to use author management functions. Only one database of each type may be open at once.

When trying to open a database, the standard OS/2 file dialogue will appear, which shows *.qdb files (for quote databases) or *.adb files (for author databases). A database that already exists can be opened in the usual fashion, or a new database can be created by typing in the name of the new database (the user will be asked to confirm creation). The *.tdb and *.ddb files are assumed from the *.qdb or *.adb file that is specified.

The last quote and author databases in use may also be opened quickly by choosing the last option on the File menu, i.e. the option showing the names of these databases. This option will not appear if there have been no databases in use before.

In addition to the open and close functions on the File menu, there are two more options to re-organise the quote database and the author database. These functions will de-fragment the open database. When data is deleted from a database, it leaves a gap. The Quoteriser will try to fill these gaps when new information is stored in the database; however, if the database has undergone a lot of deletions with few additions, packing the database in this fashion may save space.

It may happen that the Quoteriser is not able to gain write access to the database, e.g. if the database has been marked as read-only, or it has been already opened by another application. In this case, functions requiring write access (such as adding, editing and re-organising) will be disabled.

Managing quotes

Once a quote database has been opened, the quotes within can be manipulated using the Quote menu. The user can add a new quote, edit or delete old quotes, view/search the quotes, and import quotes from another database.

To add a new quote, choose the Add option from the Quote menu. A dialogue box into which to enter quote information will appear. The quote code must be specified; all other entries are optional.

In the Keywords entry field, the keywords should be separated by spaces.

The text of the quote can be edited by pressing the Text button. This will start the text editor specified in the settings, where the quote text can be typeset using simple HTML. Make sure the file is saved before pressing the Okay button.

Pre-existing quotes can be edited by choosing Edit from the Quote menu. The user can edit the current quote (if there is one), or choose from the list of quotes in the database. A dialogue box like the one used for adding quotes will appear, which can be used to edit the quote as necessary using the same procedure.

Quotes can be deleted by choosing Delete from the Quote menu. The user can delete the current quote (if there is one), or choose from the list of quotes in the database. Warning: there is no undelete function, so be careful.

Quotes in the database can be viewed using the View sub-menu of the Quote. Each option of the View sub-menu causes a different list of quotes to be displayed for choosing:

List all
Lists all quotes in the database.
By keyword
Lists all the quotes associated with a particular keyword; the user will be asked to type this in. Regular expressions may be used.
By text
Lists all the quotes containing a regular expression given by the user.
By author
Lists all the quotes from a given author, which can be selected from the list of authors in the currently open author database. This option is not available if there is no author database open.

Another database can be imported into the currently-open database by choosing the Import option from the Quote menu. The user will be presented with a dialogue box asking for the name of the database to import, and giving several options for what to do about codes which exist in both the open database and the database being imported:

Replace all
Replace quotes in the open database with ones from the database being imported.
Replace none
Do not import any quotes whose code already exists in the open database
Ask
Prompt the user for action whenever a duplicate code is found.
The Duplicate codes setting does not affect codes being imported that do not clash with codes already existing in the open database.

Managing authors

With an author database open, authors can be manipulated in exactly the same way quotes are manipulated, using the Author menu. Adding, editing, deleting and importing are the same. The View sub-menu has the following options:
List all
Lists all the authors in the database
By name
Lists all the authors with a name typed in by the user, which may be their given name or surname, and may be a regular expression, given by the user, in their descriptions.

The clipboard

The Quoteriser can interact with other applications via the clipboard. When a quote or author is displayed on the screen, it can be copied to the clipboard using the Edit menu. Once copied to the clipboard, it can be pasted into another application - see the other application's documentation for how to paste into it.

Copy as text will copy the display to the clipboard as plain text, suitable for pasting into text editors and word processors. This will destroy some of the formatting of the quote; obviously italics and boldface cannot be rendered in plain text. Line-wrapping will also be removed (to allow the pasting application to wrap as it sees fit).

Copy as metafile will copy the display to the clipboard as a metafile, suitable for pasting into graphics applications. This method will preserve all of the formatting.


Quoteriser settings

Main settings

The main Quoteriser settings are accessed via the Settings option in the File menu:

Editor
The name of the text (or HTML) editor to use for editing quote texts and author descriptions. The default is the OS/2 system editor, E.EXE.
Editor parameters
Parameters to pass to the text editor; the % symbol represents the name of the file to edit. The default is '%'.
Path to data
The default path in which to look for databases. There is no default.
Path to documentation
The path to the Quoteriser documentation. The default is the 'doc' directory in the parent directory of the working directory.
Browser
The name of the HTML browser to use (for viewing the documentation). The default is WebExplorer, EXPLORE.EXE
Browser parameters
Parameters to pass to the HTML browser; the % symbol represents the name of the document to view. The default is '%'.

Quote-of-the-day settings

The Quote-of-the-day option brings up a dialogue box allowing the user to specify settings for the quote-of-the-day program; namely, the name of the quote database to select random quotes from, and the name of an author database to provide author information.


A Quoteriser reference

Quoteriser HTML

The HTML understood by the Quoteriser is a tiny subset of the full HTML standard; only elements thought to be useful in the typesetting of quotes have been implemented.

The Quoteriser understands the following HTML tags:

<b> ... </b> - the enclosed text is in boldface
<br> - force a line break here
<i> ... </i> - the enclosed text is in italics
<p> - paragraph break

Other tags will be ignored.

The Quoteriser implements all the ISO Latin-1 macros; unrecognised macros will be printed verbatim. Note that because the '&', '<' and '>' characters have special meaning in HTML, the &amp; (&), &lt; (<) and &gt; (>) macros must be used to represent such characters. The list of HTML macros may be obtained from the W3 Consortium, http://www.w3.org.

Because the Quoteriser blindly sends the ISO Latin-1 codes to the screen, some characters may display strangely if the current codepage/font does not correspond to ISO Latin-1. There is no support at all for other character sets, the author regrets to say (though one supposes fiddling with the codepages and fonts might produce results for some alphabets).

Regular expressions

(Note: if the reader has re-compiled the Quoteriser with a different regular expression library to GNU Rx, this section may not accurately describe the re-compiled Quoteriser - in this case, the author assumes the reader either knows what he or she is doing, or can find out).

The Quoteriser uses the GNU Rx library to implement regular expression matching. All regular expression matching is case insensitive and uses extended regular expression syntax. All matches are sub-string matches. The following is an incomplete description that is hopefully enough to get the reader started.

[ ] Matches any one of the characters inside the square brackets. Ranges may be used, e.g. [a-z] to match any alphabetic character.
[^ ] Matches any character not in the square brackets. Ranges may be used, e.g. [^a-z] to match any non-alphabetic character.
\ Take the following character literally, e.g. \\ match a backslash, \[ match a left square bracket.
. Matches any single character
? Match the preceding item zero or one times.
* Match the preceding item zero or more times.
+ Match the preceding item one or more times.
{n} Match preceding item n times.
{n,} Match preceding item n or more times.
{,m} Match preceding item at most m times.
{n,m} Match preceding item at least n times and at most m times.
| Match either the expression on the left or on the right.
( ) Used to alter order of precedence (similar to arithmetic).

Examples:

[KC]arl E.g. to find all authors named "Carl", regardless of whether they spell their names with a C or a K
happ(y|iness) E.g. to search for keyword "happy" or "happiness"
honou?r E.g. to search for both the US and UK spellings of "honour".
[aeiou]{3} E.g. to find all quotes with three or more vowels in succession.
[ ',.";:]word[ ',.";:] E.g. to match a whole word ("word", in this case) only

Unfortunately, the author is unable to direct the keen reader to a good, comprehensive regular expression reference; the best he can suggest is to get the manual page for the grep utility.


Related utilities

The Quoteriser, in addition to being able to manipulate quotes in databases, is shipped with a couple of utilities for amusing oneself and others with the wit and wisdom of a good quote database:
Introduction to the Quoteriser
Installation, credits, copyright, etc.
Database compiler (quoterc.exe)
A utility for compiling databases from text files, or de-compiling databases into text files.
Quote-of-the-day (qotd.exe)
A simple utility for choosing and displaying a random quote
Signature generator (sig.exe)
A utility for inserting random quotes into one's e-mail and Usenet signature (and anything else, for that matter).