From 107731d03c8627f888dcc52a6573e54b2c8c1dac Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Sun, 30 Jun 2024 05:07:20 -0400
Subject: a8xd: tweak code, doc.

---
 a8xd.1   |  6 +++---
 a8xd.c   | 38 ++++++++++++++++++++++++++++++--------
 a8xd.rst | 10 +++++-----
 3 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/a8xd.1 b/a8xd.1
index a02fc9e..d9d454c 100644
--- a/a8xd.1
+++ b/a8xd.1
@@ -69,12 +69,12 @@ Without \fIinfile\fP, or if \fIinfile\fP is \fB\-\fP, \fBa8xd\fP reads from stan
 ANTIC mode: treat the input as screen bytes. Can usefully be combined
 with \fB\-g\fP\&.
 .TP
-.B  \-i
-Print XL/XE International Character Set conversions instead of ATASCII.
-.TP
 .B  \-g
 Graphics mode. Changes the colorization so it looks like \fIGRAPHICS 1\fP (or 2)
 on the Atari.
+.TP
+.B  \-i
+Print XL/XE International Character Set conversions instead of ATASCII.
 .UNINDENT
 .INDENT 0.0
 .TP
diff --git a/a8xd.c b/a8xd.c
index 3871248..534267c 100644
--- a/a8xd.c
+++ b/a8xd.c
@@ -8,12 +8,27 @@
 
 #include "atables.h"
 
+/* printf() formats for lower/uppercase hex. */
+#define LC_WORD_FMT "%04x"
+#define LC_BYTE_FMT "%02x"
+#define UC_WORD_FMT "%04X"
+#define UC_BYTE_FMT "%02X"
+
+/* translation table (see atables.c), choices are
+   ata2utf, ics2utf, or magazine. */
 const char **table = ata2utf;
+
+/* hardcoded ANSI-style escape sequences, work fine on
+	all modern terminal emulators. */
 const char *inverse_on  = "\x1b[7m";
 const char *inverse_off = "\x1b[0m";
-const char *word_format = "%04x";
-const char *byte_format = "%02x";
+const char *color_off = "\x1b[0m";
+
+/* -u option changes these. */
+const char *word_format = LC_WORD_FMT;
+const char *byte_format = LC_BYTE_FMT;
 
+/* command line options change these. */
 int verbose = 0, color = 1, disp_offset = 0, maxlen = 0;
 int seek_whence = 0, seekpos = 0, filepos = 0, limit = 0;
 int graphics = 0, screencodes = 0;
@@ -34,8 +49,17 @@ void die(const char *msg) {
 }
 
 void print_help(void) {
-	printf("Usage: %s [-i] [-l limit] [-m] [-o offset] [-s [-]seek] [-u] [-v] [file]\n", self);
-	printf("With no [file], or '-', reads from stdin.\n");
+	printf("Usage:\n  %s [-a] [-g] [-i] [-l limit] [-m] [-o offset] [-s [-]seek] [-u] [-v] [file]\n", self);
+	printf("   -a: Input is ANTIC screencodes (default is ATASCII).\n");
+	printf("   -g: GR.1/2 style colorization.\n");
+	printf("   -i: Input is XL intl charset (default is ATASCII).\n");
+	printf("   -l: Stop after <limit> bytes.\n");
+	printf("   -m: Monochrome (color off).\n");
+	printf("   -o: Add <offset> to displayed byte positions.\n");
+	printf("   -s: Seek <seek> bytes into input (with -, seek back from EOF).\n");
+	printf("   -u: Uppercase hex digits (default is lowercase).\n");
+	printf("   -v: Verbose debugging info.\n");
+	printf("With no [file], or -, reads from stdin.\n");
 }
 
 int parse_num_arg(const char *arg) {
@@ -104,8 +128,6 @@ FILE *open_input(const char *file) {
 	return input;
 }
 
-const char *color_off = "\x1b[0m";
-
 char *get_color(unsigned char c) {
 	int color;
 	unsigned char c7 = c & 0x7f;
@@ -143,7 +165,7 @@ char *get_color(unsigned char c) {
 	return outbuf;
 }
 
-/* in GR.1 or GR.2:
+/* displaying ATASCII (not screencodes) in GR.1 or GR.2:
    $00-$1F get displayed in green, as $20-$2F.
    $20-$5F get displayed in orange, as themselves.
    $60-$7F get displayed in green, as $40-$5F.
@@ -300,7 +322,7 @@ int main(int argc, char **argv) {
 			case 'h': print_help(); exit(0); break;
 			case 'i': table = ics2utf; break;
 			case 'm': color = 0; break;
-			case 'u': word_format = "%04X"; byte_format = "%02X"; break;
+			case 'u': word_format = UC_WORD_FMT; byte_format = UC_BYTE_FMT; break;
 			case 's': parse_seek_arg(optarg); break;
 			case 'o': disp_offset = parse_offset_arg(optarg); break;
 			case 'l': limit = parse_limit_arg(optarg); break;
diff --git a/a8xd.rst b/a8xd.rst
index 057ffbe..30d187b 100644
--- a/a8xd.rst
+++ b/a8xd.rst
@@ -42,16 +42,16 @@ OPTIONS
 =======
 
 -a
-  ANTIC mode: treat the input as screen bytes. Can usefully be combined
-  with **-g**.
-
--i
-  Print XL/XE International Character Set conversions instead of ATASCII.
+  ANTIC mode: treat the input as screen bytes (aka "internal codes")
+  rather than ATASCII. Can usefully be combined with **-g**.
 
 -g
   Graphics mode. Changes the colorization so it looks like *GRAPHICS 1* (or 2)
   on the Atari.
 
+-i
+  Print XL/XE International Character Set conversions instead of ATASCII.
+
 -l *len*
   Stop after dumping *len* bytes. *len* may be given in decimal or hex (with
   leading *0x* or *$*).
-- 
cgit v1.2.3