====== ANS2ASC ======

ANSI to Synchronet Ctrl-A message format conversion utility 

The ANS2ASC utility may be used to convert files encoded with ANSI X3.64 terminal escape sequences (e.g. ''*.ans'' files created/edited with an [[resource:ansi editors|ANSI editor]]) into [[Custom:Ctrl-A Codes|Ctrl-A]] encoded output (e.g. Synchronet ''*.asc'' or ''*.msg'' files).

This utility will convert basic non-animated ANSI files into Synchronet Ctrl-A
code files that can be displayed to color or monochrome ANSI terminal users with 
attractive results as well as non-ANSI (e.g. TTY) terminal users. This allows you to use an ANSI
drawing program (such as TheDraw) to create your menus in ANSI and convert the
ANSI file to Ctrl-A message format for your ''.asc'' or ''.msg'' version of the same file (for non-ANSI or ANSI-monochrome users, respectively). Or you can
use the converted file for all users (terminal types) by keeping the ANSI (.ANS) version in
a directory other than your ''[[dir:text]]/menu'' directory.

If, for example, you create a main menu with an ANSI drawing program that you
want your TTY and monochrome-ANSI users to see with attractive output, use
ANS2ASC to create the ''.mon'' and ''.asc'' versions.

Type: ''ans2asc main.ans main.mon''
in your ''[[dir:text]]/menu'' directory to create the monochrome version. 

Type: ''ans2asc main.ans main.asc''
in your ''[[dir:text]]/menu'' directory to create the ASCII (non-ANSI) version.

If you rename ''main.ans'' file or move into a directory other than ''[[dir:text]]/menu'', then
you will not need the ''.mon'' version of the file as the ''.asc'' version will be used for all
terminal types.

This utility is also useful for creating colorful system, newuser, feedback
and other Synchronet ''.msg'' files for display. For example, create 
''[[dir:text]]/system.ans'' with your favorite ANSI editor and then convert to ''.msg'' by
typing: ''ans2asc system.ans system.msg''

The following ANSI terminal sequences (preceded by <ESC>[) are supported:

^ ANSI 	^ Ctrl-A Code	^ Explanation                  ^ Supported by ANSI.SYS  ^
| 2J	| 	L	| Clear Screen (other J values are ignored) | Yes |
| K     |       >       | Clear to end-of-line | Yes |
| #B    |               | Move cursor down # lines, converted to # line-feeds | Yes |
| #C	| 	7Fh-FFh | Move cursor right # columns  | Yes |
| #D    |               | Move cursor left # columns, converted to # backspaces or carriage-return if # >= 80 | Yes |
| 0m	| 	N	| Normal attribute    | Yes |
| 1m	| 	H	| High intensity      | Yes |
| 2m	| 	N	| Low intensity *     | No  |
| 3m	| 	I	| Italic *            | No  |
| 4m	| 	I	| Underline *         | No  | 
| 5m	| 	I	| Blink               | Yes |
| 6m	| 	I	| Rapid Blink *       | No  | 
| 7m	| 	I	| Reverse Video *     | No  | 
| 8m	| 	E((deprecated "elite text" feature))	| Concealed text *    | No  | 
| 30m	| 	K	| Foreground black    | Yes |
| 31m	| 	R	| Foreground red      | Yes | 
| 32m	| 	G	| Foreground green    | Yes |
| 33m	| 	Y	| Foreground yellow   | Yes |
| 34m	| 	B	| Foreground blue     | Yes |
| 35m	| 	M	| Foreground magenta  | Yes |
| 36m	| 	C	| Foreground cyan     | Yes |
| 37m	| 	W	| Foreground white    | Yes |
| 40m	| 	0	| Background black    | Yes |
| 41m	| 	1	| Background red      | Yes |
| 42m	| 	2	| Background green    | Yes |
| 43m	| 	3	| Background yellow   | Yes |
| 44m	| 	4	| Background blue     | Yes |
| 45m	| 	5	| Background magenta  | Yes |
| 46m	| 	6	| Background cyan     | Yes |
| 47m	| 	7	| Background white    | Yes |

===== Options =====

ANS2ASC has the following command-line options:

| -ice            | treat blink as bright-background (iCE colors) |
| -<columns>      | insert conditional-newlines to force wrap (e.g. -80) |
| -normal         | use 'save/normal/restore' attributes for conditional new-lines |
| -newline        | append a newline (CRLF) sequence to output file |
| -clear          | insert a clear screen code at beginning of output file |
| -pause          | append a pause (hit a key) code to end of output file |
| -space          | use space characters for cursor-right movement/alignment |
| -esc            | use C-style string literal escaping of control and CP437 chars |
| -delay <int>    | insert a 1/10th second delay code at output byte interval (lower interval values result in more delays, slower display) |

==== SAUCE ====

The ''-ice'' and ''-<columns>'' option values will be automatically read from the SAUCE metadata appended to the ANSI file, if present.

===== Animation =====

In general, animated ANSI files cannot be converted to equivalent Ctrl-A files. Only cursor positioning ANSI sequences which can be converted to non-ANSI equivalents (e.g. cursor-right or cursor-down positioning) may be converted to Ctrl-A codes. If you see the following warning message from ANS2ASC, that indicates that you most likely are trying to convert an ANSI file with unsupported animation sequences:
  Unsupported ANSI code 'x' (0xYY)"
  
However, unsupported color codes aren't usually an issue:
  Unsupported ANSI code 't' (0x74)

Some ANSI editing programs will save ANSI files with unsupported cursor positioning sequences by default. To avoid saving unsupported cursor positioning sequences when using the **TheDraw**, for example, use the Block-Save feature.

===== See Also =====
  * [[:util:|Utilities]]
  * [[:util:ASC2ANS]]
  * [[:resource:ANSI Editors]]
  * [[:custom:atcodes|@-Codes]]
  * [[:ref:ANSI]]
  * [[:custom:|Customization]]

{{tag>ansi customization}}
