diff options
Diffstat (limited to 'a8cat.1')
| -rw-r--r-- | a8cat.1 | 176 |
1 files changed, 176 insertions, 0 deletions
@@ -0,0 +1,176 @@ +.\" 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-24" "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), +\fBfauxtari\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. +. |