path: root/a8cat.1

.\" 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 "A8CAT" 1 "2024-07-21" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
a8cat \- Convert Atari 8-bit text to UTF-8 encoded Unicode (and back).
.SH SYNOPSIS
.sp
\fIa8cat\fP [\fB\-r\fP] [\fB\-i\fP] [\fB\-u\fP] [\fB\-t\fP] [\fIinfile\fP] [\fIinfile ...\fP]
.SH DESCRIPTION
.sp
Convert Atari 8\-bit ATASCII or XL ICS (International Character
Set) text to UTF\-8 encoded Unicode. Control graphics characters are
replaced with their nearest Unicode equivalents (mostly from the Box
Drawing block, or from the Basic Latin block with \fB\-i\fP option).
.sp
If no \fIinfile\fPs are given, input is read from standard input. Output always
goes to standard output; to write to a file, use a command like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
a8cat atari.txt > converted.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The output is UTF\-8 Unicode, without BOM, but possibly with
ANSI/VT\-100 control sequences. It will display correctly in modern
terminals that support Unicode and UTF\-8. If you get lots of "empty
rectangle" characters, it means your font lacks the glyphs for the
codepoints; try using the Deja Vu Sans and/or Symbola fonts.
.sp
If you want to pipe the output to a pager, \fBless \-MR\fP is
recommended. It will display the inverse characters correctly.
.sp
It\(aqs even possible to edit the converted text and turn it back into
ATASCII, if you\(aqre very careful. See the \fB\-r\fP option, below.
.sp
Inverse video (characters codes above \fB$80\fP) are translated using
the ANSI/VT\-100 reverse video escape sequences. Exception: \fB$9B\fP
(Atari EOL) is translated to \fB\en\fP (newline).
.SH OPTIONS
.INDENT 0.0
.TP
.B  \-i
Input uses Atari XL/XE International Character Set encoding, rather than
ATASCII graphics.
.TP
.B  \-u
Use "underlining" for inverse video. Each inverse character is followed by
a backspace, then a \fI_\fP character. When viewed in a pager such as \fBless\fP(1),
this causes the characters to appear underlined. Output created with this
option cannot be converted back to ATASCII with the \fB\-r\fP option.
.TP
.B  \-t
Text mode. Normally, everything but EOL (\fB$9B\fP) is converted to a
Unicode graphics character. In text mode, ATASCII tabs, backspace,
and bells are translated to the ASCII versions.
.TP
.B  \-r
Reverse conversion: Input is plain text, or UTF\-8 created by a previous
run of \fBa8cat\fP; output is ATASCII (or XL ICS, with \fB\-i\fP). ASCII
tabs, backspaces, and newlines will be coverted to the ATASCII
equivalent. ASCII carriage returns will be silently ignored.
.sp
Only the UTF\-8 codepoints that correspond to ATASCII characters will
be converted. If the \fB\-i\fP option was used to create the input, it
must be used with \fB\-r\fP also.
.sp
\fBa8cat\fP will refuse to print ATASCII to a terminal. You must
redirect or pipe the output.
.TP
.B  \-m
Magazine listing mode. Rather than Unicode graphics characters,
ATASCII characters are printed in symbolic form, e.g. \fI{clear}\fP or
\fI{ctrl\-A}\fP\&. The result is similar to type\-in listings in magazines
like Antic, Analog, or Compute! Output created with this option
cannot be converted back to ATASCII with the \fB\-r\fP option.
.TP
.B  \-s
Strip the inverse video bit (bit 7) from all characters except the
EOL (\fB$9B\fP). Output created with this option can be converted
back to ATASCII with the \fB\-r\fP option, but of course there won\(aqt
be any inverse\-video characters in the result.
.TP
.B  \-v
Verbose operation.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-\-\fP
End of options; the rest of the arguments are filenames. Use this if you\(aqre
trying to work with files whose names begin with \fI\-\fP\&.
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Show built\-in help and exit.
.TP
.B \fB\-\-version\fP
Show version number and exit.
.UNINDENT
.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
\fBa8cat\fP(1),
\fBa8eol\fP(1),
\fBa8xd\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBbas2aplus\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdiffbas\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\fP(1),
\fBwhichbas\fP(1),
\fBxex1to2\fP(1),
\fBxexamine\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1),
\fBxex\fP(5),
\fBatascii\fP(7).
.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.
.