.\" 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 "LISTAMSB" 1 "2025-02-25" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
listamsb \- List the source of a tokenized Atari Microsoft BASIC program
.SH SYNOPSIS
.sp
listamsb [\fB\-a\fP] [\fB\-v\fP] [\fB\-h\fP] [\fB\-i\fP] [\fB\-u\fP] [\fB\-t\fP] [\fB\-m\fP] [\fB\-s\fP] [\fBinput\-file\fP]
.SH DESCRIPTION
.sp
\fBlistamsb\fP acts like the \fILIST\fP command in Atari Microsoft BASIC. It reads a
tokenized (SAVEd) AMSB program and prints the code in human\-readable
format.
.sp
By default, output is piped to \fBa8cat\fP(1), which converts the
ATASCII output to something that\(aqs human\-readable on modern terminals.
This means \fBa8cat\fP must be available somewhere in \fB$PATH\fP\&.
.sp
\fBlistamsb\fP supports both versions of Atari Microsoft BASIC: the
disk\-based version 1 and the cartridge\-based version 2. The language
is the same for both versions, so there\(aqs no need to specify it.
.sp
\fBinput\-file\fP must be a tokenized AMSB program. If no \fBinput\-file\fP is given,
input is read from stdin.
.sp
Output is to stdout. Use shell redirection to save the output to a file.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a\fP
Output raw ATASCII. This option must be used with a pipe or redirection, as
\fBlistamsb\fP will not write ATASCII to a terminal. \fBa8cat\fP is not used,
with this option.
.TP
.B \fB\-c\fP
Check only. No output on stdout. Diagnostics are still printed on stderr,
and the exit status is unchanged.
.TP
.B \fB\-v\fP
Verbose output, on stderr.
.TP
.B \fB\-h\fP
Print built\-in help and exit.
.TP
.B \fB\-i\fP, \fB\-u\fP, \fB\-t\fP, \fB\-m\fP, \fB\-s\fP
These options are passed to \fBa8cat\fP\&. See its man page for details. If
the \fB\-a\fP or \fB\-c\fP option is used, these options have no effect.
.UNINDENT
.SH DIAGNOSTICS
.sp
All error and warning messages are written to the standard error output.
.SS Fatal errors
.sp
These are errors in the program header at the start of the file. They
generally mean the input isn\(aqt actually an tokenized Atari Microsoft
BASIC file.
.INDENT 0.0
.IP \(bu 2
not an AMSB file: first byte not $00
.IP \(bu 2
not an AMSB file: too big (\fIN\fP bytes), won\(aqt fit in Atari memory
.IP \(bu 2
not an AMSB file: program size too small (\fIN\fP). Atari BASIC file?
.UNINDENT
.SS Warnings
.sp
These are non\-fatal: \fBlistamsb\fP logs the warning to stderr, then
continues processing.
.INDENT 0.0
.IP \(bu 2
unexpected EOF, file truncated?
.sp
A tokenized AMSB file always ends with three null bytes (\fI$00\fP).
This file doesn\(aqt. Probably the rest of the file is missing.
.IP \(bu 2
line number out of order
.sp
Probably means the file is corrupted, or isn\(aqt really an AMSB file.
.IP \(bu 2
line number out range
.sp
The program contains a line number that\(aqs greater than \fI63999\fP\&. How
did that happen?
.IP \(bu 2
line \fIN\fP has character \fIC\fP outside of a string, maybe not an AMSB file?
.sp
This happens when ATASCII codes 0 to 31 (\fI$1f\fP) appear in the program.
AMSB can create files like this, but at runtime, it\(aqs a syntax error.
It could also mean it\(aqs not really an AMSB file.
.IP \(bu 2
actual program size doesn\(aqt match program size in header
.sp
Might mean this isn\(aqt an AMSB file. If you\(aqre sure it is, part of the file
might have been overwritten with \fI$00\fP bytes.
.IP \(bu 2
trailing garbage at end of file
.sp
Might mean this isn\(aqt an AMSB file. If you\(aqre sure it is, garbage
data has somehow gotten appended to the file, after the three \fI$00\fP
bytes that end the program. Maybe it was downloaded with a crappy
version of XMODEM that pads the last block.
.IP \(bu 2
file has \fIN\fP unknown tokens
.sp
Either the file is corrupt, or this is a file from some \fIother\fP variant
of Microsoft BASIC (e.g. Commodore, AppleSoft, GW\-BASIC, TRS\-80). If
you see this warning, you\(aqll also see \fIN\fP <unknown token \fIXX\fP>
messages in the actual listing.
.UNINDENT
.SH LIMITATIONS
.sp
Unlike \fBlistbas\fP, there\(aqs no color syntax highlighting. Probably there
never will be.
.sp
It\(aqs hard to reliably detect AMSB files. Most of the time, it can at least
detect Atari BASIC files, but occasionally you\(aqll get gibberish output instead.
.SH EXIT STATUS
.sp
0 for success, 1 if there was an error reading the input (e.g. file
not found), or 2 if the input file had errors or warnings (see
\fBDIAGNOSTICS\fP).
.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),
\fBlistamsb\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.
.