==================================================================
Snippet-title:		fortune v1.2
Creator:		Graham Keellings
E-mail:			pivot@keellings.com
Website:		http://www.keellings.com/software/pivot.php
Creation date:		14 June 2005, Kouvola, Finland
==================================================================

Content of zipped file:
-----------------------
snippet_fortune.php
snippet_fortune_create_file.php
readme_fortune.txt (this file)


Usage:
------
1) unpack this package in your extensions/snippets/ folder.
2) place a [[fortune]] tag, with the appropriate parameters, in any of your template files, wherever you want the randomly generated "fortune cookie" to appear
3) rebuild the FrontPage(s).
   
Description:
------------
* A Pivotization of the classic Un*x fortune cookie program.
*
* Just a snippet encapsulation of some fully functioning code PHP fortune
* cookie code which I shamelessly ripped off (with permission) from
* Henrik Aasted Sorensen (haas@itu.dk).
*
* Takes its input from standard format fortune files, so that it can be
* easilly extended. There is a large collection of ready made fortune files
* at FreshMeat http://freshmeat.net/browse/895/?topic_id=895  and I have
* incldued some of my favourties with this snippet. Look, too, at
* http://sourceforge.net/projects/fortunecookies
*
* http://www.splitbrain.org/projects/fortunes also has some from
* the Discworld Novels, Forrest Gump, The Hitchhikers Guide to the Galaxy, 
* The Simpsons, Star Wars and The X-Files.
*
* Included in the distribution you will find instructions on how to create
*  your own data files.
*
* Visit http://www.keellings.com/blog/_demos/fortune.php to see it
* in action
*
* To generate your own files.
*    (I recommend keeping them in a "fortune" sub-directory of your snippets
*    directory, but that is not mandatory.)
* 1) create a data file; plain text, fortunes can be of any length, separated
*    by a line containing only a percentage symbol %
* 2) look in directory fortunes/make your own for the appropriate
*    sub-directory for your operating system and follow the instrcutions
*    in the ReadMe file there
*


Parameters:
-----------
* @param   string   fortuneSource - specifies the name of the file or directory
*                                 from which the fortune will be generated (if
*                                 a directory is given, a random file will be
*                                 selected).
*                                 IMPORTANT: if you specify only a directory
*                                 then it must end with a trailing slash '/'.
*                                 IMPORTANT: the directory or file is relative
*                                 to your <pivot dir>.
*                                 Examples:
*                                   [[fortune:extensions/snippets/fortunes/:1]]
*                                   [[fortune:extensions/snippets/fortunes/homer.dat:1]]

* @param  int       errorLevel  - specifies what should be output if an error
*                                 occurs: 
*                                    0 (default) output nothing
*                                    1 Ouputs the text of parameter errorMsg as
*                                       an HTML comment
*                                    2 Ouputs the text of parameter errorMsg
* @param   string   errorMsg    - see parameter errorLevel. If this is blank
*                                 and errorLevel = 1 or 2 then the snippet will
*                                 supply its own text.
*
* @return  the randomly generated 'fortune'.



* History:
*
* v 1.2 2005/02/23  Sentosa Island, Singapore
*   - now it actually works on-line for the first time (path problems solved)
*
* v 1.1 2005/11/08  Sentosa Island, Singapore
*   - removed the attempt to generate index files by PHP.
*   - packaged the strfile program to generate index files
*   - added a few extra data files.
*
* * v 1.0 2005/06/14  K