From a1144de8efebc414c33a0df9b8fccd758a242586 Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Wed, 22 May 2024 05:24:11 -0400
Subject: unprotbas: implement -r option (needs more testing though).

---
 unprotbas.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

(limited to 'unprotbas.rst')

diff --git a/unprotbas.rst b/unprotbas.rst
index 28ccd8b..752acd7 100644
--- a/unprotbas.rst
+++ b/unprotbas.rst
@@ -11,7 +11,7 @@ Unprotect LIST-protected Atari 8-bit BASIC programs
 SYNOPSIS
 ========
 
-unprotbas [**-v**] [**-f**] [**-n**] [**-g**] [**-c**] **input-file** **output-file**
+unprotbas [**-v**] [**-f**] [**-n**] [**-g**] [**-c**] [**-r** | **-w**] **input-file** **output-file**
 
 DESCRIPTION
 ===========
@@ -56,6 +56,17 @@ will be treated as options.
   memory, but doesn't write the result anywhere. In this mode, there
   is no **output-file**.
 
+**-w**
+  Write the variable names to **varnames.txt**, one per line.
+  This can be edited, and later used with **-r** to set the variable names
+  to something sensible rather than A, B, C, etc. For an unprotected
+  program, you can use **-n** to write the existing names rather than
+  generating new ones. See **VARIABLE NAMES**, below.
+
+**-r**
+  Read variable names from **varnames.txt**, and use them instead of
+  generating the names. See **VARIABLE NAMES**, below.
+
 EXIT STATUS
 ===========
 
@@ -167,4 +178,48 @@ remove it with the **-g** option. If removing the "garbage" causes the
 program to fail to run, it wasn't garbage! **unprotbas** doesn't
 remove extra data by default, to be on the safe side.
 
+VARIABLE NAMES
+==============
+
+If variable name scrambling was used, the original variable names no
+longer exist. **unprotbas** will generate them, according to these rules:
+
+  The first 26 numeric variables will be called *A* through *Z*. Further
+  numeric variables will be *A1* through *A9*, *B1* through *B9*, etc.
+
+  The first 26 string variables will be *A$* to *Z$*, then *A1$* to
+  *A9$*, *B1$* to *B9$*, etc.
+
+  The first 26 array variables will be *A(* to *Z(*, then *A1(* to
+  *A9(*, *B1(* to *B9(*, etc.
+
+To properly reverse-engineer the protected program, it's necessary to assign
+meaningful variable names. **unprotbas** isn't smart enough to do this for you,
+but it can semi-automate the process.
+
+First, run **unprotbas** with the **-w** option. This will create a
+file called **varnames.txt**, containing the generated variable names.
+These are in order, one line per variable name, ending with *$* for strings
+and the *(* for arrays.
+
+Load the unprotected program on the Atari and LIST it (or use **chkbas** to get a
+listing), and edit **varnames.txt** in a text editor.
+
+As you figure out what each variable's purpose is, change its name
+in the text file. Don't delete any lines from the file, and don't
+add any. Don't get rid of the *$* or *(* at the end of any line. You
+may enter the names in lowercase (**unprotbas** will convert them to
+uppercase). Remember to follow the rules for BASIC variable names:
+only letters and numbers allowed, and the first character must be
+a letter. No duplicates of the same type are allowed (you can have
+*FOO* and *FOO$*, but not two numerics called *FOO*).
+
+When you're finished, re-run **unprotbas**, this time with the **-r**
+option. The unprotected program will use your variable names, rather
+than generating new ones.
+
+This process can also be used for regular unprotected programs. Use
+**-n -w** the first time, to save the existing variable names to
+**varnames.txt** rather than generating new ones.
+
 .. include:: manftr.rst
-- 
cgit v1.2.3