.TH MCVERT LOCAL "10Nov93"
.UC 4.2
.SH NAME
mcvert \- MacBinary <=> BinHex 4.0 and more file conversion utility
.SH SYNOPSIS
.B mcvert
{ [option] ... name ... } ...
.br
.SH DESCRIPTION
The
.I mcvert
program translates files between MacBinary format and
other formats often used in exchanging Macintosh files.
See
.I FILE FORMATS
below for a description of the file formats supported.
.SH PARAMETERS
The defaults for the parameters are
.RB - xDqv :
convert BinHex 4.0 files
.RB ( x )
to MacBinary files
.RB ( D ),
bypass automatic unpacking of PIT files
.RB ( q ),
and provide a verbose level of output
.RB ( v ).
.SH "OPTIONS"
All the options, other than
.I "FORMAT OPTIONS"
described below, are listed here.
From each set, one and only one alternative is active for any one file.
.TP
.B U | D
When option -U, as in Upload, is selected,
the conversion is from MacBinary to something else.
Conversely, option -D, as in Download,
selects conversion from something to MacBinary.
.TP
.B p | q
If a BinHex 4.0 to MacBinary conversion is taking place
and option -p, as in Pit, is selected,
any file of type "PIT "
will be unpacked into its constituent parts.
This option does not recursively
unpack "PIT " files packed in "PIT " files.
If a MacBinary to BinHex 4.0 conversion is taking place,
this option is currently
ignored.
Conversely, option -q, as in Quiescent, does no such unpacking.
.TP
.B t
Macintosh and UNIX differ in the end-of-line character they use.
Option -t, as in Translate,
enables end-of-line character translation for the data.
Translation is off by default,
but it is enabled automatically when processing -u (Usual Text) files.
Option -t is useful when processing both data and resource files at the
same time (option -b) to enable end-of-line character translation for
the data.
.TP
.B
S | s | v | V | VV
Normally,
.I mcvert
prints converting messages and other information
about the files it is processing to stderr.
Option -S, as in SILENT, disables all such reporting.
Option -s, as in Silent, disables all but the "Converting ..." messages.
Option -v, as in Verbose, emits generally useful information.
Option -V, as in VERBOSE, displays some additional debugging information.
Option -VV, as in VERY VERBOSE, 
displays detailed debugging information as well.
.TP
.B H
Option -H, as in Heuristic,
disables the skip-legal-but-suspect-lines heuristic
used when processing BinHex 4.0 formatted input files.
See
.I BUGS
below for details on the heuristic.
.TP
.B I
Option -I, as in Information only,
does not write output files, but does indicate which output files would
normally be written.
All other operations are performed, including verifying file formats
and calculated CRC values.
The -I option basically provides a non-destructive verification of the
files and their processing.
It is also a soothing balm for the
somewhat paranoid, since it reports what files would be changed,
without actually changing them.
.TP
.B P
Option -P, as in Pipe output to stdout,
writes the resulting output file(s) to stdout,
rather than
to the file system
with the appropriate extension.
The default is to use the file system.
.SH "FILE FORMATS"
Some useful formats in which Macintosh files are represented on non-Macs are:
.TP
.B MacBinary:
An eight bit wide representation of the data and resource forks of a Mac
file and of relevant Finder information, MacBinary files are recognized
as "special" by several Macintosh terminal emulators.  These emulators,
using kermit or xmodem or other file transfer protocols,
can separate
the incoming file into forks and appropriately modify the Desktop to display
icons, types, creation dates, and the like.
.TP
.B BinHex 4.0:
A seven bit wide representation of a Mac file with CRC error checking,
BinHex 4.0 files are designed for communication of Mac files over long
distance, possibly noisy, seven bit wide paths.
.TP
.B PackIt:
PackIt files are actually representations of collections of Mac files, possibly
Huffman compressed.  Packing many small related files together before
a MacBinary transfer or a translation to BinHex 4.0 is common practice.
.TP
.B Text:
A Macintosh ends each line of a plain text file with a carriage return
character (^M), rather than the newline character (^J) that some systems
require (for example, UNIX).
Moreover, a MacBinary file has prepended Finder information
that non-Macintoshes usually don't expect.
.TP
.B Data, Rsrc:
A Data or Rsrc file is the exact copy of the data or resource fork of a
Macintosh file.
.SH "FORMAT OPTIONS"
Exactly one of the following selections may be specified for an input name:
.TP
.B x
BinHex 4.0 [.hqx] - files in the MacBinary format are translated to
BinHex 4.0 files, or vice versa.
The name argument is the name of a file to be converted.
If the conversion is from BinHex 4.0 to MacBinary,
several files may comprise the BinHex 4.0 representation of the Mac file.
Rather than manually concatenate the files and manually delete mail
headers and other extraneous garbage, one may specify the names of the
files in order and
.I mcvert
will do the concatenating and deleting.  Conversely, in converting
a MacBinary file to BinHex 4.0 format for mailing over long distances,
one may be restricted to mail messages of no greater that some fixed
length.  In this case,
.I mcvert
can automatically divide the BinHex 4.0 file into pieces and label each
piece appropriately.
For details on automatically segmenting files, see the description of the
.B MAC_LINE_LIMIT
environment variable below.
.TP
.B u | h
Text [.text] - files in the MacBinary format with nonempty data forks
and empty resource forks are made from ordinary data files, or vice versa.
Option -u, for Usual Text, performs translation.
Option -h, for Host Text, performs no translation.
When translating,
UNIX newline
characters are interchanged with Macintosh carriage return
characters.
.TP
.B d
Data [.data] - files in the MacBinary format with nonempty data forks
and empty resource forks are made from ordinary data files, or vice
versa.  If the data is really text, you should use -u or -h so that
the file type and creator get set correctly.
.TP
.B r
Resource [.rsrc] - files in the MacBinary format with empty data forks
and nonempty resource forks are made from ordinary data files, or vice versa.
.TP
.B b
Both [.data .rsrc] -
files in the MacBinary format with nonempty data forks and
and nonempty resource forks are made from ordinary data files, or vice versa.
For option -b processing, a single base file name is provided, and
the ".data" and ".rsrc" extensions are supplied by
.IR mcvert .
.SH "FILE NAMES AND EXTENSIONS"
.PP
.I mcvert
uses certain
file extensions when reading and writing files.  These
extensions are indicated in the "FORMAT OPTIONS" section above.
For example, the appropriate extension for a BinHex 4.0 file is
".hqx".
.PP
For input files,
.I mcvert 
first tries to open the file using the specified name.
If that fails,
.I mcvert
appends the appropriate suffix (if not already present) and tries again.
Recall that for option -b (Both) processing,
a single base file name must be provided, since
the ".data" and ".rsrc" extensions are appended automatically by
.IR mcvert .
For example,
"mcvert foo" will try to open "foo",
and failing that, try to open "foo.hqx" for input;
while "mcvert -b foo" will open only
"foo.data" and "foo.rsrc" for input.
.PP
For output files,
.I mcvert
always uses the specified base file name and appropriate extension.
For MacBinary and BinHex 4.0 input files,
the base file name is specified within the input file,
while for plain files,
the file name specified on the command line is used.
The appropriate extension is based on the conversion,
or on the MAC_EXT
environment variable for MacBinary output files.
For example, if there is text file named foo.text
(but no file named foo),
"mcvert -u foo" will use foo.text as input, and
generate a file called "foo.bin",
while 
"mcvert -u foo.text" will use foo.text as input, and
generate a file called "foo.text.bin".
.SH "ENVIRONMENT VARIABLES AND DEFAULTS"
There are five environment variables one may use to customize 
the behavior of
.I mcvert
slightly.
.TP
.B MAC_FILETYPE
The file type of a MacBinary file converted from
non BinHex 4.0 inputs is set to this four-character sequence.
For example, one might
set this variable to "PICT" when converting files created
by ppmtopict(1).
The default is "TEXT" for Text or Host inputs, and "????" otherwise.
BinHex 4.0 inputs specify the file type to use internally.
.TP
.B MAC_EDITOR
The creator type (author)
of MacBinary files is set to this four-character sequence.
The default is "MACA" (the creator type of MacWrite)
for Text inputs, and "????" otherwise.
BinHex 4.0 inputs specify the creator type to use internally.
.TP
.B MAC_DLOAD_DIR
The MacBinary files created when option -D is selected are placed in this
directory.  The default is ".", the current working directory.
.TP
.B MAC_EXT
The MacBinary files created when option -D is selected are named according
to the file name field stored in the file header, with the name extended by
this suffix.  The default is ".bin".
.TP
.B MAC_LINE_LIMIT
The BinHex 4.0 files created when option -U is selected may be no longer than
this many lines long.  Files that would otherwise exceed this line limit
are broken up into several files with numbers embedded into their file 
names to show their order.  Each such file has "Start of part x" and "End
of part x" messages included where appropriate.
.SH BUGS
.PP
.I mcvert
silently discards input lines which are not completely valid.
Therefore, error indications for illegally formatted files are likely to
be somewhat obtuse, often with just a CRC mismatch message.
.PP
In order to handle files
(such as segmented comp.binaries.mac files)
which have extraneous
but valid BinHex 4.0 lines
(such as  "---"),
.I mcvert
uses the following heuristic
to discard suspect but legal lines
in BinHex 4.0 formatted input files.
When a new file is opened, or when invalid lines are found,
the search for good data begins.
While searching for good data,
if a line is too short (less than 12 characters),
or if a line is just
a single repeated character, the line is discarded.
Once
.I mcvert
starts processing good data,
no valid lines are discarded.
Thus, this heuristic can also discard (unusually formatted)
valid and intended BinHex 4.0 lines.
While there is no way to tune the heuristic
(other than modifying the program and recompiling),
the heuristic can be completely disabled with the
.B -H
option.
So if you run into problems,
put all the relevant lines into one file,
edit the file to remove any extraneous lines,
and invoke
.I mcvert
with the
.B -H
option.
.PP
It should be possible to discard bad input now and successfully translate
good input later, but bad input usually causes immediate termination.
.PP
A more diligent person would support BinHex 3.0 and BinHex 2.0 and BinHex
5000 B. C., but I've never seen or heard of anyone using them in years.
.SH "OTHER PROGRAMS"
There are a number of programs which run on the Mac and convert
between various Macintosh file formats.
For example, here's what info-mac/help/accessing-files.txt, as of 13Jun93,
has to say about converting between BinHex 4.0 and native Mac files:
.RS

