Ag2txt - Turns AmigaGuide files into flat, readable and printable text. ====== Function ======== Ag2txt is a fictious program. It becomes reality in the form of "ag2txt13" for KickStart 1.3 (maybe older versions, too) and "ag2txt20" for KickStart 2.0 (and above). The purpose of Ag2txt is to convert AmigaGuide hypertext files into flat, readable and printable text. It does this by recognising nodes and links and highlighting these. All other hypertext information is discarded. This means that if the hypertext document comprises several files you will need to convert all of them. The converted file uses Ansi escape sequences to do the highlighting, so any decent Amiga text reader should display them properly. Also, any decent printer driver will convert these sequences into the appropriate printer control codes, so you can send the file directly to PRT: and have it printed. At first sight this may seem like a completely useless program. I agree. AmigaGuide and MultiView are much better and hypertext is really good fun. But there are times when you want to just read the text, and printing hypertext properly would require a very strange printer and some weird paper! In fact, I have derived a C version of this program so that I can run it on a Unix machine (in an Xterm). A blatant plug now follows: Ag2txt was written in Amiga E (v2.1b), which is a Public Domain Amiga-specific programming language based heavily on C and with many other useful features 'borrowed' from other language. Its syntax is very much like Pascal and Modula-2. It's brilliant. You must get a copy. Find it on Aminet in dev/lang, and there's even a dev/e with loads of programs and text. Find it also on Fred Fish disks 810 and 848. The author, Wouter van Oortmerssen, is an exceptionally pleasant and helpful guy, and there's a Amiga E mailing list where he and others can help you with any problems (send E-mail to "amigae-request@bkhouse.cts.com" asking to subscribe). Usage ===== Ag2txt13 ------- Ag2txt13 is the KickStart 1.3 (and above, of course) version of Ag2txt. It should also work on earlier KickStarts but I have no way of testing this. This version is not as configurable as ag2txt20, in that you can only specify the input file and the output is sent to the console (this can be redirected of course). As it stands, nodes are highlighted in reverse video and links in italics. This is not configurable from the command line like ag2txt20, but the source is fairly easy to change if you prefer some other setup. As an example, to convert "docs:reference.guide" to "ram:reference.txt": 1> ag2txt13 >ram:reference.txt docs:reference.guide To convert "docs:reference.guide" and print it: 1> ag2txt13 >prt: docs:reference.guide Ag2txt20 -------- Ag2txt20 is the KickStart 2.0 (and above) version of Ag2txt, and it has a nice, standard argument template. This enables the user to specify input and output files (with output defaulting to stdout/console), and to change the way nodes and links are highlighted. The template for the arguments is: FROM/A,TO,NODEFONT=NODE/K,LINKFONT=LINK/K This means the FROM (input) file must be specified, and all the others are optional. Keywords need not be used for the FROM and TO arguments but if you use them you can write the arguments in any order. Otherwise the FROM argument is expected before the TO argument. Keywords must be used for the NODEFONT and LINKFONT arguments (e.g., NODEFONT=PLAIN), and these may occur anywhere on the command line. A shorthand for the NODEFONT and LINKFONT keywords are NODE and LINK (respectively). Therefore, NODEFONT=PLAIN is the same as NODE=PLAIN. The possible values for fonts are: PLAIN (normal typeface) BOLD (bold typeface) ITALIC (italic typeface) REVERSE (reverse video) These default to REVERSE for NODEFONT and ITALIC for LINKFONT. If you plan to print the document it might be best to not use REVERSE. It depends how you printer driver works. As an example, to convert "docs:reference.guide" to "ram:reference.txt" using the default font setup: 1> ag2txt20 from=docs:reference.guide to=ram:reference.txt The same conversion but using a bold typeface for the nodes: 1> ag2txt20 to=ram:reference.txt nodefont=bold from=docs:reference.guide This time using a bold typeface for the links and redirecting the standard output to the destination file: 1> ag2txt20 >ram:reference.txt from=docs:reference.guide link=bold This time printing the converted file with nodes in bold: 1> ag2txt20 node=bold to=prt: from=docs:reference.guide Bugs/Problems ============= At the moment it's fairly memory hungry, requiring two copies of the hypertext file to be present in memory. I did this because the filter version (read a byte, write a byte) was *so* slow on my Amiga. Also, I assume that the produced file will be no bigger than the source file (which is a very fair assumption, given the amount of information the converter discards!). A filter version would not require any such assumptions. It's very easy to alter the source so that using a plain font for either nodes or links means that no escape sequences are generated (helpful if you've got a fussy printer). I don't know why I didn't do this, but it's a good, simple exercise for the reader! Get Amiga E. Learn Amiga E. Be hap-E. Implementation ============== The source is supplied for both programs. You need the Amiga E compiler but it's Public Domain and easily available and brilliant so that's not a problem, is it? Basically, ag2txt is implemented using a tiny state machine a is fairly grotty. But it works. At least, it works for me. I find it useful (for reading Amiga Report!). Legal Junk ========== This program (even if it is small) is Copyright (c) 1993 Jason R. Hulance. Apart from that the Gnu Public License holds. You can contact me by E-mail at "m88jrh@ecs.oxford.ac.uk".