Category : BBS Programs+Doors
Archive   : TONSMOD.ZIP
Filename : ASR.DOC

----------------------------------------------------------------
ASR version 1.50
May/June, 1992
Written by Preston Brown
#3 @9987 WWIVnet, #2 @9191 VirtualNET
----------------------------------------------------------------

I. What is DGROUP, and ESM?

ASR stands for AUTOMATIC STRINGS REMOVER. It was developed
over a period of time to deal with a problem that surfaced in WWIV
4.11/4.12, and is still a threat in WWIV 4.20/4.21. That problem is
the infamous DGROUP compile error. DGROUP is the program segment that
contains the text, or "strings" for the program, as well as a few
other things that don't amount to very much memory at all. Because
WWIV's memory model allows only 64 kilobytes of DGROUP space, if
you start modifying your WWIV source code a lot, you will eventually
have too many strings in the source, and you will run into the
DGROUP compile error in the linking process.
To many people, this was a stone wall. Various simplistic
modifications had been released on modnet to deal with this
problem, but all of them were just that: simplistic. They did not
do a good job, and even with them installed, the DGROUP error came
back after only a few more modifications. Thus, most people were
forced to stop modifying their code, or they were forced to cut out
some of their larger (and favorite) mods, like a non-external
casino or fancy file listing system.
Then along came Tolkien with his program, External Strings
Manager, or ESM. To many WWIV modifiers, this program was a
literal lifesaver. The small modification and the accompanying
executable file enabled you to place strings into an external file,
from where they were called by the modified source code. This
program is EXCELLENT, and though I have only used through version
1.04, I know that there are more current versions available (for a
registration fee). They have features such as ASR, and I feel they
have more features than are needed for our purposes, but feel free to
obtain them. I believe that they cost in the neighborhood of $20.00
or so.
ESM was excellent, but there was still one small problem
facing many modifiers: it took way too much time to remove the
strings. The summer of 1991 I can remember printing out each
individual source code file, marking a string number next to each
string, and then loading up the ESM editor to key them in. Then I
would have to go back into the code, remove the string, and replace
it with a call to "get_string(xxx)" which was the procedure that
looked in the strings file for string "xxx" and read it in. For
100 strings, this could take at least 2 hours, if I remember
correctly. However long it took was too long. I only did it
because I had to do it to keep modifying! Later, ver. 1.04 of ESM
added the capability for the ESM editor to read in a text file with
a string on each line, and this sped up things considerably, but
the process was still very slow.
Then WWIV 4.20 came out, and everyone kind of forgot about the
DGROUP compile error if they switched to that version. Wayne Bell
(author of WWIV) had made some good steps in his new version, one
of them being adding about 4 or so extra kilobytes of room to the
DGROUP area by optimizing his code more efficiently. However, I
know from experience that the DGROUP threat is still real, because
on my own WWIV BBS, we hit it again several months ago.
Recently, a mod claiming to give WWIV 4.20 1 meg of DGROUP space
has been released. This modification is buggy at best, and dangerous
at worst. It requires a lot of modification to very sensitive
areas of the source code that Wayne may change in his future versions
of WWIV, which he might release more of now that he has a program
that makes all updates a modification. Also, the 1 meg DGROUP mod
is a very difficult mod, and it does not give you the control over
strings that ESM does. When wayne himself does some sort of mod like
this, we can forget about ASR and ESM, but that's just it: HE HASN'T.
So what was I going to do this time? Do what I did last
summer? No, No, NO WAY. I was not going to waste so much time
doing such the paltry task of string removal again. There had to
be a better way to get around this unfortunate thing. And there is.

II. How do I use ASR?

