whichbas: tweak doc.

2 files changed, 50 insertions, 19 deletions

diff --git a/whichbas.1 b/whichbas.1
index 7f422c3..1c97a73 100644
--- a/whichbas.1
+++ b/whichbas.1
@@ -94,21 +94,37 @@ Detection of Turbo vs. BXL/BXE isn\(aqt 100% reliable, and probably
 never will be. There\(aqs too much overlap between the sets of extra
 tokens added by each. Programs that don\(aqt use very many of the extra
 functions provided by Turbo/BXL/BXE may show up as "Either Turbo BASIC XL
-or OSS BASIC XE".
+or OSS BASIC XL".
 .sp
-Atari Microsoft BASIC is detected by checking that the first two
-bytes of the file are not zero, and that the last 3 are zero. This
-may result in false positives (files that aren\(aqt BASIC programs at
+Atari Microsoft BASIC is detected by checking that:
+.INDENT 0.0
+.IP \(bu 2
+the first byte of the file \fB$00\fP\&.
+.IP \(bu 2
+the next 2 bytes (LSB/MSB) are the same as the actual file length minus 3.
+.IP \(bu 2
+the last 3 bytes of the file are zero.
+.UNINDENT
+.sp
+This may result in false positives (files that aren\(aqt BASIC programs at
 all might show up as Microsoft). Also, no distinction is made between
 Atari MS BASIC 1.0 and 2.0.
 .sp
+OSS BASIC/A+ is an extended form of Atari BASIC. It\(aqs source
+compatible with Atari BASIC, but not token\-compatible because it uses
+different token numbers for the regular BASIC commands and operators.
+Example: SAVE is token \fB$19\fP in Atari BASIC (also Turbo/BXL/BXE),
+but in A+ it\(aqs token \fB$1D\fP\&. Detection should be 100% reliable, but
+since there aren\(aqt many BASIC/A+ programs in the wild, it hasn\(aqt been
+thoroughly tested.
+.sp
 Various non\-BASIC files are detected (including Mac/65 source,
 ELF binaries, etc) as a convenience, but I wouldn\(aqt rely on
 \fBwhichbas\fP\(aqs non\-BASIC file type detection if I were you.
-.SH LIMITATIONS
+If you need the \fBfile\fP(1) command, use it.
 .sp
 \fBwhichbas\fP knows nothing about other BASICs such as Frost BASIC,
-BASIC/A+, Altirra BASIC...
+or Altirra BASIC.
 .SH BUGS
 .sp
 It\(aqs possible to get a BASIC XL/XE program to misdetect as Atari BASIC
@@ -117,9 +133,9 @@ by writing a program that does these things:
 .INDENT 3.5
 .INDENT 0.0
 .IP \(bu 2
-Dimensions a string array with a number of elements that isn\(aqt just a
+Dimension a string array with a number of elements that isn\(aqt just a
 numeric constant or numeric variable (e.g. \fIDIM A$(2+2,10)\fP or
-\fIDIM A$(I*2,10)\fP). The code that detects a 2D string \fIDIM\fP command
+\fIDIM A$(I*2,10)\fP). The code that detects a string array \fIDIM\fP command
 can only handle simple cases like \fIDIM A$(10,10)\fP or \fIDIM A$(I,10)\fP\&.
 It doesn\(aqt actually matter if the 2nd argument is a fancy expression,
 though.
@@ -137,7 +153,8 @@ runtime.
 .UNINDENT
 .sp
 The good news is, such a program will still work fine in Atari BASIC.
-Believe it or not, it\(aqs true.
+Atari BASIC will dimension it as a regular string variable and ignore
+the 2nd dimension.
 .SH EXIT STATUS
 .sp
 Without the \fB\-s\fP option, exit status is 0 for success, non\-zero for
diff --git a/whichbas.rst b/whichbas.rst
index 497b0ff..b4150e1 100644
--- a/whichbas.rst
+++ b/whichbas.rst
@@ -65,31 +65,44 @@ Detection of Turbo vs. BXL/BXE isn't 100% reliable, and probably
 never will be. There's too much overlap between the sets of extra
 tokens added by each. Programs that don't use very many of the extra
 functions provided by Turbo/BXL/BXE may show up as "Either Turbo BASIC XL
-or OSS BASIC XE".
+or OSS BASIC XL".
 
-Atari Microsoft BASIC is detected by checking that the first two
-bytes of the file are not zero, and that the last 3 are zero. This
-may result in false positives (files that aren't BASIC programs at
+Atari Microsoft BASIC is detected by checking that:
+
+- the first byte of the file **$00**\.
+
+- the next 2 bytes (LSB/MSB) are the same as the actual file length minus 3.
+
+- the last 3 bytes of the file are zero.
+
+This may result in false positives (files that aren't BASIC programs at
 all might show up as Microsoft). Also, no distinction is made between
 Atari MS BASIC 1.0 and 2.0.
 
+OSS BASIC/A+ is an extended form of Atari BASIC. It's source
+compatible with Atari BASIC, but not token-compatible because it uses
+different token numbers for the regular BASIC commands and operators.
+Example: SAVE is token **$19** in Atari BASIC (also Turbo/BXL/BXE),
+but in A+ it's token **$1D**. Detection should be 100% reliable, but
+since there aren't many BASIC/A+ programs in the wild, it hasn't been
+thoroughly tested.
+
 Various non-BASIC files are detected (including Mac/65 source,
 ELF binaries, etc) as a convenience, but I wouldn't rely on
 **whichbas**\'s non-BASIC file type detection if I were you.
+If you need the **file**\(1) command, use it.
 
-LIMITATIONS
-===========
 **whichbas** knows nothing about other BASICs such as Frost BASIC,
-BASIC/A+, Altirra BASIC...
+or Altirra BASIC.
 
 BUGS
 ====
 It's possible to get a BASIC XL/XE program to misdetect as Atari BASIC
 by writing a program that does these things:
 
-  - Dimensions a string array with a number of elements that isn't just a
+  - Dimension a string array with a number of elements that isn't just a
     numeric constant or numeric variable (e.g. *DIM A$(2+2,10)* or
-    *DIM A$(I*2,10)*). The code that detects a 2D string *DIM* command
+    *DIM A$(I*2,10)*). The code that detects a string array *DIM* command
     can only handle simple cases like *DIM A$(10,10)* or *DIM A$(I,10)*.
     It doesn't actually matter if the 2nd argument is a fancy expression,
     though.
@@ -104,7 +117,8 @@ by writing a program that does these things:
     runtime.
 
 The good news is, such a program will still work fine in Atari BASIC.
-Believe it or not, it's true.
+Atari BASIC will dimension it as a regular string variable and ignore
+the 2nd dimension.
 
 EXIT STATUS
 ===========