NOTE: This file is accompanied by an icon that contains "folding" information used by TurboText. If you use TurboText as a text reader, you will see this file collapsed, and you can expand the sections you are interested in. Asha's Silly Tagline Generator 1.8 Documentation ================================================ About ASTG ~~~~~~~~~~ ASTG is a tagline generator. For those people not familiar with such things, a tagline generator's function is to create random quotes that appear at the end of a message, maybe humorous, maybe not. Taglines are more or less bumper stickers for electronic mail. ASTG 1.0 (and later revisions) was created specifically for Asha Develder as a birthday present. While I could spend a few pages describing Asha and why she has inspired me to write a program just for her, I think she speaks best for herself, so catch her in the Fidonet echos, AMIGA (sometimes called Amiga General) and the echo she moderates, AMIGAGAMES. To know her is to love her. :-) Anyway, Happy Birthday, Asha!!! ASTG was designed to work with most popular offline readers and point programs, such as Spot, April, or Foozle. It may well work with other programs but I have not had the opportunity to try them with it. If you get ASTG to work with one of these other programs, please contact me and let me know how you did it, and I'll include that information in any future releases (if any) of the program's docs. History of ASTG =============== ASTG began its life as an Arexx script that was released as ASTG07.LHA (sysops, if you have this one, you may delete it). While it worked fine for me, it was a bit slow on the larger tagline files. Asha especially disliked having to wait for Arexx to makes its way through the large collection of taglines she had, hence my motivation to speed things up for her. ASTG the Rexx script was developed partly from QUOTEMONGER, another Arexx tagline generator. Well, two or three lines of the original code remained after I hacked it :-) ASTG 0.7 seems to have developed a reputation for being psychic. I make NO claims of ownership for this -- the source code for 0.7 is available and I can find nothing in it representing an AI function, and no one has pointed that block of code out to me, either. It SEEMS that that certain *something* has carried over to the C version, too. One thing we have noticed is that it takes a while for ASTG to get "used" to you before things start happening. FEATURES ======== ASTG offers several features that might not be individually unique, but as a whole it offers a comprehensive package: o Marks taglines as they are used. This ensures that you cycle through ALL your taglines before it starts over, which means basically that you get to see them all over the course of time. Typical C and Arexx randomizing functions -- aren't, so they don't normally provide much variety in taglines. o Allows taglines of over one line in length. The taglines have to be formatted in a specific way for this to work (read on). o Intuition based Prefs editor. Easy to set up! o Works with most text editors o Works with any message system that calls an external editor and stores the message in an external text file. o FAST! Written in C for speed! Requirements ============ ASTG 1.7 requires AmigaDOS 2.04 or later. ReqTools.library version 38 or later is required for the prefs program. It also requires a message writing system of some sort and a file of taglines (sample tagline file included, but PLEASE start your own personalized collection! Otherwise, the magic will not work!). Installation ============ If you have been using ASTG 1.0 through 1.4, you will have to delete ENV:ASTG.PREFS and re-run ASTG Prefs! Sorry about that, but there was a problem in the way I was reading the prefs file, and the easiest way to correct it was to completely change the way I did things. ASTG Archive ~~~~~~~~~~~~ From the ASTG archive, copy the following files: ASTG Prefs Copy this file and its icon to your ASTG Prefs.info SYS:Prefs directory. Actually, it can go anywhere, but the PREFS dir is the logical place to put it. ASTG Copy this program to where you plan to use it -- C: is fine, as is where you keep your mail reader. As long as you can find it later... Taglines This is a sample tagline file. Put it wherever you like, but be sure to remember where it went, as you'll probably wish to edit it later on. You can also rename it to anything you wish. ASTG.DOC Put this file anywhere you wish :-) Your Mail Program ~~~~~~~~~~~~~~~~~ SPOT ~~~~ In the SETTINGS menu, select GENERAL. On the setup window you get, set EDITOR to: /ASTG %s where is the drive and path that ASTG is stored in. APRIL ~~~~~ In the CONFIGS menu, select GENERAL1. On the setup window you get, set EDITOR to: /ASTG where is the drive and path that ASTG is stored in. FOOZLE ~~~~~~ Run FZI. Click on GENERAL1. Cycle through until you find the "Editor" window. Set it to /ASTG % where is the drive and path that ASTG is stored in. Configuring ASTG Prefs ====================== Double click on the ASTG Prefs icon. A window will pop up with four parameters that you can set: Tag File This is the path and filename of the tagline file. Click on the button next to it to get a file requester. Editor 1 This is the path and filename of the editor you use to write messages, and the first part of any parameters you need to pass it, up to but not including the filename that you will be editing. Click on the button next to it to get a file requester. For example, if you're using TurboText, you might set it to TurboText:TTX. The next thing you would NORMALLY put in that line would be the file name itself. ASTG gets that from the mail program itself, so don't put it in here. Editor 2 Some editors require parameters AFTER the file name. This is where you would put it. If there is nothing you need to put there, make it blank. For example, Turbotext will let the parent process go immediately after it is called, normally, but you can make it wait until you finish editing the message with the WAIT parameter. Another example would be the CygnusEd -keepio parameter. Brag Line ASTG normally lets the world know that you're using it. If this checkbox is turned off, it won't. It won't bruise my ego if you want to be incognito :-) If I was worried about it, I wouldn't have made it an OPTION. :-) Also, for the bandwidth-concious, you'll probably want to turn this off in order to save precious bytes in your outgoing mail packets (no comment :-) Creating and editing the tagline file ===================================== NOTE: if you have been using ASTG 0.7, you DO NOT need to change your tagline file except to delete the "###" at the end. IMPORTANT >>>>>>>>> The tagline file can contain as many taglines as you wish. The ONLY constraint is how much memory you have -- be warned that ASTG loads the ENTIRE tagline into memory, so if you have a 500K tagline file wow!) you need to have at least 500K of memory free to use it. END IMPORTANT >>>>> Each line in the tagline file represents one single tagline. Each tagline, as I mentioned, can be a multi-line tagline. To do this, seperate each 'line' in the tagline with the two characters, "\n". You will notice several taglines in the sample file are formatted like this. For example: ... Tell a man that there are 300 billion stars in the galaxy and\n he'll believe you. Tell him a bench has wet paint and he'll have\n to touch it to be sure. -- M.B. (if your text reader doesn't let you see it properly, the above should have been seen all on one line). translates to: ... Tell a man that there are 300 billion stars in the galaxy and he'll believe you. Tell him a bench has wet paint and he'll have to touch it to be sure. -- M.B. NOTE: EXCESSIVE USE OF THIS FUNCTION MAY RESULT IN YOUR BEING FLAMED BY OTHER PEOPLE ON THE NET FOR WASTING BANDWIDTH. IF THIS HAPPENS, IT'S YOUR FAULT. I SUPPLY THE PROGRAM, WHAT YOU DO WITH IT ISN'T MY FAULT. General information: (for the technically minded) ==================== So far, I've presented several specific examples. Now, I'll go more into depth with this so that people with different programs can possibly make it work. If you do, please let me know and I'll include your information in any future releases. ASTG Command Line ~~~~~~~~~~~~~~~~~ Usage: ASTG ASTG takes most of its parameters from ENV:ASTG.PREFS. One filename, the name of the message file itself, must be supplied by the mail program. This file must be a plain text file. ASTG Operation ~~~~~~~~~~~~~~ ASTG does several things as it goes along. First, it opens the tagline file that it is directed to in the prefs file, counts up the number of unused taglines, and randomly selects one to use. It marks that tagline with a "*" as the first character, then re-writes to the tagline file with the changed information. It then parses and appends that tagline to the end of the message. If it is directed to, it appends a bragline. Finally, it calls the prefs-selected text editor, using the name of the message file supplied on the command line by the calling message reader. In your mail program, there is probably a place that you tell it what editor to use. If there is not, you probably cannot use ASTG with it. In that program, you substitute ASTG for the editor. Be sure to follow that program's conventions for supplying the message file name. If there are less than 3 free taglines, ASTG will remove the markers before writing the taglines back to the file. This takes a bit of time, but it only happens occasionally. ASTG.Prefs ~~~~~~~~~~ ASTG uses the style guide suggested method of storing its configuration data in ENV: and ENVARC: as ASTG.PREFS. You should not change this manually. TECHNICAL SUPPORT, AND REGISTRATION =================================== I'll get the easy part out of the way, first. This program is freeware. Use it in good health. Fercrissakes, this is just a stupid tagline generator! Take that registration money and spend it on something worthwhile, like your sweetheart! OK, the odds of this program being bug-free are pretty slim. As such, I very much want to hear of any bugs you come across. If you do, please let me know about the version of the OS you use, the CPU and memory in your computer, and whether you're using a hard drive for this. Also, open a shell, and CD to the directory that ASTG lives in. Type "VERSION ASTG FULL" and record the information you get and pass that along. Be prepared to somehow get your tagline file to me, too, as it may be something in your tagline file that's doing it (but don't send it unless I ask for it!). Finally, ASTG will report an error code when it fails. Please let me know what code that is, as it will point me to the exact location in the code of the failure. If you're up to it, try to reproduce the failure and see if it fails in the same place. You can contact me on FidoNet as: Jeff Grimmett at 1:202/720 (not crashable) ... or on Internet as: jgrimm@sdd.hp.com ... or on GENie as: J.Grimmett2 You can contact me via SnailMail as: Jeff Grimmett 3152 Kemper St #5 San Diego, CA 92110 Future Plans ============ The few items I have left: o Implement keyboard support for the prefs program (not that there's much to implement...) o Remove final dependencies on ReqTools.library in the prefs program. Not much left to do! ACKS! ===== I'd like to thank my beta testers, Holly Sullivan, Joyce Divina, and Gary Peake. Oh, and Asha Develder, as well :-) ASTG Prefs was built using GadToolsBox, sadly no longer supported by the author. :-( ASTG and ASTG Prefs were built using SAS/C 6.3, a wonderful development system on any platform! Thanks to Oxxi for TurboText, which was used for both the code editing and for document generation :-) Thanks to the various offline reader and point software authors for making thier products useable even unregistered. If it weren't for that, if would be darned difficult to test ASTG under varying conditions. History File ============ Version 1.8 (15 April 1995) (Happy Easter, Asha!) o Removed the backup code in ASTG. It was creating more problems than it was worth. Users would run ASTG after ASTG bombed out, and the empty file would be backed up, destroying the good file. Since no one (including myself) was benefiting from the backup option, I took it out to save space. o ASTG got rewritten from the ground up. This was due to the fact that although ASTG was running flawelessly on countless systems, it was still crashing on Asha's machine. This is not good, since it is Asha's program! ALL SAS/C str* string functions were removed or my own code was substituted. ASTG is slightly slower, but now seems to be running stable on Asha's machine. As a side effect, the code is around 2K smaller. Version 1.7 ( 2 April 1995) *BETA* ASTG would crash horribly if the tagline file was 0 bytes long. Code has been added to exit gracefully if that happens. If you see this error, it is probably because ASTG bombed out in an earlier run. Implemented the PARANOID MODE of programming ASTG. This means that ASTG error checks practically everything it does and fails if anything is remiss, but it prints an error code when it does so. This should facilitate troubleshooting of bugs that I cannot reproduce here. As part of the PARANOID philosophy, I have implemented a backup mode in ASTG. Before it touches your tagline file, it copies the file to the same directory with the ".bk" suffix. Removed, for philosophical reasons, all dependencies in ASTG itself on ReqTools. The dependencies still exist in ASTG Prefs. One thing at a time, ambassador, one thing at a time. Version 1.6 (19 March 1995) Rewrote the Prefs File editor and the prefs file portion of ASTG. You MUST delete the old ENV:ASTG.Prefs and rerun the prefs program. Sorry! Version 1.5 A radical departure from 1.3 and 1.4, it was actually found to be SLOWER than the older ones. As such, it was scrapped. Version 1.4 (13 March 1995) Changed "cleanup" function to utilize a faster method of writing out the tagline file when it's cleaning out the "*"'s. I don't think there's anything else that can be done to increase the speed of ASTG now. Removed all references to ANY "printf" related functions (fprintf, sprintf), which reduced the code size by 4K or thereabouts. Yet another speed increase -- this time, on the file write-back. Changed it from line I/O to buffered I/O. Unfortunately, it does not appear that this is possible for the "clean-up" operation. Found and stomped one more bug, this one introduced in 1.3. The memory buffer used to store the tagline selected was exactly one byte too large. Thus, a garbage character was being tacked on to the end of each tagline in the tagline file. Version 1.3 (14 Feb 1995) (Happy Valentine's day, Asha!) Nailed it! Well, I think so... For the technically oriented, strtok() is a little brain dead and tends to overflow if you tell it to parse a string for "\n" and it doesn't find it. I fixed this by calloc()-ing a chunk of memory one byte larger than the tagline file, and strset()-ing it to "\n", thus guaranteeing that there is a CR at the end of the last line parsed. Side effect: the first time you use it, ASTG causes the tagline file to grow by one byte. At this time, I am not certain if this will cause any ill effects, but time will tell. There is no indication as to the cause of the failure of ASTG to parse the bragline setting. I am assuming at this time that it was a side-effect of the memory grunging happening due to the tagline corruption problem. Only time will tell. Version 1.2 ( 9 Feb 1995) Internal release. There are two known bugs in ASTG. One causes it to not properly parse the bragline on/off switch. The other is more major, and causes it to occasionally corrupt the tagline file. In many cases, ASTG hangs up because of it. Major changes made to speed the execution of the program. This has caused the bug that corrupts the tagline file to stand up and be really noticable, which makes it easier to troubleshoot. It goes without saying that ASTG will not be released in this condition. One side effect of the change is that the "###" is no longer needed at the end of the tagline file. In fact, if it is left in, it will eventually be seen as a tagline! :-) Another side effect is that the number of taglines you have is now limited only by how much memory you have. Version 1.1 ( 3 Jan 1995) Several changes made to increase the execution speed. I am still not altogether satisfied with the speed, but it now takes 1/5 the time it took version 1.0 to execute on the same sized tagline file, so that's some progress! :-) All speed changes were accomplished by inlining several functions within the program. Added an extra before the tagline, at Asha's request. Hey, it's HER birthday present! :-) Trimmed out a lot of excessive junk (debugging code, catch code, stdio code, etc) to reduce the size of the program by 25%. Version 1.0 ( 9 Dec 1994) (Happy Birthday, Asha!) First C release, beta only. No smoke! :-)