unprotbas: document findings about ERROR 4.

3 files changed, 38 insertions, 8 deletions

diff --git a/unprotbas.1 b/unprotbas.1
index b2e44f5..de1f947 100644
--- a/unprotbas.1
+++ b/unprotbas.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "UNPROTBAS" 1 "2024-05-22" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "UNPROTBAS" 1 "2024-05-23" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 unprotbas \- Unprotect LIST-protected Atari 8-bit BASIC programs
 .SH SYNOPSIS
@@ -160,6 +160,10 @@ the rebuilt table will be larger. Other types of scrambling leave
 the variable name table at its original size, but \fBunprotbas\fP
 generates only one\- and two\-character variable names, so the rebuilt
 table might be smaller.
+.sp
+The program \fBPROTECT.BAS\fP, found on Disk 2 of the Holmes Archive,
+creates protected BASIC programs that only use variable name
+scrambling.
 .TP
 .B Bad next\-line pointer
 Every line of tokenized BASIC contains a line length byte, which
@@ -189,6 +193,10 @@ line of tokenized code currently being executed.
 \fBunprotbas\fP fixes this simply by calculating what the pointer
 should be (based on the tokens in the line) and changing it. No
 information is lost by doing this.
+.sp
+The program \fBUNPROTEC\fP, from the \fIPirate\(aqs Treasure Chest\fP, can
+fix bad pointers in protected programs, though it doesn\(aqt do
+anything about variable name scrambling.
 .UNINDENT
 .sp
 One more thing \fBunprotbas\fP can do is remove extra data from the end
@@ -263,9 +271,16 @@ This process can also be used for regular unprotected programs. Use
 .SH NOTES
 .sp
 Atari BASIC has a limit of 128 variables in a program. It\(aqs actually
-possible for the variable name table (and the variable value table)
-to contain 129 variables, though the last one won\(aqt be usable in the
-program.
+possible for the variable name table to contain up to 256 variables,
+though the 129th and further ones won\(aqt be usable in the program. The
+variable value table can hold more than 256 values, though the
+variable numbers wrap around once they pass 255. The attempt to add
+variables past the 128th causes BASIC to respond with \fIERROR\- 4\fP, but
+the variable does get added to the tables. \fBunprotbas\fP will preserve
+these extra (useless) entries in the tables, though it will complain
+"Warning: variable #XXX value is corrupt" for value table entries
+256 and up. This is a pathological case, and shouldn\(aqt happen with
+programs that aren\(aqt deliberately written to test this behaviour.
 .SH COPYRIGHT
 .sp
 WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
diff --git a/unprotbas.c b/unprotbas.c
index 5748461..a3ae9cf 100644
--- a/unprotbas.c
+++ b/unprotbas.c
@@ -30,7 +30,7 @@ unsigned char data[65536];
 
 /* for the -r option */
 unsigned char varnames[65536];
-unsigned char *varmap[129];
+unsigned char *varmap[256];
 int varmap_count;
 
 /* BASIC 14-byte header values */
diff --git a/unprotbas.rst b/unprotbas.rst
index 6ba560c..cd55dd8 100644
--- a/unprotbas.rst
+++ b/unprotbas.rst
@@ -135,6 +135,10 @@ Variable name table scrambling
   generates only one- and two-character variable names, so the rebuilt
   table might be smaller.
 
+  The program **PROTECT.BAS**, found on Disk 2 of the Holmes Archive,
+  creates protected BASIC programs that only use variable name
+  scrambling.
+
 Bad next-line pointer
   Every line of tokenized BASIC contains a line length byte, which
   BASIC uses as a pointer to the next line of code. Before printing
@@ -164,6 +168,10 @@ Bad next-line pointer
   should be (based on the tokens in the line) and changing it. No
   information is lost by doing this.
 
+  The program **UNPROTEC**, from the *Pirate's Treasure Chest*, can
+  fix bad pointers in protected programs, though it doesn't do
+  anything about variable name scrambling.
+
 One more thing **unprotbas** can do is remove extra data from the end
 of the file. It's possible for BASIC files to contain extra data that
 occurs after the end of the program. Some programs use this as a way
@@ -231,8 +239,15 @@ NOTES
 =====
 
 Atari BASIC has a limit of 128 variables in a program. It's actually
-possible for the variable name table (and the variable value table)
-to contain 129 variables, though the last one won't be usable in the
-program.
+possible for the variable name table to contain up to 256 variables,
+though the 129th and further ones won't be usable in the program. The
+variable value table can hold more than 256 values, though the
+variable numbers wrap around once they pass 255. The attempt to add
+variables past the 128th causes BASIC to respond with *ERROR- 4*, but
+the variable does get added to the tables. **unprotbas** will preserve
+these extra (useless) entries in the tables, though it will complain
+"Warning: variable #XXX value is corrupt" for value table entries
+256 and up. This is a pathological case, and shouldn't happen with
+programs that aren't deliberately written to test this behaviour.
 
 .. include:: manftr.rst