@database Cookie Monster V1.0 documentation

@node main "Cookie Monster V1.0 documentation"
        Welcome to Cookie Monster V1.0

   @{" Contents              " link "Contents"} -what's inside
   @{" What does it do ?     " link "What does it do ?"} -in case you are still wondering
   @{" Using Cookie Monster  " link "Using Cookie Monster"} -working with it
   @{" If all else fails     " link "Errors"} -some terse, annoying messages
   @{" Distribution          " link "Distribution"} -spreading it about
   @{" Greets                " link "Greets"} -slimmed-down version
   @{" And finally...        " link "And finally..."} -How to contact me

Note: If you would like to print this entire document out, I can recommend
a program called AG2Txt by Jason R. Hulance which does a great job of
converting AmigaGuide documents to text files. It is found in the
text/hyper (!?) directory of Aminet.

                  Written by Andrew Elia (August 1996)

@endnode

@node Contents "Contents"

   This archive should contain the following files:

       CookieMonster               - The main program
       CookieMonster.SunOS         - A version compiled for Sun SPARCs
       CookieMonster.Guide         - well what do you think this is ?
       CookieMonster.Guide.info    - with an icon

   If for any reason it doesn't, this program can be downloaded from the
Aminet (or obtained from an Aminet CD) in the util/misc directory as
CookieMonster.lha.

@endnode

@node "What does it do ?" "Cookieeees!"

    In short, Cookie Monster is yet another fortune cookie program. I
