From e79bf42c2fa43f131f79d0891694e59434f820e9 Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Sat, 29 Jun 2024 05:58:21 -0400
Subject: a8cat: handle ASCII tab/backspace/bell in -r mode.

---
 a8cat.1 | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

(limited to 'a8cat.1')

diff --git a/a8cat.1 b/a8cat.1
index b6d85a4..42f2017 100644
--- a/a8cat.1
+++ b/a8cat.1
@@ -29,7 +29,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .TH "A8CAT" 1 "2024-06-29" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
-a8cat \- Convert Atari 8-bit text to UTF-8 encoded Unicode.
+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]
@@ -53,13 +53,17 @@ a8cat atari.txt > converted.txt
 .UNINDENT
 .UNINDENT
 .sp
-The output is plain UTF\-8 Unicode, without BOM. 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.
+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.
+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
@@ -80,8 +84,7 @@ option cannot be converted back to ATASCII with the \fB\-r\fP option.
 .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. Output created with this
-option cannot be converted back to ATASCII with the \fB\-r\fP option.
+and bells are translated to the ASCII versions.
 .TP
 .B  \-r
 Reverse conversion: Input is UTF\-8, output is ATASCII (or XL ICS, with \fB\-i\fP).
@@ -106,6 +109,10 @@ be any inverse\-video characters in the result.
 .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.
 .UNINDENT
-- 
cgit v1.2.3