Enter ASR. The Automatic Strings Remover works by actually
removing the strings from the source code FOR YOU!! The most
common string output routines in the WWIV source code for WWIV
4.12+ are "outstr", "pl", and "prt", "sysoplog", "pla", and "onek".
These are the ones that ESM handles most efficiently and easily, so
these are the ones that ASR can remove. ASR reads in a WWIV source
code C++ file, and then it removes all the strings to an external
strings text file for you. It replaces the string in the source
code file with a call to the appropriate string in the text file,
all automatically!
Before you do anything, you MUST install ESM version 1.04 or
later. ASR is not a stand-alone program: it requires ESM to do
anything useful! You can probably get ESM from any local Bulletin
board in your area that supports WWIV, or if you can't find it, you
may call my Bulletin Board, Silicon Valley, or Tolkien's board, The
Fellowship. My number and network addresses are listed at the end
of the documentation, and his are in the network BBS lists. After
you have installed ESM, and your source code is compiling correctly
with the ESM modification, you are ready to start "de-stringing"
your source code, and ELIMINATING DGROUP!
ASR is disgustingly simple. From the DOS command line, simply
type ASR, the name of the source code file to be "de-stringed", and
then the name of the file for the strings to go to.

e.g. "ASR NEWUSER.C STRINGS.TXT"

This will remove all the strings of the types mentioned at the
beginning of the documentation from NEWUSER.C to a ESM text file
called STRINGS.TXT. With the new version, wildcard C++ filenames
are fully supported! Since ESM only uses STRINGS.TXT as the file
that it can read in and convert to STRINGS.DAT, this will be the
usual name. However, if you are only experimenting, or for any
reason you do not want the strings to go to a STRINGS.TXT file, you
of course could type some other name. Just remember that ESM will
not recognize the file until it has been renamed to STRINGS.TXT, or you
have tinkered with the ESM source code modification. I believe that
a version of the modification in Tolkien's ENHANCE.C package does have
multiple STRINGS.DAT file capability, check into it.
ASR is smart. If you have used ASR on previous files, or
you have been manually writing strings to a STRINGS.TXT file, you
can easily put this as the strings file when you start ASR and it
will tack new strings onto the end of the file with no problem!
After using ASR, make sure that the STRINGS.TXT file is in the
same directory as ESM.EXE, and start up ESM. Use the option in ESM
called "read in STRINGS.TXT" or something akin to that. It should
not be hard to find. ESM will start working, and it will count
through the strings that it is processing. When it is done, a new
file called STRINGS.DAT will be created in the current directory.
Read up in the ESM documentation on what to do with this file. Now
you are ready to do some more mods, or even "de-string" some more
WWIV source code files with ASR/ESM!

III. Configuring ASR

Configuring ASR couldn't be simpler, because in version 1.50 I
have added a really great full screen configuration. The options are
simple: Backups, prompting, comments, slash checking, and escape conversion.
I will discuss each in some detail. To toggle an option (from disabled
to enabled) all you have to do is press SPACEBAR. To move to the next
option, simply press TAB. To save the current configuration at any time,
just press F10. It's that simple!
Backups do just that: If backups are enabled, the C++ files that
you are working with, as well as the string file you are working with
are backed up. The same filename is used, but the extension becomes
".BAK". Any previous ".BAK" files by the same name are overwritten. This
option provides minor protection from weird source files, or whatever, but
do not rely on it solely to get you out of trouble. Always make frequent
backups of your source files, either by yourself or with my utility,
WWIV Backup.
Prompting - With this option on, ASR will prompt you for each string
that it encounters and wishes to remove. You can either choose YES or NO,
and ASR will skip those that you say NO to. This is useful for weeding
out strings that are kind of pointless to take out, such as those that
are only a few characters long ("NN:" or even ":"). This obviously is
not as quick as letting ASR take EVERYTHING out that looks ok, but it
does allow you to be much more selective of what happens to your source
files.
Comments - With this option enabled, when a string is removed, it
will be placed in a set of comments after the call to the string.
Example: If we had the string

pl("Happy Birthday!")

then after it was removed it would look something like this:

pl(get_string(101)); /*Happy Birthday!*/

if comments are off, then you cut down a *little* on the size of your
files, but you also lose the ability to quickly see what the string
that is being called actually is. It is my suggestion to leave this on.
Slash Checking and Escape Conversion - These options are a bit more
complex, and unless you know what you are doing I suggest that you leave
them in their default configuration - ENABLED. I thought seriously about
not even making these options at all, but I thought that experienced users
would benefit from being able to change them. If slash checking is
enabled, the all strings with special codes in them that the compiler
interprets are ignored, e.g. not removed. Such an example is this:

