READ ME:: QIParser.tcl (in which the uses and possible joys of such a script are described at great, and mostly accurate, length, and which should be the hitherto most enjoyable README thee hast ever read) ============================== Short Summary: ------------------------------ - The default version of this script (run as ./QIParser.tcl from the commandline) will 1) fetch an XML file from http://www.sanemagazine.com/publish/content/1.0/horosocpes.xml, 2) parse that file and dump the data into a few arrays for use by 3) an HTML formatter, which writes the data into the default layout specified by a template file and write it to a file in the output directory as 'horoscopes.inc'. There are no and and tags in the resulting HTML, it's only a simple html table so you can include it in any page on your site if you happen to have server side includes turned on. We recommend you don't run this script as root and we also recommend you read James Sallis and Michael Marshall Smith. We recommend you don't run this script as James Sallis or Michael Marshall Smith unless you happen to be either of those two. If you do happen to be one of those two, "Hey." You may also want to read the license for this fine piece of software, available at http://supertart.com/software/license.html To Install: ------------------------------ - From a shell prompt on the machine you're going to run this script from type 'which tclsh' - If tclsh is not at /usr/local/bin/tclsh on your machine (Mac OS X users, for example, will see that tclsh is at /usr/bin/tclsh), change the first line of the QIParser.tcl file to point to the location of your tclsh with your favourite text editor (make sure you're saving the file with Unix line breaks if you do make any changes). - If QIParser.tcl isn't executable, type chmod o+x QIParser.tcl as the user that will be executing this script. If you don't know whether it's executable or not, just go on and type chmod o+x QIParser.tcl anyway. - Make sure, in the default mode, you are able to write to the directory to which your html file is going to be written. If you can't, for some reason, change directory permissions on that directory, make sure there is a file named 'horoscopes.inc' in that directory that you have write permission on. - We also recommend you create an entry in cron for this script and have it run on Monday midday (Monday evening if you're in Europe, the UK, or Eire). Running it more frequently won't serve any purpose, as this script fetches data which is only updated every week on early Monday morning (GMT). System Requirements: ------------------------------ - Tcl 8.0 or higher (Or whichever version began supporting namespaces, which I'm almost certain is 8.0, without looking at the docs) (Unix version only (This means it will not run, as is, on a Windows machine with Tcl installed. Unless it does. I don't know. It will run, I suppose, on a Windows machine with Yellowbox installed, but this statement is made without actually having tried said operation. Just go and get Mac OS X and stop playing with that other rubbish.)) - That previous comment (mostly the namespaces bit) would be in an ideal world. As it is, if you have the app packaged as QIParser.app you can run the scripts included under Tcl 7.5, if you like. It doesn't use namespaces, and runs quite happily back to tclsh7.5. The Longer Version: ------------------------------ This script can actually do quite a lot, if you decide to do more than just the default. It is a mostly fully functional Sane Magazine horoscopes XML file parser *and* RSS parser. To find out what the default does, type './QIParser.tcl -NORUN' This will output the verbose intro, and explain the different flags an their uses. The following, as a matter of fact: Options are, for those interested: -RSS This option specifies that it's an RSS file you're collecting. -t templateFile The reference to templateFile needs the file to reside in the templates directory of this app. You can add your own template files, to install and use simply copy your template into the templates directory under QIParser.app and call the script with -t 'yourTemplateFileName' -h sourceHost NB. This is simply the host name the file you wish to fetch resides on, do not include the protocol (http://) or anything else. eg. www.sanemagazine.com -f sourceFile NB. This is the full path to the file you wish to fetch, from the root of the webserver (this fetch is only happening over http at the moment). eg. /publish/content/1.0/horoscopes.xml -x exportFile A file relative to the default export directory (./output/). -v The default settings are: -t ./templates/QIP_Horoscopes.template -h www.sanemagazine.com -f /publish/content/1.0/horoscopes.xml -x ./output/horoscopes.inc The default RSS ivars are: -t QIP_RSS.template -h www.sanemagazine.com -f /rdf/sanemagazine.rdf -x './output/rss.inc' To parse RSS files with this script simply run the script with the -RSS flag. (./QIParser.tcl -RSS). You can configure most of the stuff in this app yourself, simply by playing with the QIPGlobals.tcl file, which contains all the defaults. The defaults you're most likely going to want to change will be the QIPGlobalTemplateDirectory, QIPGlobalOutputDirectory, QIPGlobalSource, QIPGlobalSourceHost, QIPGlobalSourceFile, QIPGlobalHTMLTemplate, QIPGlobalOutputFile, and QIPGlobalDefaultNumItems. Possibly in a later release the ones we recommend you don't change will be in a separate file, but we're taking the approach at the moment of giving you loads and loads of rope. What you do with it is your choice. If you use it for soap-on-a-rope let us know. We *do* support changing QIP_MODE to "RSS" in the QIPGlobals.tcl file, as you can simply specify -Horoscopes at the command line to parse a horoscopes file, we just haven't mentioned the -Horoscopes flag anywhere in the documentation. Erm. Except here. Of course. But then you knew that. Closing Notes: ------------------------------ - If you'd like updates on q.i. productions software, including new releases of this script, please mail software@supertart.com with the Subject: Software Updates.