1 files changed, 187 insertions, 0 deletions
diff --git a/a8xd.rst b/a8xd.rst
new file mode 100644
index 0000000..3dc2b07
--- /dev/null
+++ b/a8xd.rst
@@ -0,0 +1,187 @@
+====
+a8xd
+====
+
+----------------------------------
+Atari 8-bit ATASCII-aware hex dump
+----------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+*a8xd* [**-i**] [**-l** *limit*] [**-m**] [**-o** offset] [**-s** *[-]seek*] [**-u**] [**-v**] [*infile*]
+
+DESCRIPTION
+===========
+
+**a8xd** is a hex dump utility, similar to **xxd**\(1), but it
+understands and prints ATASCII characters rather than ASCII.
+
+The ATASCII codes are converted to UTF-8, in the same way as
+**a8cat**\(1). Codes with the high bit set are displayed in inverse
+video, using ANSI/VT-100 escape sequences.
+
+By default, the output is colorized (see **COLORS**, below). The
+colors and inverse rendering apply to both the ATASCII and hex bytes.
+
+Without *infile*, or if *infile* is **-**, **a8xd** reads from standard input.
+
+OPTIONS
+=======
+
+-a
+  ANTIC mode: treat the input as screen bytes (aka "internal codes")
+  rather than ATASCII. Can usefully be combined with **-g** or **-f**.
+
+-f
+  Like **-g**, but using the top half of the character set. This is
+  what you'd see on the Atari with *GRAPHICS 1:POKE 756,226*.
+
+-g
+  Graphics mode. Changes the printed characters and 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 *$*).
+
+-m
+  Monochrome mode. Disables color, but ATASCII characters with the high bit
+  set are still displayed in inverse.
+
+-o *offset*
+  Add *offset* to displayed file position. *offset* can be given in decimal
+  or hex (with leading *0x* or *$*). Negative offsets are allowed, but they
+  will be printed as very large positive numbers in the output (this matches
+  **xxd**\'s behaviour).
+
+-s *[-]seek*
+  Start at *seek* bytes. Without *-*, this is an absolute offset. With *-*,
+  it's relative to the end of the file. The *-* option won't work when
+  reading from standard input. *seek* may be given in decimal or hex
+  (with leading *0x* or *$*).
+
+-u
+  Use uppercase letters for hex digits; the default is lowercase.
+
+-v
+  Verbose. Shows various debug messages that are probably only useful
+  if you're hacking on **a8xd**.
+
+**--**
+  End of options; the next argument is the filename. Use this if you're
+  trying to work with files whose names begin with *-*.
+
+**-h**, **--help**
+  Show built-in help and exit.
+
+**--version**
+  Show version number and exit.
+
+COLORS
+======
+
+The default color scheme is:
+
+  - Non-control characters are green. This includes alphanumerics, spaces, and
+    punctuation. These are the characters that ATASCII has in common with
+    ASCII.
+
+  - Graphics characters are yellow. This includes **$01** to **$1a** (the
+    alphabet, with the Control key held down), **$60** (the diamond), and
+    **$7b** (the spade).
+
+  - Codes **$00** (null, or ATASCII heart) and **$9B** (EOL) are red. These
+    characters are used as delimiters, so it makes sense for them to
+    stand out.
+
+  - Cursor control characters are purple. These are characters that perform
+    some action when printed to the *E:* device. These are:
+
+      **$1b**
+        Escape.
+
+      **$1c** through **$1f**
+        Cursor movement (up/down/left/right arrows).
+
+      **$7d**
+        Clear screen.
+
+      **$7e**
+        Backspace.
+
+      **$7f**
+        Tab.
+
+      **$9c**
+        Delete line.
+
+      **$9d**
+        Insert line.
+
+      **$9e**
+        Clear tab stop.
+
+      **$9f**
+        Set tab stop.
+
+      **$fd**
+        Bell.
+
+      **$fe**
+        Delete character.
+
+      **$ff**
+        Insert character.
+
+In **-f** and **-g** modes, the above doesn't apply. Instead, the
+colors are (close to) the colors that would appear in *GRAPHICS 1*,
+with the default palette.
+
+NOTES
+=====
+
+**a8xd** requires the terminal emulator to support UTF-8 and use a
+font with the necessary glyphs. The author has tested extensively
+with **urxvt**\(1) (aka **rxvt-unicode**) and **xterm**\(1), using
+the *Deja Vu Sans Mono*, *JetBrains Mono*, *Liberation Mono*,
+and *Symbola* fonts. Also **kitty**\(1), **xfce4-terminal**\(1),
+KDE/Plasma 5's **konsole**\(1), **gnome-terminal**\(1) 3.43.90, and
+**st**\(1) from suckless.org have been lightly tested and seem to work
+fine. Even the Linux console works, except that you won't be able to
+find a console font with all the necessary glyphs (I may create one
+someday).
+
+**a8xd** only supports terminals that use ANSI-style escape sequences
+for color and inverse video. This isn't much of a limitation, since
+all modern X, Wayland, Mac, etc terminal emulators have support for
+this... but it might annoy you if you're trying to use an Atari ST
+with a VT52 emulator as a serial terminal. Sorry.
+
+**a8xd** supports a useful subset of **xxd**\(1) options. The main things
+missing are:
+
+- **-r** (revert).
+
+- **-include** (output as C include) and all options related to it.
+
+- **-g** (grouping; **a8xd** always uses a group size of 1 byte).
+
+- **-E** (EBCDIC mode).
+
+- **-p** (PostScript/continuous dump).
+
+- **-cols** (**a8xd** only supports 16 column dumps).
+
+- **-b** (bits mode).
+
+- support for files larger than 2GB. This won't be a problem for Atari 8-bit-related files!
+
+- replacing duplicate lines in the output with **\***.
+
+.. include:: manftr.rst