home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Amiga / Workbench / Archivers / mcvertWOS.lha / mcvertppc / mcvert.man < prev    next >
Text File  |  1998-04-08  |  17KB  |  397 lines
  1.  
  2.  
  3.  
  4.  MCVERT(LOCAL)                                                 MCVERT(LOCAL)
  5.                                    10Nov93
  6.  
  7.  
  8.  
  9.  NAME
  10.       mcvert - MacBinary <=> BinHex 4.0 and more file conversion utility
  11.  
  12.  SYNOPSIS
  13.       mcvert { [option] ... name ... } ...
  14.  
  15.  DESCRIPTION
  16.       The mcvert program translates files between MacBinary format and other
  17.       formats often used in exchanging Macintosh files.  See FILE FORMATS
  18.       below for a description of the file formats supported.
  19.  
  20.  PARAMETERS
  21.       The defaults for the parameters are -xDqv: convert BinHex 4.0 files
  22.       (x) to MacBinary files (D), bypass automatic unpacking of PIT files
  23.       (q), and provide a verbose level of output (v).
  24.  
  25.  OPTIONS
  26.       All the options, other than FORMAT OPTIONS described below, are listed
  27.       here.  From each set, one and only one alternative is active for any
  28.       one file.
  29.  
  30.       U | D
  31.            When option -U, as in Upload, is selected, the conversion is from
  32.            MacBinary to something else.  Conversely, option -D, as in
  33.            Download, selects conversion from something to MacBinary.
  34.  
  35.       p | q
  36.            If a BinHex 4.0 to MacBinary conversion is taking place and
  37.            option -p, as in Pit, is selected, any file of type "PIT " will
  38.            be unpacked into its constituent parts.  This option does not
  39.            recursively unpack "PIT " files packed in "PIT " files.  If a
  40.            MacBinary to BinHex 4.0 conversion is taking place, this option
  41.            is currently ignored.  Conversely, option -q, as in Quiescent,
  42.            does no such unpacking.
  43.  
  44.       t    Macintosh and UNIX differ in the end-of-line character they use.
  45.            Option -t, as in Translate, enables end-of-line character
  46.            translation for the data.  Translation is off by default, but it
  47.            is enabled automatically when processing -u (Usual Text) files.
  48.            Option -t is useful when processing both data and resource files
  49.            at the same time (option -b) to enable end-of-line character
  50.            translation for the data.
  51.  
  52.       S | s | v | V | VV
  53.            Normally, mcvert prints converting messages and other information
  54.            about the files it is processing to stderr.  Option -S, as in
  55.            SILENT, disables all such reporting.  Option -s, as in Silent,
  56.            disables all but the "Converting ..." messages.  Option -v, as in
  57.            Verbose, emits generally useful information.  Option -V, as in
  58.            VERBOSE, displays some additional debugging information.  Option
  59.            -VV, as in VERY VERBOSE, displays detailed debugging information
  60.  
  61.  
  62.  
  63.                                     - 1 -       Formatted:  October 14, 1994
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  MCVERT(LOCAL)                                                 MCVERT(LOCAL)
  71.                                    10Nov93
  72.  
  73.  
  74.  
  75.            as well.
  76.  
  77.       H    Option -H, as in Heuristic, disables the skip-legal-but-suspect-
  78.            lines heuristic used when processing BinHex 4.0 formatted input
  79.            files.  See BUGS below for details on the heuristic.
  80.  
  81.       I    Option -I, as in Information only, does not write output files,
  82.            but does indicate which output files would normally be written.
  83.            All other operations are performed, including verifying file
  84.            formats and calculated CRC values.  The -I option basically
  85.            provides a non-destructive verification of the files and their
  86.            processing.  It is also a soothing balm for the somewhat
  87.            paranoid, since it reports what files would be changed, without
  88.            actually changing them.
  89.  
  90.       P    Option -P, as in Pipe output to stdout, writes the resulting
  91.            output file(s) to stdout, rather than to the file system with the
  92.            appropriate extension.  The default is to use the file system.
  93.  
  94.  FILE FORMATS
  95.       Some useful formats in which Macintosh files are represented on non-
  96.       Macs are:
  97.  
  98.       MacBinary:
  99.            An eight bit wide representation of the data and resource forks
  100.            of a Mac file and of relevant Finder information, MacBinary files
  101.            are recognized as "special" by several Macintosh terminal
  102.            emulators.  These emulators, using kermit or xmodem or other file
  103.            transfer protocols, can separate the incoming file into forks and
  104.            appropriately modify the Desktop to display icons, types,
  105.            creation dates, and the like.
  106.  
  107.       BinHex 4.0:
  108.            A seven bit wide representation of a Mac file with CRC error
  109.            checking, BinHex 4.0 files are designed for communication of Mac
  110.            files over long distance, possibly noisy, seven bit wide paths.
  111.  
  112.       PackIt:
  113.            PackIt files are actually representations of collections of Mac
  114.            files, possibly Huffman compressed.  Packing many small related
  115.            files together before a MacBinary transfer or a translation to
  116.            BinHex 4.0 is common practice.
  117.  
  118.       Text:
  119.            A Macintosh ends each line of a plain text file with a carriage
  120.            return character (^M), rather than the newline character (^J)
  121.            that some systems require (for example, UNIX).  Moreover, a
  122.            MacBinary file has prepended Finder information that non-
  123.            Macintoshes usually don't expect.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                     - 2 -       Formatted:  October 14, 1994
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  MCVERT(LOCAL)                                                 MCVERT(LOCAL)
  137.                                    10Nov93
  138.  
  139.  
  140.  
  141.       Data, Rsrc:
  142.            A Data or Rsrc file is the exact copy of the data or resource
  143.            fork of a Macintosh file.
  144.  
  145.  FORMAT OPTIONS
  146.       Exactly one of the following selections may be specified for an input
  147.       name:
  148.  
  149.       x    BinHex 4.0 [.hqx] - files in the MacBinary format are translated
  150.            to BinHex 4.0 files, or vice versa.  The name argument is the
  151.            name of a file to be converted.  If the conversion is from BinHex
  152.            4.0 to MacBinary, several files may comprise the BinHex 4.0
  153.            representation of the Mac file.  Rather than manually concatenate
  154.            the files and manually delete mail headers and other extraneous
  155.            garbage, one may specify the names of the files in order and
  156.            mcvert will do the concatenating and deleting.  Conversely, in
  157.            converting a MacBinary file to BinHex 4.0 format for mailing over
  158.            long distances, one may be restricted to mail messages of no
  159.            greater that some fixed length.  In this case, mcvert can
  160.            automatically divide the BinHex 4.0 file into pieces and label
  161.            each piece appropriately.  For details on automatically
  162.            segmenting files, see the description of the MAC_LINE_LIMIT
  163.            environment variable below.
  164.  
  165.       u | h
  166.            Text [.text] - files in the MacBinary format with nonempty data
  167.            forks and empty resource forks are made from ordinary data files,
  168.            or vice versa.  Option -u, for Usual Text, performs translation.
  169.            Option -h, for Host Text, performs no translation.  When
  170.            translating, UNIX newline characters are interchanged with
  171.            Macintosh carriage return characters.
  172.  
  173.       d    Data [.data] - files in the MacBinary format with nonempty data
  174.            forks and empty resource forks are made from ordinary data files,
  175.            or vice versa.  If the data is really text, you should use -u or
  176.            -h so that the file type and creator get set correctly.
  177.  
  178.       r    Resource [.rsrc] - files in the MacBinary format with empty data
  179.            forks and nonempty resource forks are made from ordinary data
  180.            files, or vice versa.
  181.  
  182.       b    Both [.data .rsrc] - files in the MacBinary format with nonempty
  183.            data forks and and nonempty resource forks are made from ordinary
  184.            data files, or vice versa.  For option -b processing, a single
  185.            base file name is provided, and the ".data" and ".rsrc"
  186.            extensions are supplied by mcvert.
  187.  
  188.  FILE NAMES AND EXTENSIONS
  189.       mcvert uses certain file extensions when reading and writing files.
  190.       These extensions are indicated in the "FORMAT OPTIONS" section above.
  191.       For example, the appropriate extension for a BinHex 4.0 file is
  192.  
  193.  
  194.  
  195.                                     - 3 -       Formatted:  October 14, 1994
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  MCVERT(LOCAL)                                                 MCVERT(LOCAL)
  203.                                    10Nov93
  204.  
  205.  
  206.  
  207.       ".hqx".
  208.  
  209.       For input files, mcvert first tries to open the file using the
  210.       specified name.  If that fails, mcvert appends the appropriate suffix
  211.       (if not already present) and tries again.  Recall that for option -b
  212.       (Both) processing, a single base file name must be provided, since the
  213.       ".data" and ".rsrc" extensions are appended automatically by mcvert.
  214.       For example, "mcvert foo" will try to open "foo", and failing that,
  215.       try to open "foo.hqx" for input; while "mcvert -b foo" will open only
  216.       "foo.data" and "foo.rsrc" for input.
  217.  
  218.       For output files, mcvert always uses the specified base file name and
  219.       appropriate extension.  For MacBinary and BinHex 4.0 input files, the
  220.       base file name is specified within the input file, while for plain
  221.       files, the file name specified on the command line is used.  The
  222.       appropriate extension is based on the conversion, or on the MAC_EXT
  223.       environment variable for MacBinary output files.  For example, if
  224.       there is text file named foo.text (but no file named foo), "mcvert -u
  225.       foo" will use foo.text as input, and generate a file called "foo.bin",
  226.       while "mcvert -u foo.text" will use foo.text as input, and generate a
  227.       file called "foo.text.bin".
  228.  
  229.  ENVIRONMENT VARIABLES AND DEFAULTS
  230.       There are five environment variables one may use to customize the
  231.       behavior of mcvert slightly.
  232.  
  233.       MAC_FILETYPE
  234.            The file type of a MacBinary file converted from non BinHex 4.0
  235.            inputs is set to this four-character sequence.  For example, one
  236.            might set this variable to "PICT" when converting files created
  237.            by ppmtopict(1).  The default is "TEXT" for Text or Host inputs,
  238.            and "????" otherwise.  BinHex 4.0 inputs specify the file type to
  239.            use internally.
  240.  
  241.       MAC_EDITOR
  242.            The creator type (author) of MacBinary files is set to this
  243.            four-character sequence.  The default is "MACA" (the creator type
  244.            of MacWrite) for Text inputs, and "????" otherwise.  BinHex 4.0
  245.            inputs specify the creator type to use internally.
  246.  
  247.       MAC_DLOAD_DIR
  248.            The MacBinary files created when option -D is selected are placed
  249.            in this directory.  The default is ".", the current working
  250.            directory.
  251.  
  252.       MAC_EXT
  253.            The MacBinary files created when option -D is selected are named
  254.            according to the file name field stored in the file header, with
  255.            the name extended by this suffix.  The default is ".bin".
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                     - 4 -       Formatted:  October 14, 1994
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  MCVERT(LOCAL)                                                 MCVERT(LOCAL)
  269.                                    10Nov93
  270.  
  271.  
  272.  
  273.       MAC_LINE_LIMIT
  274.            The BinHex 4.0 files created when option -U is selected may be no
  275.            longer than this many lines long.  Files that would otherwise
  276.            exceed this line limit are broken up into several files with
  277.            numbers embedded into their file names to show their order.  Each
  278.            such file has "Start of part x" and "End of part x" messages
  279.            included where appropriate.
  280.  
  281.  BUGS
  282.       mcvert silently discards input lines which are not completely valid.
  283.       Therefore, error indications for illegally formatted files are likely
  284.       to be somewhat obtuse, often with just a CRC mismatch message.
  285.  
  286.       In order to handle files (such as segmented comp.binaries.mac files)
  287.       which have extraneous but valid BinHex 4.0 lines (such as  "---"),
  288.       mcvert uses the following heuristic to discard suspect but legal lines
  289.       in BinHex 4.0 formatted input files.  When a new file is opened, or
  290.       when invalid lines are found, the search for good data begins.  While
  291.       searching for good data, if a line is too short (less than 12
  292.       characters), or if a line is just a single repeated character, the
  293.       line is discarded.  Once mcvert starts processing good data, no valid
  294.       lines are discarded.  Thus, this heuristic can also discard (unusually
  295.       formatted) valid and intended BinHex 4.0 lines.  While there is no way
  296.       to tune the heuristic (other than modifying the program and
  297.       recompiling), the heuristic can be completely disabled with the -H
  298.       option.  So if you run into problems, put all the relevant lines into
  299.       one file, edit the file to remove any extraneous lines, and invoke
  300.       mcvert with the -H option.
  301.  
  302.       It should be possible to discard bad input now and successfully
  303.       translate good input later, but bad input usually causes immediate
  304.       termination.
  305.  
  306.       A more diligent person would support BinHex 3.0 and BinHex 2.0 and
  307.       BinHex 5000 B. C., but I've never seen or heard of anyone using them
  308.       in years.
  309.  
  310.  OTHER PROGRAMS
  311.       There are a number of programs which run on the Mac and convert
  312.       between various Macintosh file formats.  For example, here's what
  313.       info-mac/help/accessing-files.txt, as of 13Jun93, has to say about
  314.       converting between BinHex 4.0 and native Mac files:
  315.  
  316.            You can also do the conversion on your Macintosh by using any of
  317.            a number of utilities, including BinHex 4.0, StuffIt, or Compact
  318.            Pro. We recommend using Compact Pro because it is slightly more
  319.            convenient and reliable than the other tools.  Note: do NOT use
  320.            BinHex 5.0 as it is incompatible, for some very brain-damaged
  321.            reasons.
  322.  
  323.       CompactPro is a wonderful piece of shareware.  But if your needs are
  324.  
  325.  
  326.  
  327.                                     - 5 -       Formatted:  October 14, 1994
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  MCVERT(LOCAL)                                                 MCVERT(LOCAL)
  335.                                    10Nov93
  336.  
  337.  
  338.  
  339.       limited to expansion of BinHex 4.0 files, StuffIt or CompactPro
  340.       archives or AppleLink packages, then the freeware StuffIt Expander (v
  341.       3.0.3 as of 28Jul93) may be just what you want.
  342.  
  343.       There are other programs available which run under UNIX and convert
  344.       between various Macintosh file formats.  One of these programs may be
  345.       what you want to use if mcvert does not meet your needs.  One
  346.       collection, called macutil, is available from various archives.
  347.       Here's what the comp.sys.mac.comm FAQ (Frequently Asked Questions),
  348.       Last-modified: Sat Jun 05 1993, has to say about it:
  349.  
  350.            As of (8/92), macutil includes three programs:
  351.  
  352.            hexbin
  353.                 a program to convert BinHex 4.0 to MacBinary; it also
  354.                 converts uuencode (and UULite) files to their native binary
  355.                 format; support for .dl, .hex, and .hcx formats (all
  356.                 predecessors of BinHex 4.0) also exists
  357.  
  358.            macsave
  359.                 a MacBinary filter program to convert between various
  360.                 MacBinary representations, including a single .bin file,
  361.                 three separate .data, .rsrc, .info files, and AUFS format.
  362.                 macsave also allows one to "peek" inside MacBinary files
  363.  
  364.            macunpack
  365.                 a program to unpack PackIt, StuffIt, Diamond,
  366.                 Compactor/Compact Pro, most StuffIt Classic and StuffIt
  367.                 Deluxe, DiskDoubler, Zoom and LHarc/MacLHa archives.
  368.  
  369.                 It also decodes BinHex 5.0, MacBinary, uuencode, and UNIX
  370.                 compress (ie: .Z suffix) files (as well as variants of
  371.                 compress implemented by various Macintosh compress
  372.                 programs).
  373.  
  374.                 Support for password protected and/or multi-segment archives
  375.                 of various types is minimal or non-existent.
  376.  
  377.  SEE ALSO
  378.       hexbin(1), kermit(1), macbin(1), macunpack(1), macsave(1), macutil(1),
  379.       ppmtopict(1), sit(1), unsit(1), xbin(1), xmodem(1)
  380.  
  381.  AUTHORS
  382.       Doug Moore, Cornell University Computer Science.  Based upon xbin by
  383.       Dave Johnson, Brown University, as modified by Guido van Rossum, and
  384.       upon unpit by Allan G. Weber, as well as upon correspondence with
  385.       several helpful readers of USENET.
  386.  
  387.       Joseph P. Skudlarek (Jskud@wv.MentorG.com) made numerous enhancement
  388.       and maintenance releases.  See the comments in mcvert.c for additional
  389.       supporting characters.
  390.  
  391.  
  392.  
  393.                                     - 6 -       Formatted:  October 14, 1994
  394.  
  395.  
  396.  
  397.