====
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