unprotbas: implement -r option (needs more testing though).

1 files changed, 58 insertions, 2 deletions

diff --git a/unprotbas.1 b/unprotbas.1
index 2b389ac..992bd28 100644
--- a/unprotbas.1
+++ b/unprotbas.1
@@ -27,12 +27,12 @@ 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-19" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "UNPROTBAS" 1 "2024-05-22" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 unprotbas \- Unprotect LIST-protected Atari 8-bit BASIC programs
 .SH SYNOPSIS
 .sp
-unprotbas [\fB\-v\fP] [\fB\-f\fP] [\fB\-n\fP] [\fB\-g\fP] [\fB\-c\fP] \fBinput\-file\fP \fBoutput\-file\fP
+unprotbas [\fB\-v\fP] [\fB\-f\fP] [\fB\-n\fP] [\fB\-g\fP] [\fB\-c\fP] [\fB\-r\fP | \fB\-w\fP] \fBinput\-file\fP \fBoutput\-file\fP
 .SH DESCRIPTION
 .sp
 \fBunprotbas\fP modifies a LIST\-protected Atari 8\-bit BASIC program,
@@ -73,6 +73,17 @@ it\(aqs left as\-is, in case it\(aqs actually data used by the program.
 Check only. Does a dry run. Loads the program, unprotects it in
 memory, but doesn\(aqt write the result anywhere. In this mode, there
 is no \fBoutput\-file\fP\&.
+.TP
+.B \fB\-w\fP
+Write the variable names to \fBvarnames.txt\fP, one per line.
+This can be edited, and later used with \fB\-r\fP to set the variable names
+to something sensible rather than A, B, C, etc. For an unprotected
+program, you can use \fB\-n\fP to write the existing names rather than
+generating new ones. See \fBVARIABLE NAMES\fP, below.
+.TP
+.B \fB\-r\fP
+Read variable names from \fBvarnames.txt\fP, and use them instead of
+generating the names. See \fBVARIABLE NAMES\fP, below.
 .UNINDENT
 .SH EXIT STATUS
 .INDENT 0.0
@@ -193,6 +204,51 @@ it normally does... if you suspect it\(aqs causing a problem, you can
 remove it with the \fB\-g\fP option. If removing the "garbage" causes the
 program to fail to run, it wasn\(aqt garbage! \fBunprotbas\fP doesn\(aqt
 remove extra data by default, to be on the safe side.
+.SH VARIABLE NAMES
+.sp
+If variable name scrambling was used, the original variable names no
+longer exist. \fBunprotbas\fP will generate them, according to these rules:
+.INDENT 0.0
+.INDENT 3.5
+The first 26 numeric variables will be called \fIA\fP through \fIZ\fP\&. Further
+numeric variables will be \fIA1\fP through \fIA9\fP, \fIB1\fP through \fIB9\fP, etc.
+.sp
+The first 26 string variables will be \fIA$\fP to \fIZ$\fP, then \fIA1$\fP to
+\fIA9$\fP, \fIB1$\fP to \fIB9$\fP, etc.
+.sp
+The first 26 array variables will be \fIA(\fP to \fIZ(\fP, then \fIA1(\fP to
+\fIA9(\fP, \fIB1(\fP to \fIB9(\fP, etc.
+.UNINDENT
+.UNINDENT
+.sp
+To properly reverse\-engineer the protected program, it\(aqs necessary to assign
+meaningful variable names. \fBunprotbas\fP isn\(aqt smart enough to do this for you,
+but it can semi\-automate the process.
+.sp
+First, run \fBunprotbas\fP with the \fB\-w\fP option. This will create a
+file called \fBvarnames.txt\fP, containing the generated variable names.
+These are in order, one line per variable name, ending with \fI$\fP for strings
+and the \fI(\fP for arrays.
+.sp
+Load the unprotected program on the Atari and LIST it (or use \fBchkbas\fP to get a
+listing), and edit \fBvarnames.txt\fP in a text editor.
+.sp
+As you figure out what each variable\(aqs purpose is, change its name
+in the text file. Don\(aqt delete any lines from the file, and don\(aqt
+add any. Don\(aqt get rid of the \fI$\fP or \fI(\fP at the end of any line. You
+may enter the names in lowercase (\fBunprotbas\fP 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
+\fIFOO\fP and \fIFOO$\fP, but not two numerics called \fIFOO\fP).
+.sp
+When you\(aqre finished, re\-run \fBunprotbas\fP, this time with the \fB\-r\fP
+option. The unprotected program will use your variable names, rather
+than generating new ones.
+.sp
+This process can also be used for regular unprotected programs. Use
+\fB\-n \-w\fP the first time, to save the existing variable names to
+\fBvarnames.txt\fP rather than generating new ones.
 .SH COPYRIGHT
 .sp
 WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.