CBM2ASC -- A Commdore ASCII to standard ASCII converter.
*** Version 1.0 ***

By Reed D. Meyer (rdm@astro.yale.edu), 6/14/94.
========================================================

WHERE TO FIND THIS PROGRAM
--------------------------

I will try to upload CBM2ASC.EXE to the anonymous ftp sites
watson.mbb.sfu.ca  and  ftp.funet.fi.

INSTRUCTIONS
------------

Call CBM2ASC with the following command line:

     CBM2ASC  <infile> <outfile> [opt]

where <infile> is the name of the input (Commodore ASCII) file,
<outfile> is the name of the output (standard ASCII) file, and
[opt] is an optional parameter which can be either:

     'B' or 'b' ---  convert a Commodore-64 BASIC program to standard ASCII
     'S' or 's' ---  convert a file written with the Commodore-64 version
                     of "SpeedScript" (a popular word-processing program
                     many years ago) to standard ASCII

(If [opt] is left blank, only alphanumerics and certain other standard
ASCII characters are converted; see below.)

<outfile> will be overwritten, if it already exists; CBM2ASC does NOT
prompt you before it overwrites the file!  As far as I know, CBM2ASC will
accept any valid DOS filename (but, unfortunately, wildcards are not
supported in this version).  You can even overwrite the input file with
<infile> = <outfile>.

CBM2ASC only works on Commodore-64 files which have been saved as binary
files in DOS.  In other words, CBM2ASC will not read "virtual disks"
like .D64 files.  If you have only virtual disk images like .D64 files,
try using a utility like D64T64 (dt64_10.zip on watson.mbb.sfu.ca) to
save the Commodore files as individual DOS (binary) files.

WHAT THE PROGRAM ACTUALLY DOES
------------------------------

As you may already know, the Commodore 64 "ASCII" character set is
substantially different from the "standard" ASCII set used by IBM PC
compatibles and other machines.  And the "extended" ASCII codes (i.e.,
the graphics characters; codes between 128 and 255) are RADICALLY
different -- many of the graphics characters on the C64 are so different
from, say, the IBM graphics characters that it would be more-or-less
impossible to map the full Commodore ASCII set one-for-one with the full
IBM set.  Therefore I have decided to convert only those characters
which SHOULD be a standard part of any "ASCII" character set: namely,
most of the symbols you typically find on a typewriter keyboard
(i.e., alphanumerics, carriage return, '!', '#', '%', etc.)  (Perhaps
in the future I would also have it map those graphics codes which DO have
IBM equivalents, but not in the current version.)

When you use the option 'B' (for "BASIC"), the program goes one step
further: it interprets the input file as if it were the binary image of
a C64 BASIC program.  In order to save space, C64 BASIC statements are
stored in memory as single-byte character codes > 128; these character
codes are properly converted by CBM2ASC into ASCII strings like "GOTO",
"RETURN", etc.  CBM2ASC also properly converts BASIC line numbers into
strings like "100", "200", etc.  Generally speaking, the only things
which CBM2ASC does not convert in a C64 BASIC program are graphics
characters within strings (for example, codes to "clear the screen"
or "change color to blue" within strings, will not be converted.)
The 'B' option is most useful for reading C64 BASIC programs, but it
may even be possible to run the converted programs on a DOS-based
BASIC interpreter (e.g., QBasic) if the program does not rely upon
Commodore-specific BASIC commands!

The option 'S' (for "SpeedScript") is a special option I included for
properly interpreting C64 SpeedScript files; SpeedScript was the
primary motivation for writing CBM2ASC.  You see, for a long time 
SpeedScript (a public domain word processor published in Compute's Gazette 
many years ago) was the only word processor I had; I amassed
a large number of SpeedScript files which I now wanted to convert to ASCII 
for use with DOS-based word processors, etc.  Anyway, with the 'S' option,
CBM2ASC will convert all the characters in a SpeedScript file EXCEPT for
SpeedScript escape codes -- i.e., the control sequences that tell
SpeedScript when to do boldface, italics, centerlining, etc.  Since it's
been many years since I last used SpeedScript and even longer since I read
the instructions for it, I can't remember how the various escape codes
work.  Furthermore, each word-processor (e.g., Microsoft Word, WordPerfect,
etc.) has a different way of defining its escape codes, so I decided not
to attempt to convert them.  I have CBM2ASC pass these codes "untouched"
to the output file, so the user can manually pass through the output file
and convert the escape sequences to the proper set of codes necessary
for specifying italics, boldface, etc. on the word processor which that
person likes most.  (There shouldn't be that many escape sequences to
have to convert manually; after all, SpeedScript files can't be more than
about 50k long.)

Note that the 'S' option passes all characters, even the ones it can't
convert, to the output file; whereas the 'B' and 'default' options simply
ignore characters which can't be converted (these characters are not
passed to the output file).

PROBLEMS
--------

This isn't really a problem, but: on large files ( > 40k or so), you may
find CBM2ASC annoyingly slow.  I believe this is because I have the
program read and write files one byte at a time (rather than using buffers).
I haven't bothered to change it because most of the files I have converted
aren't particularly large, but I MIGHT look into this in future versions
of CBM2ASC.

DISCLAIMER
----------

CBM2ASC is Freeware; it is in the public domain and you can do whatever
you want with it.  But as such, I won't be held responsible for any harm
that occurs as a result of its use!  I can e-mail you the Borland C++
source code if you like.

---Reed D. Meyer (rdm@astro.yale.edu)

