diff options
Diffstat (limited to 'a8eol.1')
| -rw-r--r-- | a8eol.1 | 482 |
1 files changed, 482 insertions, 0 deletions
@@ -0,0 +1,482 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "A8EOL" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools" +.SH NAME +a8eol \- convert Atari 8-bit text files to/from UNIX/Windows/Mac +.\" RST source for a8eol(1) man page. Convert with: +. +.\" rst2man.py a8eol.rst > a8eol.1 +. +.\" rst2man.py comes from the SBo development/docutils package. +. +.SH SYNOPSIS +.sp +\fBa8eol\fP [\fI\-admu8tcpsxih\fP] [\fIinfile\fP] [\fIoutfile\fP] +.SH DESCRIPTION +.sp +\fBa8eol\fP 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. +.SH OPTIONS +.SS File type options: +.INDENT 0.0 +.TP +.B \-a +Input is UNIX, MS\-DOS/Windows, or MacOS < 10 text; convert to Atari (EOL=$9B) +.TP +.B \-d +Input is Atari text; convert to MS\-DOS/Windows (EOL=$0A,$0D) +.TP +.B \-m +Input is Atari text; convert to MacOS < 10 (EOL=$0D) +.TP +.B \-u +Input is Atari text; convert to UNIX (EOL=$0A) +.UNINDENT +.sp +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. +.sp +Only one file type option can be used per run of \fBa8eol\fP\&. If more than +one is given, the last one occurring on the command line will be used. +.SS Translation options: +.INDENT 0.0 +.TP +.B \-n +Translate EOL characters only; pass anything else as\-is (including +tabs and backspaces). +.TP +.B \-c +Replace non\-printing characters with ^x (ASCII input) or {x} +(ATASCII input). This option also enables the \fB\-8\fP option. When +the input file is ATASCII, the output resembles a program list‐ +ing from an old computer magazine (see \fBATASCII CODES\fP, below). +.TP +.B \-p +Replace non\-printing characters with \fI\&.\fP (period, dot). +.TP +.B \-s +Remove (strip) non\-printing characters. +.TP +.B \-x +Replace non\-printing characters with \fI\ex[hex]\fP\&. +.UNINDENT +.sp +With none of the above: EOL, tab, and backspace characters are +translated; everything else is passed through as\-is. +.sp +Only one translation option can be used per run of \fBa8eol\fP\&. If more than +one is given, the last one occurring on the command line will be used. +.SS Other options: +.INDENT 0.0 +.TP +.B \-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 \fB\-c\fP +is used. +.TP +.B \-i +In\-place conversion. Original file renamed to \fIinfile~\fP\&. This option +can\(aqt be used when reading from standard input. +.TP +.B \-q +Quiet operation. Error messages will still be printed. +.TP +.B \-v +Verbose operation. Prints extra info about what \fBa8eol\fP is doing. +.TP +.B \-h +Print built\-in help message and exit. +.UNINDENT +.sp +Leave \fIinfile\fP blank or use \fB\-\fP to read from standard input (in which +case, don\(aqt use the \fB\-i\fP option). +.sp +Leave \fIoutfile\fP blank or use \fB\-\fP to write to standard output. +.SH NOTES +.sp +Without the \fB\-8\fP option, bit 7 is stripped (cleared) for all input +characters, \fIexcept\fP for the ATASCII EOL ($9B) character (when the +input is an Atari file). Bit 7 stripping occurs for each input +character \fIbefore\fP any of the translation options are applied. +.sp +The input type auto\-detection isn\(aqt 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 +\fB\-d\fP, \fB\-m\fP, or \fB\-u\fP\&. +.sp +The auto\-detection also fails with an "Illegal seek" error when +reading from a pipe (e.g. \fBcat file | a8eol\fP). To avoid this, either +set the input type explicitly with one of \fB\-[admu]\fP, 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\(aqd take to fix it. +.sp +The \fB\-a\fP option is "magical" in that it can handle input with UNIX +(\fI\en\fP), DOS (\fI\er\en\fP), or Mac Classic (\fI\er\fP only) line endings. In fact, it +can handle an input file containing any combination of the three line +ending types in the same file. +.SH ATASCII CODES +.sp +When the \fI\-c\fP 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. +.sp +List of code translations: +.TS +center; +|l|l|l|l|l|. +_ +T{ +Dec +T} T{ +Hex +T} T{ +Keystroke(s) +T} T{ +Description +T} T{ +T} +_ +T{ +\-\- +T} T{ +\-\- +T} T{ +{inv} +T} T{ +Inverse Video (800: Atari Logo) +T} T{ +Start a sequence of inverse video characters +T} +_ +T{ +\-\- +T} T{ +\-\- +T} T{ +{norm} +T} T{ +Inverse Video (800: Atari Logo) +T} T{ +End a sequence of inverse video characters (back to normal) +T} +_ +T{ +0 +T} T{ +00 +T} T{ +{ctrl\-,} +T} T{ +Ctrl , +T} T{ +Heart; replaces ASCII NUL +T} +_ +T{ +27 +T} T{ +1B +T} T{ +{esc} +T} T{ +Esc Esc +T} T{ +Literal Escape character +T} +_ +T{ +28 +T} T{ +1C +T} T{ +{up} +T} T{ +Esc Ctrl \- +T} T{ +Cursor Up +T} +_ +T{ +29 +T} T{ +1D +T} T{ +{down} +T} T{ +Esc Ctrl = +T} T{ +Cursor Down +T} +_ +T{ +30 +T} T{ +1E +T} T{ +{left} +T} T{ +Esc Ctrl + +T} T{ +Cursor Left +T} +_ +T{ +31 +T} T{ +1F +T} T{ +{right} +T} T{ +Esc Ctrl * +T} T{ +Cursor Right +T} +_ +T{ +96 +T} T{ +60 +T} T{ +{ctrl\-.} +T} T{ +Ctrl . +T} T{ +Diamond; replaces ASCII grave accent: \(ga +T} +_ +T{ +123 +T} T{ +7B +T} T{ +{ctrl\-;} +T} T{ +Ctrl ; +T} T{ +Club; replaces ASCII left brace: { +T} +_ +T{ +125 +T} T{ +7D +T} T{ +{clear} +T} T{ +Esc Ctrl < or Esc Shift < +T} T{ +Clear screen (CLR/HOME on 800); Replaces ASCII right brace: } +T} +_ +T{ +126 +T} T{ +7E +T} T{ +{bksp} +T} T{ +Esc Backspace +T} T{ +Backspace (BACK S on 800); Replaces ASCII tilde: ~ +T} +_ +T{ +127 +T} T{ +7F +T} T{ +{tab} +T} T{ +Esc Tab +T} T{ +Tab to next tab stop; Replaces ASCII DEL: ~ +T} +_ +T{ +155 +T} T{ +9B +T} T{ +\-\- +T} T{ +Enter +T} T{ +Atari EOL (translated to \en, \er\en, or \er) +T} +_ +T{ +156 +T} T{ +9C +T} T{ +{del\-line} +T} T{ +Esc Shift BackSp +T} T{ +Delete logical line @ cursor +T} +_ +T{ +157 +T} T{ +9D +T} T{ +{ins\-line} +T} T{ +Esc Shift > +T} T{ +Insert blank line @ cursor +T} +_ +T{ +158 +T} T{ +9E +T} T{ +{clr\-tab} +T} T{ +Esc Ctrl Tab +T} T{ +Clear current tab stop +T} +_ +T{ +159 +T} T{ +9F +T} T{ +{set\-tab} +T} T{ +Esc Shift Tab +T} T{ +Set tab stop @ cursor position +T} +_ +T{ +253 +T} T{ +FD +T} T{ +{bell} +T} T{ +Esc Ctrl 2 +T} T{ +Ring bell (800: internal spkr) +T} +_ +T{ +254 +T} T{ +FE +T} T{ +{del\-char} +T} T{ +Esc Ctrl BackSp +T} T{ +Delete character @ cursor +T} +_ +T{ +255 +T} T{ +FF +T} T{ +{ins\-char} +T} T{ +Esc Ctrl > +T} T{ +Insert one space @ cursor +T} +_ +.TE +.sp +Other control characters are listed as \fI{ctrl\-X}\fP, where \fIX\fP is the +keystroke to use for entering the character. +.\" other sections we might want, uncomment as needed. +. +.\" FILES +. +.\" ===== +. +.\" ENVIRONMENT +. +.\" =========== +. +.SH EXIT STATUS +.sp +0 for success, non\-zero for any error. Error messages are printed to \fBstderr\fP\&. +.\" BUGS +. +.\" ==== +. +.\" EXAMPLES +. +.\" ======== +. +.SH COPYRIGHT +.sp +WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. +.SH AUTHOR +.INDENT 0.0 +.IP B. 3 +Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +\fBa8eol\fP(1), +\fBa8utf8\fP(1), +\fBatr2xfd\fP(1), +\fBatrsize\fP(1), +\fBaxe\fP(1), +\fBblob2c\fP(1), +\fBcart2xex\fP(1), +\fBdasm2atasm\fP(1), +\fBfenders\fP(1), +\fBrom2cart\fP(1), +\fBunmac65\fP(1), +\fBxexcat\fP(1), +\fBxexsplit\fP(1), +\fBxfd2atr\fP(1). +.sp +Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference +Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. +.\" Generated by docutils manpage writer. +. |