home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 26 / CD_ASCQ_26_1295.iso / vrac / reansi12.zip / REANSI.DOC < prev    next >
Text File  |  1995-08-17  |  10KB  |  255 lines
  1.       REANSI 1.2 -- a program to convert between ANSI/AVATAR/ASCII
  2.           Written and copyright 1995 by Thomas Almy
  3.  
  4.  
  5. REANSI can be used without charge, and distributed providing
  6. no modifications are made and no charge (other than media or access
  7. time) is made. REANSI may not be bundled with any commercial product.
  8.  
  9. A valid distribution of REANSI contains the following files:
  10.  
  11. REANSI.C    Source code
  12. REANSI.EXE    Executable code
  13. REANSI.DOC    This documentation
  14.  
  15. This program converts files containing ANSI and/or AVATAR terminal
  16. control sequences and/or PC-8 ("ANSI Graphic") characters into "plain
  17. vanila" ASCII, optimal (?) ANSI, or AVATAR. It is based on the author's
  18. program UNANSI which converts ANSI and/or PC-8 to plain ASCII. This
  19. program is a superset of UNANSI.
  20.  
  21. Common uses of REANSI include:
  22.     Compressing ANSI display files, and removing "animation".
  23.     Converting ANSI display files to monochrome.
  24.     Converting ANSI display files to AVATAR.
  25.     Displaying AVATAR files.
  26.     Converting ASCII files to "plain vanilla" ASCII.
  27.     Making printer files containing overstrikes displayable.
  28.     Making display files (ANSI or AVATAR) printable.
  29.     Converting into and out of RemoteAccess(TM) color codes
  30.  
  31. REANSI works by maintaining a "virtual display" of how the characters
  32. would appear, and then writes to the output what gets scrolled off
  33. the top of the screen or would get erased. Because a standard 24 line
  34. terminal is being emulated, it is assumed that only 24 lines can
  35. appear on the virtual display. (Note: if you need the program to work
  36. for some other screen size, the program can be easily modified and
  37. recompiled using any C compiler).
  38.  
  39. Because of the virtual display, REANSI removes all "animation" in the
  40. input file. 
  41.  
  42. REANSI can be used as a filter, reading from standard input and
  43. writing to standard output. If a single filename is given on the
  44. command line, that is the input file. A second filename will be taken
  45. as the output file. Any command switches follow the file names.
  46.  
  47. Execute "REANSI -?" to get a usage message.
  48.  
  49. The input file may contain any of the ANSI commands, and the program
  50. will respond to cursor positioning, erase, and display attribute
  51. (color,bright,blink) commands supported by DOS ANSI.SYS. In addition,
  52. tab, formfeed and backspace characters are processed. AVATAR/0 codes
  53. (cursor positioning, display attribute, and run-length encoding) are
  54. also processed. The AVATAR codes start with control-V or control-Y
  55. and should not interfere with normal use.
  56.  
  57. To perform successfully, several input and output options are
  58. available as command line switches. The input options control how the
  59. incoming file is used to write to the virtual display, while the
  60. output options control how the virtual display contents are written
  61. to the file. You set the input options for the type of file you are
  62. converting and the output options for the type of file you are
  63. converting to.
  64.  
  65. INPUT OPTIONS
  66.     -p     -- input is for printer
  67.     -s     -- input assumes cursor sticks at right edge
  68.     -cN    -- initial color attribute is N (hexidecimal value)
  69.     -i     -- ignore AVATAR codes in input
  70.     -r     -- accept RemoteAccess color codes in input
  71.  
  72. If the input file was intended for a printer, it might assume the
  73. ability to overprint. The -p switch causes whitespace to be non-printing
  74. (so overprinting a space won't erase what is beneath it), and also
  75. will ignore underscores that would overprint characters.
  76.  
  77. When the 80th character is written on a line (in the "virtual
  78. display"), it is assumed the cursor wraps to the next line. An ANSI
  79. control sequence (or the -s command line switch) can change the
  80. operation mode so that the cursor sticks at the 80th column. This
  81. might be necessary for input files intended for printers.
  82.  
  83. The initial color attribute is assumed to be white on black. The -c
  84. option allows setting the value. This would normally only need to be
  85. done for environments where the display color is different. For
  86. instance AVATAR defaults to cyan on black (-c3). If the default
  87. background color is wrong, then "bleeding" will occur at the end of
  88. lines and there could be some color errors blank background areas. If
  89. the default foreground is wrong then text may start in the wrong
  90. color. 
  91.  
  92. The value can be set by adding up the hexidecimal values for the three
  93. fields:
  94.     ******************************
  95.     foreground color:
  96.     01    Blue
  97.     02    Green
  98.     03    Cyan
  99.     04    Red
  100.     05    Magenta
  101.     06    Brown
  102.     07    White (light grey)
  103.     08    Dark grey
  104.     09    Bright blue
  105.     0A    Bright green
  106.     0B    Bright cyan
  107.     0C    Bright red
  108.     0D    Bright magenta
  109.     0E    Yellow
  110.     0F    Bright White
  111.     
  112.     background color:
  113.     10    Blue
  114.     20    Green
  115.     30    Cyan
  116.     40    Red
  117.     50    Magenta
  118.     60    Brown
  119.     70    White (light grey)
  120.     
  121.     blink:
  122.     80    blink
  123.     ******************************
  124.  
  125. The -i option prevents the interpretation of AVATAR codes in the
  126. input. Note that the formfeed character clears the virtual screen and
  127. set the color to cyan on black when AVATAR is used, while with the -i
  128. option the screen is cleared to the current color.
  129.  
  130. The -r switch is used when reading files using the RemoteAccess BBS
  131. software color codes (^K[nn format). By default, this feature is
  132. disabled. Note that REANSI cannot handle the language prompt commands
  133. in input.
  134.  
  135. OUTPUT OPTIONS
  136.     -x     -- don't translate PC-8 to ASCII
  137.     -f     -- don't output formfeeds
  138.     -w     -- output wraps after 80 characters
  139.     -t     -- use tab characters in output
  140.     -a     -- output ANSI positioning codes and color codes
  141.     -m     -- output ANSI positioning codes only
  142.     -v     -- output AVATAR codes
  143.     -o     -- output RemoteAccess color codes
  144.  
  145.  
  146. The -x option is very important. Normally characters in the PC-8
  147. character set (the IBM graphic characters which are commonly found in
  148. ANSI/AVATAR files) are converted to 7 bit ASCII, which can be
  149. universally displayed and printed. This translation is inhibited with
  150. the -x option. You will probably always want to use -x if you also
  151. use -a, -m, or -v (described below).
  152.  
  153. The -w switch controls the handling of the 80th column.  By default
  154. it is assumed that the output file will be sent to devices that will
  155. print 80 characters without wrapping (such as most printers). If
  156. output is destined for a device which wraps (such as an 80 column
  157. display), the -w switch should be used. On the other hand, if output
  158. is to the display, and is always less than 80 characters or the
  159. display is set to "stick" (and ANSI option), or the display is larger
  160. than 80 columns, then the -w switch should not be used. Got that?
  161.  
  162. The tab character is not used in the output unless the -t command
  163. line switch is given. Use of -t can reduce file size, but not all
  164. output devices recognize tabs. The -t switch cannot be used when the
  165. -a, -m, or -v switches are specified; cursor travel is controlled
  166. by ANSI or AVATAR sequences in these cases. The -t switch cannot be
  167. used with the -o switch since no special cursor control is used in
  168. that case.
  169.  
  170. The ANSI (or AVATAR) clear display command is interpreted to mean the
  171. end of a page. When this occurs, the contents of the virtual display
  172. are written out, followed by a formfeed character. This should handle
  173. multi-frame ANSI files.  The formfeeds can be eliminated by the -f
  174. switch. If the -a, -m, or -v switches are used, the appropriate ANSI
  175. or AVATAR clearscreen codes are always sent, and the -f switch is
  176. ignored. If the -o switch is used, the -f switch is forced.
  177.  
  178. When the -a switch is used, color ANSI is output, while when -m is
  179. used monochrome ANSI (ANSI cursor positioning sequences, but no color
  180. selection) is output, and when -v is used color AVATAR is output.
  181. With these selections one would typically also use the -x switch. 
  182.  
  183. For best results with -a and -v, input should be limited to 79
  184. characters per line and have been created making no assumptions as to
  185. colors. The colors are always reset to default at the end of the
  186. output. Note that all animation is removed, and display is always
  187. left to right then top to bottom.
  188.  
  189. The -o switch is for RemoteAccess BBS software users. It generates a
  190. file that can be used as an .ASC file which will have color codes
  191. that will be ignored, converted to ANSI, or converted to AVATAR on
  192. the fly depending on the caller's terminal settings. This can result
  193. in a substantial savings in number of files and space needed in a
  194. typical RemoteAccess installation. 
  195.  
  196.  
  197. Examples of use>>>>>
  198.  
  199. To convert a color ANSI display file (no more than 79 characters per
  200. line), X.ANS, to an AVATAR file, X.AVT, execute:
  201.  
  202. REANSI x.ans x.avt -x -v
  203.  
  204. To display an AVATAR file, X.AVT, (assuming an ANSI.SYS driver is
  205. loaded): 
  206.  
  207. REANSI x.avt -x -a
  208.  
  209. To convert a color ANSI display file, X.ANS, to a monchrome file
  210. viewable on a PC without ANSI.SYS, X.ASC, execute:
  211.  
  212. REANSI x.ans x.asc -x -w -f -t
  213.  
  214. As above, but assuming the PC has ANSI.SYS:
  215.  
  216. REANSI x.ans x.asc -x -w -f -m
  217.  
  218. To print the file on a dot matrix printer on LPT1 capable of
  219. displaying the PC character set, execute:
  220.  
  221. REANSI x.ans lpt1 -x
  222.  
  223. To convert to a file, X.ASC, to one that can be viewed on any
  224. terminal, execute:
  225.  
  226. REANSI x.ans x.asc -w -f -t
  227.  
  228. To convert a file X.DOC that uses the PC-8 character set and
  229. "overprints" for bold or underline effects into a file, X.TXT, that
  230. is pure ASCII for printing or viewing on the display:
  231.  
  232. REANSI x.doc x.txt -p
  233.  
  234. To convert an ANSI RemoteAccess BBS menu to a universal *.ASC file,
  235. execute: 
  236.  
  237. REANSI menu.ans menu.asc -o -x
  238.  
  239. (be sure to delete the menu.asc file when you are done!)
  240.  
  241. To convert the RemoteAccess .ASC file back to ANSI, execute:
  242.  
  243. REANSI menu.asc menu.ans -r -x
  244.  
  245. While REANSI was designed to compile on MSDOS systems, it should
  246. compile with few modifications on any system.
  247.  
  248. Tom Almy
  249. 08/95
  250.  
  251. I can be contacted at tom.almy@tek.com, or 1:105/290, or by mail at
  252. 17830 SW Shasta Trail, Tualatin, OR 97062. When coresponding via
  253. mail, please enclose a stamped, self-addressed envelope if you desire a
  254. reply.
  255.