diff options
Diffstat (limited to 'a8xd.1')
| -rw-r--r-- | a8xd.1 | 271 |
1 files changed, 271 insertions, 0 deletions
@@ -0,0 +1,271 @@ +.\" 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 "A8XD" 1 "2024-07-24" "0.2.1" "Urchlay's Atari 8-bit Tools" +.SH NAME +a8xd \- Atari 8-bit ATASCII-aware hex dump +.SH SYNOPSIS +.sp +\fIa8xd\fP [\fB\-i\fP] [\fB\-l\fP \fIlimit\fP] [\fB\-m\fP] [\fB\-o\fP offset] [\fB\-s\fP \fI[\-]seek\fP] [\fB\-u\fP] [\fB\-v\fP] [\fIinfile\fP] +.SH DESCRIPTION +.sp +\fBa8xd\fP is a hex dump utility, similar to \fBxxd\fP(1), but it +understands and prints ATASCII characters rather than ASCII. +.sp +The ATASCII codes are converted to UTF\-8, in the same way as +\fBa8cat\fP(1). Codes with the high bit set are displayed in inverse +video, using ANSI/VT\-100 escape sequences. +.sp +By default, the output is colorized (see \fBCOLORS\fP, below). The +colors and inverse rendering apply to both the ATASCII and hex bytes. +.sp +Without \fIinfile\fP, or if \fIinfile\fP is \fB\-\fP, \fBa8xd\fP reads from standard input. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a +ANTIC mode: treat the input as screen bytes (aka "internal codes") +rather than ATASCII. Can usefully be combined with \fB\-g\fP or \fB\-f\fP\&. +.TP +.B \-f +Like \fB\-g\fP, but using the top half of the character set. This is +what you\(aqd see on the Atari with \fIGRAPHICS 1:POKE 756,226\fP\&. +.TP +.B \-g +Graphics mode. Changes the printed characters and 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 +.B \-l \fIlen\fP +Stop after dumping \fIlen\fP bytes. \fIlen\fP may be given in decimal or hex (with +leading \fI0x\fP or \fI$\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-m +Monochrome mode. Disables color, but ATASCII characters with the high bit +set are still displayed in inverse. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o \fIoffset\fP +Add \fIoffset\fP to displayed file position. \fIoffset\fP can be given in decimal +or hex (with leading \fI0x\fP or \fI$\fP). Negative offsets are allowed, but they +will be printed as very large positive numbers in the output (this matches +\fBxxd\fP\(aqs behaviour). +.TP +.B \-s \fI[\-]seek\fP +Start at \fIseek\fP bytes. Without \fI\-\fP, this is an absolute offset. With \fI\-\fP, +it\(aqs relative to the end of the file. The \fI\-\fP option won\(aqt work when +reading from standard input. \fIseek\fP may be given in decimal or hex +(with leading \fI0x\fP or \fI$\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-u +Use uppercase letters for hex digits; the default is lowercase. +.TP +.B \-v +Verbose. Shows various debug messages that are probably only useful +if you\(aqre hacking on \fBa8xd\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \fB\-\-\fP +End of options; the next argument is the filename. 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 COLORS +.sp +The default color scheme is: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +Non\-control characters are green. This includes alphanumerics, spaces, and +punctuation. These are the characters that ATASCII has in common with +ASCII. +.IP \(bu 2 +Graphics characters are yellow. This includes \fB$01\fP to \fB$1a\fP (the +alphabet, with the Control key held down), \fB$60\fP (the diamond), and +\fB$7b\fP (the spade). +.IP \(bu 2 +Codes \fB$00\fP (null, or ATASCII heart) and \fB$9B\fP (EOL) are red. These +characters are used as delimiters, so it makes sense for them to +stand out. +.IP \(bu 2 +Cursor control characters are purple. These are characters that perform +some action when printed to the \fIE:\fP device. These are: +.INDENT 2.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fB$1b\fP +Escape. +.TP +.B \fB$1c\fP through \fB$1f\fP +Cursor movement (up/down/left/right arrows). +.TP +.B \fB$7d\fP +Clear screen. +.TP +.B \fB$7e\fP +Backspace. +.TP +.B \fB$7f\fP +Tab. +.TP +.B \fB$9c\fP +Delete line. +.TP +.B \fB$9d\fP +Insert line. +.TP +.B \fB$9e\fP +Clear tab stop. +.TP +.B \fB$9f\fP +Set tab stop. +.TP +.B \fB$fd\fP +Bell. +.TP +.B \fB$fe\fP +Delete character. +.TP +.B \fB$ff\fP +Insert character. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +In \fB\-f\fP and \fB\-g\fP modes, the above doesn\(aqt apply. Instead, the +colors are (close to) the colors that would appear in \fIGRAPHICS 1\fP, +with the default palette. +.SH NOTES +.sp +\fBa8xd\fP requires the terminal emulator to support UTF\-8 and use a +font with the necessary glyphs. The author has tested extensively +with \fBurxvt\fP(1) (aka \fBrxvt\-unicode\fP) and \fBxterm\fP(1), using +the \fIDeja Vu Sans Mono\fP, \fIJetBrains Mono\fP, \fILiberation Mono\fP, +and \fISymbola\fP fonts. Also \fBkitty\fP(1), \fBxfce4\-terminal\fP(1), +KDE/Plasma 5\(aqs \fBkonsole\fP(1), \fBgnome\-terminal\fP(1) 3.43.90, and +\fBst\fP(1) from suckless.org have been lightly tested and seem to work +fine. Even the Linux console works, except that you won\(aqt be able to +find a console font with all the necessary glyphs (I may create one +someday). +.sp +\fBa8xd\fP only supports terminals that use ANSI\-style escape sequences +for color and inverse video. This isn\(aqt much of a limitation, since +all modern X, Wayland, Mac, etc terminal emulators have support for +this... but it might annoy you if you\(aqre trying to use an Atari ST +with a VT52 emulator as a serial terminal. Sorry. +.sp +\fBa8xd\fP supports a useful subset of \fBxxd\fP(1) options. The main things +missing are: +.INDENT 0.0 +.IP \(bu 2 +\fB\-r\fP (revert). +.IP \(bu 2 +\fB\-include\fP (output as C include) and all options related to it. +.IP \(bu 2 +\fB\-g\fP (grouping; \fBa8xd\fP always uses a group size of 1 byte). +.IP \(bu 2 +\fB\-E\fP (EBCDIC mode). +.IP \(bu 2 +\fB\-p\fP (PostScript/continuous dump). +.IP \(bu 2 +\fB\-cols\fP (\fBa8xd\fP only supports 16 column dumps). +.IP \(bu 2 +\fB\-b\fP (bits mode). +.IP \(bu 2 +support for files larger than 2GB. This won\(aqt be a problem for Atari 8\-bit\-related files! +.IP \(bu 2 +replacing duplicate lines in the output with \fB*\fP\&. +.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), +\fBbas2aplus\fP(1), +\fBblob2c\fP(1), +\fBblob2xex\fP(1), +\fBcart2xex\fP(1), +\fBcxrefbas\fP(1), +\fBdasm2atasm\fP(1), +\fBdiffbas\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), +\fBfauxtari\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. +. |