CBM2ASC -- A Commodore ASCII to standard ASCII converter.
*** Version 1.1 ***

By Reed D. Meyer (rdm@astro.yale.edu), 1/28/99.
========================================================

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

As Manfred Vonderheidt's "Ultimative Commodore 64 Seite" appears to be the
only website where the original version of this program was actually
advertised as something worth downloading, I will consider this to be
the primary website for CBM2ASC.  (Thanks, Manfred!)  The website is

http://www.main-rheiner.de/homepage/manfred.vonderheidt

and look for "cbm2asc_nn.zip" where nn is the version number (11 for 1.1).

I will also try to upload CBM2ASC.EXE to the anonymous ftp sites
ftp.funet.fi and ftp.oit.unc.edu.


VERSION HISTORY
---------------

Version 1.1 (1/28/99) changes:
     --- Buffered input and output.  Now runs (almost) infinitely faster.
         Before, files were read/written one byte at a time, meaning that
         large files took some time to convert.  Now it's instantaneous.
     --- Fixed bug in printing very large (>32767) line numbers with 'B'
         option.  Thanks to Usr2001@aol.com for reporting the bug.
     --- Output and input files can now have the same name, if desired
         (in which case, output file would simply replace input file).
     --- Made output of 'B' option (Basic mode) prettier (added spaces
         between commands, etc.); user won't need to edit the output as
         much before running it on a Basic interpreter/compiler.
Version 1.0 (6/24/94):
     --- First released version.


PURPOSE OF THE PROGRAM
----------------------

To help in the transfer of files from the Commodore 64 to an IBM PC or
similar system.  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.  So much different that
if you try viewing a Commodore 64 text file, without conversion, in a
text editor on a PC (or similar system), you'll basically just get
garbage.  This conversion program makes things legible again.  It is
particularly fine-tuned to converting Commodore BASIC files and
documents written with the SpeedScript word processor (see the 'B' and
'S' options detailed below).

CBM2ASC doesn't do a perfect job at converting Commodore 64 text files.
In particular, the "extended" ASCII codes (i.e., the graphics characters;
codes between 128 and 255) are RADICALLY different between Commodore and
standard ASCII -- 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 PC-based
BASIC interpreter (e.g., QBasic) if the program does not rely upon
Commodore-specific BASIC commands!  Most likely you will need to do a
significant amount of tweaking to get the converted file to actually work,
since CBM2ASC strictly converts file format only; it knows nothing about
the differences between Commodore BASIC and other versions of BASIC.

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).


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 above.)

<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.


PROBLEMS
--------

No major ones known in this version.  As discussed above, CBM2ASC does not
convert non-standard characters (i.e., anything but alphanumerics and
punctuation) but a future version may improve this.  The output from the
'B' option probably needs significant tweaking to actually make the
resulting BASIC program work in a modern interpreter/compiler like QBasic.


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.

   Hope you find it useful!
---Reed D. Meyer (rdm@astro.yale.edu)