You can also do the conversion on
your Macintosh by using any of a number of utilities, including BinHex
4.0, StuffIt, or Compact Pro. We recommend using Compact Pro because
it is slightly more convenient and reliable than the other tools.
Note: do NOT use BinHex 5.0 as it is incompatible, for some very
brain-damaged reasons.
.RE

CompactPro is a wonderful piece of shareware.  But if your needs are
limited to expansion of BinHex 4.0 files, StuffIt or
CompactPro archives or AppleLink packages, then the freeware 
StuffIt Expander (v 3.0.3 as of 28Jul93) may be just what you want.
.PP
There are other programs available which run under UNIX and convert
between various Macintosh file formats.
One of these programs may be what you want to use if
.I mcvert
does not meet your needs.
One collection, called
.IR macutil ,
is available from various archives.
Here's what the comp.sys.mac.comm FAQ (Frequently Asked Questions),
Last-modified: Sat Jun 05 1993, has to say about it:
.RS
.IP "As of (8/92), macutil includes three programs:"
.IP hexbin
a program to convert BinHex 4.0 to MacBinary;
it also converts uuencode (and UULite) files to their
native binary format; support for .dl, .hex, and .hcx
formats (all predecessors of BinHex 4.0) also exists
.IP macsave
a MacBinary filter program to convert
between various MacBinary representations, including
a single .bin file, three separate .data, .rsrc, .info
files, and AUFS format. macsave also allows one to
"peek" inside MacBinary files
.IP macunpack
a program to unpack PackIt, StuffIt,
Diamond, Compactor/Compact Pro, most StuffIt Classic
and StuffIt Deluxe, DiskDoubler, Zoom and LHarc/MacLHa
archives.

It also decodes BinHex 5.0, MacBinary, uuencode, and
UNIX compress (ie: .Z suffix) files (as well as variants
of compress implemented by various Macintosh compress
programs).

Support for password protected and/or multi-segment
archives of various types is minimal or non-existent.
.RE
.SH "SEE ALSO"
hexbin(1),
kermit(1),
macbin(1),
macunpack(1),
macsave(1),
macutil(1),
ppmtopict(1),
sit(1),
unsit(1),
xbin(1),
xmodem(1)
.SH AUTHORS
Doug Moore, Cornell University Computer Science.  Based upon
.I xbin
by Dave Johnson, Brown University, as modified by Guido van Rossum, and upon
.I unpit
by Allan G. Weber, as well as upon correspondence with several helpful
readers of USENET.
.PP
Joseph P. Skudlarek (Jskud@wv.MentorG.com) made numerous
enhancement and maintenance releases.
See the comments in mcvert.c for additional supporting characters.