pl("Dumb String!\r\n");

What this will do is write out "Dumb String!" and then do a carriage
return. However, ESM has no idea of how to deal with this. So, in a
sense, you could leave slash checking off, remove the string, go in and
edit out the "\r\n", and then also add a "nl();" right after it to do
a carriage return. This is fine. But if you don't know what you are
doing, then go ahead and leave this option ENABLED. Escape Conversion
is a little different: this code "\x1b" is a code that the compiler
interprets as the escape character, ASCII 27. This is the way that
WWIV does all of its colors and screen movements. If you leave this on,
then "\x1b" codes are converted to ASCII 27 and then written to the
strings file. ESM can understand these just fine. If for some reason
you don't want to remove strings with "hard coded" compiler codes, then
simply turn this option off. Then it will skip over them like all the
other compiler slash codes.

IV. How fast is ASR, and is there anything I need to worry about?
a. ASR is FAST. I removed all the strings from a heavily
modified NEWUSER.C source code file (70+ strings) in under half a
minute. Before ASR, that would have taken several hours, with
commenting and all the like.
b. ASR is SAFE. However, there are a few things that you
should know about how ASR works. ASR looks through your source
code files, and looks for calls to simple strings with no variables.
These are the straightforward, everyday string calls. ASR will not
mess with other types of string calls, such as ones that contain
variables ("%s" and the like) in the string, because ESM cannot
handle such strings. If it finds such a string, it first makes
sure that it has already been converted to a call to "get_string"
or not. Here comes my warning: DO NOT, I repeat DO NOT run ASR on
a source code file with invalid code in it. Make sure that the
code compiles before running it through ASR. This is because if
you have something like this:

pl("this is a string where I forgot to put on the end quote.);

ASR will keep going until it finds a closing quote. This code
will not compile without an error, and therefore you don't really
have to worry about that ever happening. If you did run it through
ASR, you would probably end up with some very strange strings being
removed!

No program is perfect. I have tested ASR on all the WWIV
source files and it WORKS. however, I cannot foresee all the mods
that you or others may stick into the code. Therefore, unless you
are absolutely sure that everything will be easy for ASR to
interpret, turn on backups, or make your own.

DISCLAIMER: I hold no responsibility if ASR trashes your
files and you didn't make backups because you were
just plain STUPID.

V. How is ASR distributed, supported, and is it FREE?

ASR is FREE. I know that if I ask people to send me money,
more than likely they will send me nothing. I know how it
works...I have not registered many shareware programs, I admit. I
register the ones that I love and use very often. But, if out of
the kindness of your heart, you wish to send me any small token of
thanks for writing ASR, you may send whatever you feel appropriate.
I leave that up to you.
I DO ask that you mail me and tell me you are using ASR to
"de-string" your code in addition to ESM. It is so easy for you to
drop me a generic letter saying "I love ASR, keep up writing super programs!"
and then I can count you on my list of users who use my
programs. I will mail you personally through WWIVnet with any
future product announcements. This is kind of like "registration":
if you mail me, you can only get more. If you don't, you might
never learn about some of my stuff.

You can reach me through one of these Network Addresses:

#3 (Ellrond) @9987 (Silicon Valley WWIVnet)
#2 (Ellrond) @9191 (Silicon Valley VirtualNET)

or just call Silicon Valley. And here, I shamelessly plug our
BBS system.

Silicon Valley
9987 WWIVnet
9191 VirtualNET
FIDOnet and INTERnet are on the way!
HUGE compilation of WWIV mods and external programs.
Located in Winston-Salem, NC (group 5 WWIVnet)
(919) 765-8640, auto-sysop validation.
USR Dual STD. modem, v.32bis/v.42bis.

If you wish not to make a long distance call, or you do not have
access to WWIVnet (god forbid!) you can send surface mail to:

Preston Brown
1110 Arbor Rd.
Winston-Salem, NC 27104

If you do send surface mail, I will mail you back a list of
all my current software, and if you enclose $5, I will send you a
disk with all my current software as well as a list.

Good luck!

Ellrond, May 4th, 1992
see UPDATE50.DOC for revision history.