********** ** SIMPLE EXPLANATION OF THE PARSER parser.pl (or whatever the filename is) is a perl script that consumes an XML document with a specific format and produces two HTML files: one which is a pure-HTML representation of the content of the XML file, and another which serves as a container for the Flash program main.swf, which *also* parses an XML file (specifically, one in the same directory named "content.xml"). The generated HTML files contain javascript which automatically detects whether the browser can play the flash, and may forward the browser to its counterpart depending on the setup. This forwarding behavior can be turned off by appending ?noredir to the end of the html file's URL. The HTML files must be in the same directory for the forwarding to succeed. To use the parser, you must have the Expat C library from http://sourceforge.net/projects/expat/ and the Perl XML::Parser module from http://search.cpan.org/~msergeant/XML-Parser-2.34/ correctly installed on your system. You can invoke the program with the command perl or, if the program file is executable, ./ Invoking the program in this manner will cause it to give the output files the default filenames "index.html" for the pure HTML, and "index-flash.html" for the flash-playing HTML. You can specify the outgoing filenames for the HTML and Flash files with the 'flash' and 'html' attributes of the page node within the XML. If you wish to reference the files directly from a url attribute of any node, it is best to do so with aliases like this: All parsers scan url attributes (but NOT src or icon attributes, which also must have url values) for the special tags %html, %flash, %flash-noredir, and %html-noredir. You can use this behavior to ensure that modifying the output file names does not necessitate a revision of all the explicit links throughout the file. If the program is about to produce a file under a certain name, and a file of that name already exists, it renames the old file to make room for the new one. Keep in mind that if there are any HTML links to the old file, those links now point to the *new* file. ********** ** VERBOSITY Depending on your setup, the Perl parser may take a while to process. If you want updates on how far along it is, you can tell it to report its progress with the following tags, which you can include on the command line anywhere with the other arguments (as long as you don't displace the XML file as the last argument). -s Silent mode - the default. Perl will not output anything unless it has to abort processing because of a critical error in the format of the file. -w Warning mode. Slightly more verbose than silent mode. The parser will report when it moves from processing stage to processing stage and when it encounters unimportant errors such as unrecognized nodes. -v Verbose mode. MUCH more verbose than warning mode - every time the parser encounters a new element in the XML tree it will report its current location and the current construction of the XML tree in memory. Enabling this option will cause the parser to process up to 50 times slower, as it spends all its time writing to the terminal! -d Debug mode. Just like verbose mode except it also prints miscellaneous debugging strings. ********** ** XML FORMAT The XML file the Flash and Perl parsers consume is expected to have a certain format IN ADDITION to the constraints already imposed by the XML specification. Deviation from this format may cause the parsers to crash, and probably not very nicely. Since the two parsers are specialized applications designed to format the XML for presentation in their own medium, one parser will respect different parts of an XML document than another (for example, the flash parser doesn't respect grandchildren of the page node that aren't children of a panel node). In general, effectively authoring pages with these parsers requires an intimate familiarity with the unique ways they interpret the XML, but can usually be used to your advantage. HTML nodes, for example, tend to look very nice after going through the Perl parser but look *horrible* after going through the Flash parser. The following table doesn't go into too much detail about the function or purpose of the various nodes; if you need that, see the full README file. Instead, it is most useful merely as a summary or quick reference after the concepts in the full README are understood. NODE TYPE CAN HAVE CHILDREN CAN BE A CHILD CAN BE OWNED ATTRIBUTE (optional/required) - meaning ------------------------------------------------------ page yes no no title (optional) - the title of both HTML pages and the banner of the flash. html (optional) - the file name of the pure HTML file. flash (optional) - the file name of the flash playing HTML file. bgcolor (optional) - the background color of the flash and HTML files. text (optional) - the color of all unlinked text on the page. link (optional) - the color of all unvisited, inactive links. vlink (optional) - the color of all visited links. alink (optional) - the color that links flash when clicked. hlink (optional) - the color that links become when hovered over. meta no only of the page node yes name (required) - the 'name' field of the meta tag content (required) - the 'content' field of the meta tag panel yes yes yes name (required) - the text that serves as the panel header line yes yes yes text (required) - the text of the line url (optional) - the location to link to when the text is clicked icon (optional) - the URL of a picture to include on the right img yes yes yes src (required) - the URL of the image source caption (optional) - text to include beneath the image url (optional) - the location to link to when the image is clicked group yes yes yes anything at all (optional) - propagates all of its attributes and their values down through all of its children that don't define them already. (Including text and CDATA nodes.) no yes not directly, because can't specify attributes regular text no yes not directly, because can't specify attributes