MCVERT(LOCAL) MCVERT(LOCAL) 10Nov93 NAME mcvert - MacBinary <=> BinHex 4.0 and more file conversion utility SYNOPSIS mcvert { [option] ... name ... } ... DESCRIPTION The mcvert program translates files between MacBinary format and other formats often used in exchanging Macintosh files. See FILE FORMATS below for a description of the file formats supported. PARAMETERS The defaults for the parameters are -xDqv: convert BinHex 4.0 files (x) to MacBinary files (D), bypass automatic unpacking of PIT files (q), and provide a verbose level of output (v). OPTIONS All the options, other than FORMAT OPTIONS described below, are listed here. From each set, one and only one alternative is active for any one file. 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. 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. 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. S | s | v | V | VV Normally, 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 - 1 - Formatted: October 14, 1994 MCVERT(LOCAL) MCVERT(LOCAL) 10Nov93 as well. H Option -H, as in Heuristic, disables the skip-legal-but-suspect- lines heuristic used when processing BinHex 4.0 formatted input files. See BUGS below for details on the heuristic. 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. 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. FILE FORMATS Some useful formats in which Macintosh files are represented on non- Macs are: 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. 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. 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. 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. - 2 - Formatted: October 14, 1994 MCVERT(LOCAL) MCVERT(LOCAL) 10Nov93 Data, Rsrc: A Data or Rsrc file is the exact copy of the data or resource fork of a Macintosh file. FORMAT OPTIONS Exactly one of the following selections may be specified for an input name: 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 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, 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 MAC_LINE_LIMIT environment variable below. 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. 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. 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. 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 mcvert. FILE NAMES AND EXTENSIONS 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 - 3 - Formatted: October 14, 1994 MCVERT(LOCAL) MCVERT(LOCAL) 10Nov93 ".hqx". For input files, mcvert first tries to open the file using the specified name. If that fails, 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 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. For output files, 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". ENVIRONMENT VARIABLES AND DEFAULTS There are five environment variables one may use to customize the behavior of mcvert slightly. 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. 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. MAC_DLOAD_DIR The MacBinary files created when option -D is selected are placed in this directory. The default is ".", the current working directory. 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". - 4 - Formatted: October 14, 1994 MCVERT(LOCAL) MCVERT(LOCAL) 10Nov93 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. BUGS 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. In order to handle files (such as segmented comp.binaries.mac files) which have extraneous but valid BinHex 4.0 lines (such as "---"), 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 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 -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 mcvert with the -H option. It should be possible to discard bad input now and successfully translate good input later, but bad input usually causes immediate termination. 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. 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: 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. CompactPro is a wonderful piece of shareware. But if your needs are - 5 - Formatted: October 14, 1994 MCVERT(LOCAL) MCVERT(LOCAL) 10Nov93 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. 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 mcvert does not meet your needs. One collection, called 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: As of (8/92), macutil includes three programs: 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 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 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. SEE ALSO hexbin(1), kermit(1), macbin(1), macunpack(1), macsave(1), macutil(1), ppmtopict(1), sit(1), unsit(1), xbin(1), xmodem(1) AUTHORS Doug Moore, Cornell University Computer Science. Based upon xbin by Dave Johnson, Brown University, as modified by Guido van Rossum, and upon unpit by Allan G. Weber, as well as upon correspondence with several helpful readers of USENET. Joseph P. Skudlarek (Jskud@wv.MentorG.com) made numerous enhancement and maintenance releases. See the comments in mcvert.c for additional supporting characters. - 6 - Formatted: October 14, 1994