home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / jËzyki_programowania / amigae / e_v3.2a / pdsrc / ag2txt / ag2txt.doc next >
Text File  |  1996-09-17  |  6KB  |  146 lines
  1. Ag2txt - Turns AmigaGuide files into flat, readable and printable text.
  2. ======
  3.  
  4. Function
  5. ========
  6.  
  7. Ag2txt is a fictious program.  It becomes reality in the form of "ag2txt13"
  8. for KickStart 1.3 (maybe older versions, too) and "ag2txt20" for KickStart
  9. 2.0 (and above).  The purpose of Ag2txt is to convert AmigaGuide hypertext
  10. files into flat, readable and printable text.  It does this by recognising
  11. nodes and links and highlighting these.  All other hypertext information is
  12. discarded.  This means that if the hypertext document comprises several
  13. files you will need to convert all of them.
  14.  
  15. The converted file uses Ansi escape sequences to do the highlighting, so
  16. any decent Amiga text reader should display them properly.  Also, any
  17. decent printer driver will convert these sequences into the appropriate
  18. printer control codes, so you can send the file directly to PRT: and have
  19. it printed.
  20.  
  21. At first sight this may seem like a completely useless program.  I agree.
  22. AmigaGuide and MultiView are much better and hypertext is really good fun.
  23. But there are times when you want to just read the text, and printing
  24. hypertext properly would require a very strange printer and some weird
  25. paper!  In fact, I have derived a C version of this program so that I can
  26. run it on a Unix machine (in an Xterm).
  27.  
  28. A blatant plug now follows: Ag2txt was written in Amiga E (v2.1b), which is
  29. a Public Domain Amiga-specific programming language based heavily on C and
  30. with many other useful features 'borrowed' from other language.  Its syntax
  31. is very much like Pascal and Modula-2.  It's brilliant.  You must get a
  32. copy.  Find it on Aminet in dev/lang, and there's even a dev/e with loads
  33. of programs and text.  Find it also on Fred Fish disks 810 and 848.  The
  34. author, Wouter van Oortmerssen, is an exceptionally pleasant and helpful
  35. guy, and there's a Amiga E mailing list where he and others can help you
  36. with any problems (send E-mail to "amigae-request@bkhouse.cts.com" asking
  37. to subscribe).
  38.  
  39.  
  40. Usage
  41. =====
  42.  
  43. Ag2txt13
  44. -------
  45. Ag2txt13 is the KickStart 1.3 (and above, of course) version of Ag2txt.  It
  46. should also work on earlier KickStarts but I have no way of testing this.
  47. This version is not as configurable as ag2txt20, in that you can only
  48. specify the input file and the output is sent to the console (this can be
  49. redirected of course).
  50.  
  51. As it stands, nodes are highlighted in reverse video and links in italics.
  52. This is not configurable from the command line like ag2txt20, but the
  53. source is fairly easy to change if you prefer some other setup.
  54.  
  55. As an example, to convert "docs:reference.guide" to "ram:reference.txt":
  56.  
  57.   1> ag2txt13 >ram:reference.txt docs:reference.guide
  58.  
  59. To convert "docs:reference.guide" and print it:
  60.  
  61.   1> ag2txt13 >prt: docs:reference.guide
  62.  
  63.  
  64. Ag2txt20
  65. --------
  66. Ag2txt20 is the KickStart 2.0 (and above) version of Ag2txt, and it has a
  67. nice, standard argument template.  This enables the user to specify input
  68. and output files (with output defaulting to stdout/console), and to change
  69. the way nodes and links are highlighted.  The template for the arguments
  70. is:
  71.  
  72.   FROM/A,TO,NODEFONT=NODE/K,LINKFONT=LINK/K
  73.  
  74. This means the FROM (input) file must be specified, and all the others are
  75. optional.  Keywords need not be used for the FROM and TO arguments but if
  76. you use them you can write the arguments in any order.  Otherwise the FROM
  77. argument is expected before the TO argument.  Keywords must be used for the
  78. NODEFONT and LINKFONT arguments (e.g., NODEFONT=PLAIN), and these may occur
  79. anywhere on the command line.  A shorthand for the NODEFONT and LINKFONT
  80. keywords are NODE and LINK (respectively).  Therefore, NODEFONT=PLAIN is
  81. the same as NODE=PLAIN.  The possible values for fonts are:
  82.  
  83.   PLAIN   (normal typeface)
  84.   BOLD    (bold typeface)
  85.   ITALIC  (italic typeface)
  86.   REVERSE (reverse video)
  87.  
  88. These default to REVERSE for NODEFONT and ITALIC for LINKFONT.  If you plan
  89. to print the document it might be best to not use REVERSE.  It depends how
  90. you printer driver works.
  91.  
  92. As an example, to convert "docs:reference.guide" to "ram:reference.txt"
  93. using the default font setup:
  94.  
  95.   1> ag2txt20 from=docs:reference.guide to=ram:reference.txt
  96.  
  97. The same conversion but using a bold typeface for the nodes:
  98.  
  99.   1> ag2txt20 to=ram:reference.txt nodefont=bold from=docs:reference.guide 
  100.  
  101. This time using a bold typeface for the links and redirecting the standard
  102. output to the destination file:
  103.  
  104.   1> ag2txt20 >ram:reference.txt from=docs:reference.guide link=bold
  105.  
  106. This time printing the converted file with nodes in bold:
  107.  
  108.   1> ag2txt20 node=bold to=prt: from=docs:reference.guide 
  109.  
  110.  
  111. Bugs/Problems
  112. =============
  113.  
  114. At the moment it's fairly memory hungry, requiring two copies of the
  115. hypertext file to be present in memory.  I did this because the filter
  116. version (read a byte, write a byte) was *so* slow on my Amiga.
  117.  
  118. Also, I assume that the produced file will be no bigger than the source
  119. file (which is a very fair assumption, given the amount of information the
  120. converter discards!).  A filter version would not require any such
  121. assumptions.
  122.  
  123. It's very easy to alter the source so that using a plain font for either
  124. nodes or links means that no escape sequences are generated (helpful if
  125. you've got a fussy printer).  I don't know why I didn't do this, but it's a
  126. good, simple exercise for the reader!  Get Amiga E.  Learn Amiga E.  Be
  127. hap-E.
  128.  
  129.  
  130. Implementation
  131. ==============
  132.  
  133. The source is supplied for both programs.  You need the Amiga E compiler
  134. but it's Public Domain and easily available and brilliant so that's not a
  135. problem, is it?  Basically, ag2txt is implemented using a tiny state
  136. machine a is fairly grotty.  But it works.  At least, it works for me.  I
  137. find it useful (for reading Amiga Report!).
  138.  
  139.  
  140. Legal Junk
  141. ==========
  142.  
  143. This program (even if it is small) is Copyright (c) 1993 Jason R. Hulance.
  144. Apart from that the Gnu Public License holds.  You can contact me by E-mail
  145. at "m88jrh@ecs.oxford.ac.uk".
  146.