   -=[ MacDown 1.0     Copyright 1988 Jason Harper ]=-

MacDown is a utility for converting some downloaded Macintosh
files into formats usable on Apple II-series computers.  It
will run on any Apple II that supports ProDOS (in other
words, at least 64K memory), but the screen displays will
probably not be readable on an Apple ][ or ][+, even with a
lower-case adapter.  The program is freeware, meaning that it
is a copyrighted work but I give users the right to freely
distribute it and upload it to computer services.

=> Why Mac files are a bit difficult to work with.
The Macintosh has a very unusual file system: its files,
instead of being a single sequence of bytes as most
computer's files are, consist of two completely separate
sequences of bytes plus a substantial amount of information
about the file, such as the format of data it contains and
the program that created it.  The two components of a Mac
file are referred to as the 'data fork' and the 'resource
fork': the data fork contains arbitrary data much as other
computer's files do, and the resource fork contains a series
of discrete data items ("resources") such as icons.  A Mac
file may be missing one or both forks: document files tend to
be mainly data, while program files tend to be mainly
resources.  This file arrangement makes it impossible to
simply send a Mac file via modem: there must be some way to
recreate the two forks and the file's directory information.
Early Mac communication programs actually transmitted files
in three pieces which were glued back together at the
receiving end: this works when connected directly to another
Mac, but non-Mac host computer systems generally are not
prepared to handle such files.  So, a standard was developed
to allow all the parts of a Mac file to be appended into a
single data stream, with imbedded information to allow the
original file to be recovered unchanged...

=> The MacBinary standard.
All current Mac communication programs now automatically
convert transmitted files into MacBinary format, and rebuild
received MacBinary files into an exact copy of the original
file.  The format is quite similar to the Binary II format
used for transfer of files between Apple II computers (which
was based on MacBinary): the transmitted data starts with a
128-byte header containing the file's directory information
and the length of the two forks, followed by the data fork
(if any) rounded up to a multiple of 128 bytes, followed by
the resource fork (if any) also rounded up.  There are
provisions for tacking on additional information at the end,
but this is seldom (if ever) implemented.  Using MacBinary
files downloaded on an Apple II isn't very difficult: since
most Mac files that are meaningful on other computers contain
only data and no resources, just stripping off the first 128
bytes of the file is sufficient.  This can be done (on files
at most 32K long) from ProDOS Basic with the commands:
  BLOAD mac.file,Ttxt,A$1000
  BSAVE mac.file,Ttxt,A$1080
replacing 'mac.file' and 'txt' with the downloaded file's
actual name and filetype.  The process gets much more
complicated with longer files, and there are other problems
to worry about...

=> Compressed files.
Mac files tend to be pretty large, so it is a common practice
to apply some sort of compression to them.  There are two
compression methods in current use: PackIt and StuffIt.  Such
files can be easily identified because their names will end
with .PIT or .SIT, respectively.  Another advantage of using
these schemes is that related files (a program and its
documentation, for example) can be packed into one file for
transmission: unlike Binary II, the current implementation of
MacBinary does not allow for multiple files.  StuffIt is the
more recent and more efficient of the two formats:
unfortunately, its author has not seen fit to release enough
information on the format to allow decoders to be developed
for other computers.  PackIt is, however, publicly defined
and MacDown will allow you to decompress such files for use
on an Apple II.

=> Mac file formats.
Mac files are identified by a 4-character filetype code and a
4-character creator code: for example, a MacPaint picture has
filetype=PNTG and creator=MPNT.  A MacPaint-format picture
generated by some other program will still have a filetype of
PNTG but will have a different creator.  Some common types:
* PNTG: MacPaint picture.  MacDown will allow you to view
these in HiRes graphics.  If you have an Apple IIgs, see my
SHRConvert utility which will convert these files directly
into several IIgs SuperHiRes formats.
* TEXT: plain text.  Usable with any Apple II program that
deals with text, although some Mac characters (accented
vowels, for example) will not translate properly.
* APPL: application program.  Totally useless on a II.
* PIT : PackIt-format compressed file.
* SIT!: StuffIt-format compressed file: currently unusable.
There are numerous other Mac file formats, such as word
processor documents, that could be used on an Apple II if
someone would write a converter for them (hint hint).

=> Using MacDown.
MacDown is a ProDOS SYStem program, so you can run it from
Basic by typing "-MACDOWN" (without the quotes, of course).
The program should be fairly easy to use: it is controlled
entirely with the arrow keys (to move the hilighted selection
up or down), Return (to accept the current selection), and
Escape (to go back to the previous menu).  The trickiest part
is the file selector routine used in various parts of the
program: I'd suggest that you put an unimportant disk in a
drive, select 'ProDOS commands' from MacDown's main menu, and
play with it for a while.  Pay close attention to the [set
prefix here] option at the top of each directory listing: you
must use that command at some point to select where you want
converted Mac files to go.  If you're trying to put converted
files on a different disk, both disks must be online at the
same time: disk swapping is not allowed.  All downloaded Mac
files should first be processed with the 'Extract MacBinary'
command.  If the file is PackIt-compressed, you should then
use 'De-compress PackIt' on the extracted file.  You can then
use 'MacPaint => hires' to display any picture files.  For
each file produced by the conversion process, you will be
presented with some info about the file, and given options to
save or not save each fork.  You generally won't want to save
the resource fork of any file, since it is not meaningful on
an Apple II.  Data forks will be saved with the closest
ProDOS equivalent to the original Mac filename: resource
forks will be saved with the same name with '.R' appended.
If a name conflict arises, you will be given options to
cancel, save with a different name ('.N' will be added to the
name), rename the existing file ('.O' will be added), or
delete the existing file.  Note that PackIt files will take a
long time to process, even if you aren't saving either fork.

=> The end.
Thanks to George Photakis for beta-testing this program.
Please send any questions, comments, bug reports, gripes,
or suggestions (or large sums of money, for that matter) to:
        Jason Harper
        CompuServe: 76703,4222 (preferred)
        GEnie: JR.HARPER
        1480 Michelle Ct. #A
        Colorado Springs, CO 80916
