A8EOL(1)

NAME
a8eol - convert Atari 8-bit text files to/from UNIX/Windows/Mac

SYNOPSIS

a8eol [-admu8tcpsxih] [infile] [outfile]

DESCRIPTION

a8eol converts between ATASCII and UNIX, MS-DOS/Windows, and Mac text file formats. It can auto-detect the input file format and set the output format accordingly, or the user can explicitly set the input and output formats. Various options are available for translating non-printing characters, including a mode similar to what old computer magazines used for program listings.

OPTIONS

  File type options:

-a  Input is UNIX, MS-DOS/Windows, or MacOS < 10 text; convert to Atari (EOL=$9B)

-d  Input is Atari text; convert to MS-DOS/Windows (EOL=$0A,$0D)

-m  Input is Atari text; convert to MacOS < 10 (EOL=$0D)

-u  Input is Atari text; convert to UNIX (EOL=$0A)

    With none of the above: input type is auto-detected; output type is UNIX if input is Atari, or Atari if input is UNIX/DOS/Mac.

    Only one file type option can be used per run of a8eol. If more than one is given, the last one occurring on the command line will be used.

  Translation options:

-n  Translate EOL characters only; pass anything else as-is (including tabs and backspaces).

-c  Replace non-printing characters with ^x (ASCII input) or {x} (ATASCII input). This option also enables the -8 option. When the input file is ATASCII, the output resembles a program listing from an old computer magazine (see ATASCII CODES, below).

-p  Replace non-printing characters with . (period, dot).

-s  Remove (strip) non-printing characters.

-x  Replace non-printing characters with \x[hex].

    With none of the above: EOL, tab, and backspace characters are translated; everything else is passed through as-is.

    Only one translation option can be used per run of a8eol. If more than one is given, the last one occurring on the command line will be used.

  Other options:

-8  8-bit ASCII/ATASCII mode: Do not strip bit 7 (inverse video). This option may be used alone or combined with any of the translation options, above. Characters with bit 7 set are considered non-printing. This option is always enabled when -c is used.

-i  In-place conversion. Original file renamed to infile~. This option can't be used when reading from standard input.

-q  Quiet operation. Error messages will still be printed.

-v  Verbose operation. Prints extra info about what a8eol is doing.

-h  Print built-in help message and exit.

    Leave infile blank or use - to read from standard input (in which case, don't use the -i option).

    Leave outfile blank or use - to write to standard output.

NOTES

Without the -8 option, bit 7 is stripped (cleared) for all input characters, except for the ATASCII EOL ($9B) character (when the input is an Atari file). Bit 7 stripping occurs for each input character before any of the translation options are applied.

The input type auto-detection isn't perfect. It scans from the beginning of the input, looking for either an ATASCII EOL or an ASCII carriage return or linefeed. An Atari file with ATASCII graphics may be mis-detected as an ASCII file, if it contains any $0A or $0D bytes before the first EOL ($0A and $0D are graphics characters, in ATASCII). If this happens, force Atari input with -d, -m, or -u.

The auto-detection also fails with an "Illegal seek" error when reading from a pipe (e.g. cat file | a8eol). To avoid this, either set the input type explicitly with one of -[admu], or read from a regular file (possibly a temporary one created just for this purpose). This is a bug (not a feature), but probably not worth the time it'd take to fix it.

The -a option is "magical" in that it can handle input with UNIX (\n), DOS (\r\n), or Mac Classic (\r only) line endings. In fact, it can handle an input file containing any combination of the three line ending types in the same file.

ATASCII CODES

When the -c option is used on ATASCII input, the special Atari character codes are translated into human-readable descriptive strings. This is similar to the way old magazines (Compute!, Antic, Analog) printed ATASCII codes in typeset program listings.

List of code translations:
Dec | Hex | Keystroke(s) | Description |
-- | -- | {inv} | Inverse Video (800: Atari Logo) | Start a sequence of inverse video characters
-- | -- | {norm} | Inverse Video (800: Atari Logo) | End a sequence of inverse video characters (back to normal)
0 | 00 | {ctrl-,} | Ctrl , | Heart; replaces ASCII NUL
27 | 1B | {esc} | Esc Esc | Literal Escape character
28 | 1C | {up} | Esc Ctrl - | Cursor Up
29 | 1D | {down} | Esc Ctrl = | Cursor Down
30 | 1E | {left} | Esc Ctrl + | Cursor Left
31 | 1F | {right} | Esc Ctrl * | Cursor Right
96 | 60 | {ctrl-.} | Ctrl . | Diamond; replaces ASCII grave accent: `
123 | 7B | {ctrl-;} | Ctrl ; | Club; replaces ASCII left brace: {
125 | 7D | {clear} | Esc Ctrl < or Esc Shift < | Clear screen (CLR/HOME on 800); Replaces ASCII right brace: }
126 | 7E | {bksp} | Esc Backspace | Backspace (BACK S on 800); Replaces ASCII tilde: ~
127 | 7F | {tab} | Esc Tab | Tab to next tab stop; Replaces ASCII DEL: ~
155 | 9B | -- | Enter | Atari EOL (translated to \n, \r\n, or \r)
156 | 9C | {del-line} | Esc Shift BackSp | Delete logical line @ cursor
157 | 9D | {ins-line} | Esc Shift > | Insert blank line @ cursor
158 | 9E | {clr-tab} | Esc Ctrl Tab | Clear current tab stop
159 | 9F | {set-tab} | Esc Shift Tab | Set tab stop @ cursor position
253 | FD | {bell} | Esc Ctrl 2 | Ring bell (800: internal spkr)
254 | FE | {del-char} | Esc Ctrl BackSp | Delete character @ cursor
255 | FF | {ins-char} | Esc Ctrl > | Insert one space @ cursor

Other control characters are listed as {ctrl-X}, where X is the keystroke to use for entering the character.

EXIT STATUS

0 for success, non-zero for any error. Error messages are printed to stderr.

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.