initial commit

1 files changed, 482 insertions, 0 deletions

diff --git a/a8eol.1 b/a8eol.1
new file mode 100644
index 0000000..daf4993
--- /dev/null
+++ b/a8eol.1
@@ -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.
+.