listamsb: update man page (add DIAGNOSTICS section).

1 files changed, 62 insertions, 2 deletions

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