listamsb: update man page (add DIAGNOSTICS section).

2 files changed, 124 insertions, 4 deletions

diff --git a/listamsb.1 b/listamsb.1
index 37ece05..5b4fa65 100644
--- a/listamsb.1
+++ b/listamsb.1
@@ -74,13 +74,73 @@ 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. If you feed \fBlistamsb\fP an
-Atari BASIC file, you\(aqll get gibberish output.
+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
diff --git a/listamsb.rst b/listamsb.rst
index af72e73..c04c638 100644
--- a/listamsb.rst
+++ b/listamsb.rst
@@ -58,14 +58,74 @@ OPTIONS
 DIAGNOSTICS
 ===========
 
+All error and warning messages are written to the standard error output.
+
+Fatal errors
+------------
+
+These are errors in the program header at the start of the file. They
+generally mean the input isn't actually an tokenized Atari Microsoft
+BASIC file.
+
+- not an AMSB file: first byte not $00
+
+- not an AMSB file: too big (*N* bytes), won't fit in Atari memory
+
+- not an AMSB file: program size too small (*N*). Atari BASIC file?
+
+Warnings
+--------
+
+These are non-fatal: **listamsb** logs the warning to stderr, then
+continues processing.
+
+- unexpected EOF, file truncated?
+
+  A tokenized AMSB file always ends with three null bytes (*$00*\).
+  This file doesn't. Probably the rest of the file is missing.
+
+- line number out of order
+
+  Probably means the file is corrupted, or isn't really an AMSB file.
+
+- line number out range
+
+  The program contains a line number that's greater than *63999*. How
+  did that happen?
+
+- line *N* has character *C* outside of a string, maybe not an AMSB file?
+
+  This happens when ATASCII codes 0 to 31 (*$1f*\) appear in the program.
+  AMSB can create files like this, but at runtime, it's a syntax error.
+  It could also mean it's not really an AMSB file.
+
+- actual program size doesn't match program size in header
+
+  Might mean this isn't an AMSB file. If you're sure it is, part of the file
+  might have been overwritten with *$00* bytes.
+
+- trailing garbage at end of file
+
+  Might mean this isn't an AMSB file. If you're sure it is, garbage
+  data has somehow gotten appended to the file, after the three *$00*
+  bytes that end the program. Maybe it was downloaded with a crappy
+  version of XMODEM that pads the last block.
+
+- file has *N* unknown tokens
+
+  Either the file is corrupt, or this is a file from some *other* variant
+  of Microsoft BASIC (e.g. Commodore, AppleSoft, GW-BASIC, TRS-80). If
+  you see this warning, you'll also see *N* <unknown token *XX*>
+  messages in the actual listing.
+
 LIMITATIONS
 ===========
 
 Unlike **listbas**, there's no color syntax highlighting. Probably there
 never will be.
 
-It's hard to reliably detect AMSB files. If you feed **listamsb** an
-Atari BASIC file, you'll get gibberish output.
+It's hard to reliably detect AMSB files. Most of the time, it can at least
+detect Atari BASIC files, but occasionally you'll get gibberish output instead.
 
 EXIT STATUS
 ===========