diff options
Diffstat (limited to 'a8eol.rst')
| -rw-r--r-- | a8eol.rst | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/a8eol.rst b/a8eol.rst new file mode 100644 index 0000000..ff81d82 --- /dev/null +++ b/a8eol.rst @@ -0,0 +1,196 @@ +.. RST source for a8eol(1) man page. Convert with: +.. rst2man.py a8eol.rst > a8eol.1 +.. rst2man.py comes from the SBo development/docutils package. + +===== +a8eol +===== + +------------------------------------------------------- +convert Atari 8-bit text files to/from UNIX/Windows/Mac +------------------------------------------------------- + +.. include:: manhdr.rst + +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 list‐ + ing 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: + +.. csv-table:: + :header: "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. + +.. other sections we might want, uncomment as needed. + +.. FILES +.. ===== + +.. ENVIRONMENT +.. =========== + +EXIT STATUS +=========== + +0 for success, non-zero for any error. Error messages are printed to **stderr**. + +.. BUGS +.. ==== + +.. EXAMPLES +.. ======== + +.. include:: manftr.rst + |