aboutsummaryrefslogtreecommitdiff
path: root/a8cat.1
blob: 58c9d55905291a595cd075599861f7c5d31d1725 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
.\" 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-09" "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),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\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.
.