don't claim that it's better than any others (it's probably worse!), but
it is an alternative (which is the real beauty of Aminet, really).

    The program was written to be portable across many platforms, but
I'm not supplying the source code because I don't want anyone to compile
version for the PC. It's that simple.

    Aside from the more obvious use of sticking it in your
StartUp-Sequence or Shell-StartUp or whatever, this program can also
be used for CGI scripts (hence my need to make it portable, as my web
page runs on the University's Sun SPARCs). I intended it for a sort of
"message of the day" to stick on my rather crap page. It turns out that
it can also be used as a random picture generator!

    Further uses include execution of random AmigaDOS or Arexx scripts.
Random backdrops or indeed any other Workbench preferences file are also
possible.

@endnode

@node "Using Cookie Monster" "Using Cookie Monster"

    Cookie Monster is run from the Shell by simply typing:

    CookieMonster xxxx

Where xxxx is the name and path of a text file containing cookies. I
haven't actually supplied you with an example cookies file, mainly
because I haven't been raiding many dictionaries of quotes recently.
Actually, there is a book caled "The Guinness Dictionary of yet more
Poisonous Quotes" compiled by Colin Jarman, and published by Guinness
Publishing. The ISBN is 0-85112-729-0. It contains gems such as "His
computers take twice the gestation period of an elephant to load up...
He has the looks and charm of a warthog long since ostracised by polite
warthog society on the grounds of looks and lack of charm." That was
said about Alan Sugar. Unfortunately, it seems that Bill Gates paid off
the bloke who compiled this book before he got a chance to channel the
truckload of anti-Gates quotes into a complete book. Shame. You could of
course visit an anti-Micro$oft site and create a list of famous Bill
quotes like "640K should be enough for anyone". Or perhaps the Intel
spokesperson who with crossed fingers said "Of course we didn't know
about the Pentium bug"!

    The text file itself is easily created in a text editor of some
description. Each cookie is separated by pressing return. Any blank
lines within the file will be ignored and will never be printed. Make
sure that if you are using a text editor which can change the return
code type of a text file is set to "Line Feed" or "LF". The program uses
these codes to know when one cookie ends and another one starts. If you
find that the program outputs one long cookie containing all your
quotes, then you're using the wrong return code. To fix this, grab
RetConvert V2.0 off Aminet (text/misc/RetConvert.lha) and use:

    RetConvert xxxx LF

That will fix the problem. Coincidentally enough, I wrote RetConvert
too, by the way! Please note that in order to make Cookie Monster
produce a result as quickly as possible, it is necessary to have
sufficient memory to load the whole file. Unlike some other cookie
programs, Cookie Monster will minimise disc access by reading the whole
file into memory rather than in little bits. There is no limit to the
length of the cookies themselves or even the number of cookies in a
file. It's just memory that limits you, nothing more.

    Here is a collection of some of the cookies that have ended up on my
web page (although many of them are taken from other people's sig files
and so on, but some are my own). If you wish, you can always copy these
out of this document and stick them in your own file, but for goodness
sake use some of your own creativity! Here goes:

--- Cut here ---

Escom is dead. The Amiga lives.
Intel. Yesterday's technology today.
Intel. Making old technology look like new.
Intel is only a fraction of "Intelligence".
Microsoft. Where do you want to crash today ?
VISCorp. Our last best hope for the eradication of 70s crap.
The streets will flow with the blood of segmented architectures.
Life begins at '030. Fun begins at '040. Impotence beings at '86.

--- Cut here ---

    There are of course other uses for this program. You can, for
example, have your Amiga display a random picture, or play a random
sample as it starts up by creating a text file with the paths of the
pictures or samples you want to play. It also works for AmigaDOS
scripts, Arexx scripts, music modules, Workbench preferences (eg.
backdrop pictures) and virtually anything else you can think of.

    Note that if you are familiar with ANSI codes, you can also stick
these into your Cookies (provided they are used for text output, and not
for some kind of file path, like pictures). You can find a list of
useful ANSI codes in the "Amiga ROM Kernel Reference Manual: Devices"
(I've got the third edition -it cost me about 20 quid). For the time
being experiment with creating a file by using the following:

    echo "*E[37mHello"

That ought to print out the word "Hello" in a different colour (and also
change your prompt colour). You can swap the "37" part of it for "0" to
put everything back to normal. Try sticking other values in that place,
but be warned that it is possible to make your text disappear
(although if you can type without looking at the screen, you can put
it back to normal by using "0" in place of "37"). To stick these on to
the end of your cookies file (unless you have a really smart text editor
that can change text colour for you), try this:

    echo >>MyCookies.Txt "*E[37mHello"

    Naturally, as the program will only output the text from the file
with nothing else, you are free to output your own text alongside. For
example, if you are running Workbench 2.0 and above you can do this:

    echo "Message of the day: `CookieMonster MyCookies.Txt`"

That ought to print the following:

    Message of the day: xxxx

...where xxxx is a message selected from your cookies file (in this
case, MyCookies.Txt). Make sure that your backtick (`) is facing the
right way -on my keyboard (British), press alt and tap the tilde (~)
key just underneath the Escape key.

    To display a random picture, you'd use the following command:

    VT `CookieMonster MyCookies.Txt`

...where "VT" is the name of the picture viewer that you are using. In
this case, VT is "ViewTek" (the picture viewer written by the same
people that wrote ImageFX, and now Aladdin -Nova Design). Your cookies
file will contain entries in the following format:

    Andrew:Pix/IntelOutside.IFF
    Andrew:Pix/EscomSux.GIF
    Andrew:Pix/VISCorpRulez.JPEG

Basically, this is a complete path to each picture (not that those
particular pictures exist on my hard drive, well not the last two
anyway). A cookies file can be created quite easily if you use the
following shell command:

    List Andrew:Pix LFORMAT "%s%s" >PiccyCookies.Txt

Obviously, this can then be loaded into a text editor such as the rather
dire Ed, or something like GoldEd, Blacks Editor, or even Devpac.

    The same technique can also be applied to samples (or if you're
particularly flash, Workbench preferences files). The technique is
exactly the same, except that you'd use "Play" or something instead of
"VT". A random AmigaDOS script can be called by trading "VT" for
"Execute". In this case, the cookies file would contain the paths of
AmigaDOS scripts.
@endnode

@node "Errors" "If all else fails"

    There isn't really much that can go wrong with a program as small as
this one. Nevertheless, it's always useful to know what can go wrong and
why.

    "Unable to open input file" -This happens either when you call
Cookie Monster without supplying a filename (which I suppose isn't
really a very user-friendly way of doing it) or by giving it a file that
doesn't exist.

    "Unable to analyse file length" -It is more likely that the above
error will occur than this one. It could only really occur with some
form of bizarre disc corruption, as far as I know. Let me know if you
actually GET this error, and how.

    "Insufficient memory to analyse file" -In essence, you don't have
enough memory to load the cookies file. It's time to either trim down
that StartUp-Sequence, or get a virtual memory program. You could even
consider the unthinkable and fork out for some physical memory. Come on,
SIMMS are dirt cheap nowadays! To be honest, you'd have to be using a
hell of a lot of cookies even on a modest configuration to get this sort
of error!

    "Unable to read whole file" -The program was only able to load part
of the cookies file. This would be down to having a section of the file
sitting on a corrupt part of a disc.

    "Insufficient memory for Cookies" -A similar error to the other
memory-related one. Basically, you have enough memory to load the
cookies file, but not enough memory to set the cookies themselves up.
This error is far less likely to occur than the other one, as setting up
the cookies takes minimal memory.

    "No Cookies found" -Simply put, your cookies file is empty. This
would also occur if the file is just full of blank lines.

@endnode

@node Distribution "Distribution"

    Cookie Monster V1.0 is FREEWARE. You can distribute it where you
like, provided the archive is complete and unmodified. There are only
two executables supplied: one for the Amiga, and another for the Sun
SPARC. If there is a requirement for other versions such as SGI, DEC
etc, and I can get hold of a machine to compile it on, I will include it
in the next archive that I put onto the Aminet. Please bear in mind that
however much anyone begs, however much they grovel, I will NOT compile a
version for the PC. Never.

@endnode

@node "Greets" Greets

A slightly briefer greets list than before...

    Ash & Richard (former fellow Escom UK workers)
    John Smith (PIOS Computer UK)
    Christoph Gülicher (Amiga Technologies GmbH)
    Jason Compton (Amiga Report/VISCorp representative)

    Everyone at the Amiga Society, Queen Mary and Westfield College,
University of London

    Everyone at from AmiLon, the coolest user group in London!

                                  ---

V-Signs go to...

    All upper management staff from Escom AG, Escom NL, Escom UK
    Stuart Campbell (ex-editor of Amiga Power)
    Anyone who thinks that Win 95 multitasks better than Workbench 1.2
    Anyone that posts anti-Amiga messages on Amiga Usenet newsgroups
    Employees of Microsoft and Intel
    Tower Records (for the software stand they placed alongside the Mega
CD and 3DO).

@endnode

@node "And finally..." "And finally..."

    I would welcome any (sensible) suggestions for improving this
program, if any exist that is!

    If you feel the urge to contact me, my E-Mail address is:
odin@dcs.qmw.ac.uk, but if you have any difficulty sending any messages
to that address, try: AC4040@qmw.ac.uk. For any non-netsurfers, I can be
snail-mailed at 178 Carterhatch Road, Enfield, Middlesex, EN3 5LY,
England.

    See you in the next version!

@endnode