home *** CD-ROM | disk | FTP | other *** search
/ internet.au CDrom 42 / NETCD42.iso / misc / mac / maczip.hqx / MacZip 1.0 final / docs / README.TXT < prev    next >
Encoding:
Text File  |  1999-01-15  |  20.4 KB  |  514 lines
  1. Macintosh Port of Info-Zip's Zip
  2. by Dirk Haase, d_haase@sitec.net
  3. homepage:   www.sitec.net/maczip
  4. 15. January 1999
  5. ================================
  6.  
  7.  
  8. Some notes about this port:
  9. ===========================
  10.  
  11. MacZip requires at least System 7 and a Macintosh with a minimum of a 
  12. Motorola 68020 or PowerPC 601 processor. Other configurations may work
  13. but it is not tested at all.
  14.  
  15. The application is distributed as a fat binary with both regular 68K 
  16. and native PowerPC versions included.
  17.  
  18. Move the executable(s) somewhere--for example, drag it (or them) to your
  19. Applications folder.  For easy access, make an alias in the Launcher Control
  20. Panel or directly on your desktop.
  21. The GUI is very simple. It was not my intention to make a full-blown GUI,
  22. however I think it is comfortable enough to use it as regular tool.
  23.  
  24. This port supports also Apple-event.So you can install it in your
  25. WWW-Browser as a helper-app.
  26.  
  27. For more Info about the contents of this package, take a look into
  28. the "macos/Contents" (or :macos:Contents) file. Some notes on how to
  29. rebuild the Macintosh applications can be found in INSTALL.
  30.  
  31.  
  32.  
  33. Usage:
  34. ------
  35.  
  36. Basically there are four ways to start MacZip:
  37.  
  38. a) Drag'n Drop
  39.    To extract an archive drop an archive on MacZip.
  40.    To compress files drop a file, folder or volume on MacZip.
  41.    Note: You can not drop more than one item at the same time.
  42.    
  43.    
  44.  
  45. c) using the Dialog box (Menu: File->Start Zip/Unzip):
  46.    - Go to "Current App" and select "Zip" or "Unzip".
  47.    - Go to "File>Start Zip/Unzip"and the "Zip/Unzip Options" Dialog Box appears.
  48.    - Click on "Zip Archive"
  49.    - The "Select an archive" dialog box appears
  50.      You have basically two choices:
  51.         * Extraction:
  52.         a) select a existing zip archive
  53.            -> The choosen archive will be extracted.
  54.         * Compression:
  55.         a) select a existing zip archive
  56.            -> Your files will be added to that zip archive.
  57.         b) select a folder and name your new zip archive
  58.            -> a new zip archive will be created with your files.
  59.    - Select one or more check boxes if you want.
  60.    - Click on "Start Zip/Unzip" to start the task.
  61.      
  62.      
  63.      
  64. c) Using the Commandline (Menu: File->Command Line):
  65.    The zip & unzip tools are command line tools. So the behavior is exactly 
  66.    the same like the zip & unzip tools on unix or win. This means if you 
  67.    want zip some files you have to write a command line like this: 
  68.    [switches] path_to_zip_archive path_to_files_folders.
  69.    
  70.    - Go to "Current App" and select "Zip" or "Unzip".
  71.    - Go to "File" and select "Command Line" and the "MacZip Entry box" 
  72.      Dialog Box appears.
  73.  
  74.    An example:
  75.  
  76.    a: your zip may be created at
  77.            Macintosh HD:applications:archive.zip
  78.  
  79.    b: your files may be found at
  80.            Macintosh HD:somewhere:my_folder_to_archive:*
  81.  
  82.    Note: At the end of the path there must be a filename or a wild card !
  83.    (Footnote: 1 wild card, 2 Mac pathnames)
  84.    
  85.    So the command line should look like (one line!):
  86.  
  87.    Macintosh HD:applications:archive.zip Macintosh
  88.    HD:somewhere:my_folder_to_archive:*
  89.    
  90.    - Click on "Enter" to start the task.
  91.  
  92.    Since you can not set a default folder you have to enter always a 
  93.    full qualified path names. Full qualified path names are path names 
  94.    including the Volume name ! (Footnote: 2 Mac pathnames)
  95.      
  96.      
  97.      
  98. d) Using Applescript:
  99.  
  100. There is only one additional event defined: "do_cmd". You can enter 
  101. every valid command line. The first word must be "zip" or "unzip" to
  102. select the action (compress or extraction).
  103.  
  104. See sample Applescript:
  105.  
  106.         tell application "MacZip (PPC)"
  107.             activate
  108.             with timeout of 90000 seconds
  109.                 do_cmd "zip -rjjN Volume:archive \"My Volume:*\" "
  110.             end timeout
  111.         end tell
  112.  
  113. This script opens MacZip, brings it to the foreground on the Mac, starts the zip 
  114. action with the command line: zip -rjjN Volume:archive "My Volume:*" .
  115.  
  116.  
  117.  
  118.  
  119. A short introduction is also available online:
  120. http://www.sitec.net/maczip/How-To-Do/  
  121.  
  122. It's possible to stop the run of Zip/Unzip with the well
  123. known shortcut [Command] + [.].
  124.  
  125.  
  126. ---------------------------------------------------------------------------
  127.  
  128. There are some Mac-specific switches available.
  129. Zip Module:
  130.        -df    [MacOS   only]  Include  only  data-fork  of  files
  131.               zipped into the archive.  Good for exporting  files
  132.               to  foreign operating-systems.  Resource-forks will
  133.               be ignored at all.
  134.  
  135.        -jj    [MacOS  only] record Fullpath (+ Volname). The com-
  136.               plete  path  including  volume  will  be stored. By
  137.               default the relative path will be stored.
  138.  
  139.        -S     Include system and hidden  files.  This  option  is
  140.               effective  on  some  systems only; it is ignored on
  141.               Unix.  On MacOS, this option includes finder invis-
  142.               ible files, which are ignored otherwise.
  143.  
  144. Unzip Module:
  145.        -E     [MacOS only] display contents of MacOS extra  field
  146.               during restore operation.
  147.  
  148.        -i     [MacOS only] ignore filenames stored in MacOS extra
  149.               fields.  Instead,  the  most  compatible   filename
  150.               stored in the generic part of the entry's header is
  151.               used.
  152.  
  153.        -J     [MacOS only] ignore MacOS extra fields.  All Macin-
  154.               tosh  specific  info  is  skipped.  Data-fork   and
  155.               resource-fork are restored as separate files.
  156.  
  157.  
  158. Select [File]->[Get Help on Zip/Unzip] for a complete list 
  159. of switches.
  160.  
  161.  
  162.  
  163. Limitations / Problems:
  164. -----------------------
  165.  
  166.     - Aliases are not supported. I tried, but I got broken aliases
  167.       This port will silently ignore all aliases.
  168.       It's on my to-do list for future releases.
  169.  
  170.     - Zip needs much memory to compress many files:
  171.       You may need to increase the 'Preferred Size' in 'Get Info'.
  172.       Values of 12 Megabytes or more are possible
  173.  
  174.     - Unzip needs about 500 Kbyte of memory to unzip no matter
  175.       how many files were compressed and expanded.
  176.  
  177.     - and finally one big macintosh-related problem:
  178.       This port has one weak point: It's based on pathnames.
  179.       As you may be already know: Pathnames are not unique on a Mac !
  180.       The main reason is that an attempt to implement support exact saving of
  181.       the MacOS specific internal file-structures would require a throughout
  182.       rewrite of major parts of shared code, probably sacrifying compatibility
  183.       with other systems.
  184.       I have no solution at the moment. The port will just warn you if you try
  185.       zip from / to a volume which has a duplicate name.
  186.       MacZip has problems to find the archive or the files.
  187.       My (Big) recommendation: Name all your volumes with a unique name and
  188.       MacZip will run without any problem.
  189.  
  190.  
  191. Known Bugs:
  192.  
  193.     - crypted files in a zip archive are sometimes corrupt:
  194.       I get an error message: invalid compressed data to inflate.
  195.       Appearance of this error is purly be change:
  196.       I did a small test: Unzipping an archive containing 3589 files
  197.       56 files fails to unzip, so about 1.5%.
  198.       Rootcause is completly unclear to me :(
  199.       
  200. I strongly recommend to test your archive (eg. unzip -t archive).
  201.  
  202.  
  203.  
  204.  
  205. Zip-Programs / Macintosh Extra-Data:
  206. -----------------------------------------
  207. A brief overview:
  208. Currently, as far as I know, there are 4 Zip-Programs available 
  209. for the Macintosh platform.
  210. These programs build (of cause) different variants of Zip-Files:
  211.  
  212.     - Info-Zip's first Port of Zip. Ported by Johnny Lee
  213.       This Port is rather outdated and no longer supported (since 1992).
  214.       68K only. Only minimal Mac-info is stored (Creator/Type,
  215.       Finderattributes). Creator/Type: '????' / '????'
  216.       Until year 1998, Only Unzip 5.32 survived.
  217.  
  218.     - ZipIt by Tom Brown. This is Shareware and still supported I think.
  219.       ZipIt has a nice GUI, but I found it can't handle large Zipfiles
  220.       quite well. ZipIt compresses Macintosh files using the MacBinary
  221.       format. So, transfering files to other platforms is not so easy.
  222.       Only minimal Mac-info is stored (Creator/Type, Finderattributes).
  223.       Macfilenames are changed to a most compatible filename.
  224.       Creator/Type: 'ZIP ' / 'ZIP '
  225.  
  226.     - PKZIP/mac v2.03/210d. This is Shareware.
  227.       This Zip implementation for the Mac can be found on ASI's website
  228.       (http://www.asizip.com/products/products.htm).  The name of this
  229.       program is misleading, it is NOT a product from PKWARE.  ASI last
  230.       release version is v2.03, and they also offer a newer beta version
  231.       PKZIP/mac 210d. But even the Beta version is rather outdated (1995).
  232.       Only minimal Mac-info is stored (Creator/Type, Finderattributes).
  233.       The Zipfile format looks like incompatible to other platforms.
  234.       (More details about the compatibility issue can be found in
  235.       proginfo/3rdparty.bug!). Type: 'PKz1'
  236.       Macfilenames are restored without any change.
  237.  
  238. and finally:
  239.     - Info-Zip's latest Port of Zip. MacZip 1.0. Ported by me :-)
  240.       It is supported (of cause) and up to date. Fullset of macintosh
  241.       info is stored: Creator/Type, Finderattributes, Findercomments,
  242.       MacOS 8.0 Foldersettings, Icon/Folder-Positions ...
  243.       Macfilenames are restored without any change.
  244.       Creator/Type: 'IZip' / 'ZIP '
  245.       
  246.  
  247. Compatibility of my port; Extraction:
  248.    - Archives from Info-Zip's first port (by Johnny Lee) are still compatible.
  249.    - Extraction of ZipIt archives are supported. This support is not 
  250.      complete: Filenames are korrect but Directory names are sometimes mangled
  251.      to a dos compatible form. Segmented archives are not supported.
  252.    - PKZiP/mac archives-files are extracted without resource-forks
  253.      and without any Finderinfo. I have no information about that zip-format.
  254.  
  255. Compatibility of my port; Compression:
  256.    - My port supports only the new Info-Zip format
  257.      (introduced with this port). Therefore archives created by MacZip 1.0
  258.      (1999) must be extracted with this version or later releases of Info-ZIP's
  259.      UnZip to restore the complete set of Macintosh attributes.
  260.  
  261. Note: This port is complete unrelated to the shareware ZipIt. Even more,
  262. handling of special Macintosh attributes is incompatible with ZipIt.
  263. This port (MacZip) may be used to extract archives created by ZipIt,
  264. but make sure that you get the result as you expected.
  265.  
  266.  
  267.  
  268. Macintosh Files; File Forks:
  269. ----------------------------
  270.  
  271. All Macintosh files comprise two forks, known as the data fork and the
  272. resource fork.  Unlike the bytes stored in the resource fork, the bytes in
  273. the data fork do not have to exhibit any particular internal structure.
  274. The application is responsible for interpreting the bytes in the data fork
  275. in whatever manner is appropriate. The bytes in the resource fork usually
  276. have a defined internal structure and contain data object like menus,
  277. dialog-boxes, icons and pictures.
  278. Although all Macintosh files contain both a data fork and a resource fork,
  279. one or both of these forks may be empty.
  280.  
  281. MacZip stores data-forks and resource-forks separatly. The Zipfile-Format
  282. does not allow to store two archive entries using exactly the same name.
  283. My solution is to modify the Pathname of the resource-fork. All resource-fork
  284. names are prepended with a leading special directory named "XtraStuf.mac".
  285. So, when extracting on a Mac, you should never see this directory
  286. "XtraStuf.mac" on your *disk*.
  287.  
  288. On all foreign systems that support directories in filenames (e.g: OS/2, Unix,
  289. DOS/Windows, VMS) you will get a directory "XtraStuf.mac" when extracting
  290. MacZip archives.
  291. You can delete the complete directory "XtraStuf.mac" since Mac-resources
  292. do not make much sense outside the MacOS world.
  293.  
  294.  
  295.  
  296. Textencoding; Charsets of the Filenames:
  297. ----------------------------------------
  298.  
  299. The following information is only important if you plan to transfer
  300. archives across different platforms/language systems:
  301.  
  302. A typical Zip-archive does not support different charsets. All filenames
  303. stored in the public area (= accessible by foreign systems other
  304. than MacOS) must be coded in the charset ISO-8859-1 (CP1252 in the Microsoft
  305. Windows world) or CP850 (DOSLatin1). The latter should only be used by
  306. Zip programs that mark the archive entries as "created under DOS".
  307. Apart from Macs, the commonly used platforms either support ISO-8859-1
  308. directly, or are compatible with it.
  309. To achieve maximum compatibility, MacZip convert filenames from the
  310. Mac OS Roman character set to ISO-8859-1 and vice versa.
  311. But not every char of the charset MacRoman has their equivalent
  312. in ISO-8859-1. To make the mapping in most cases possible, I chose
  313. most similar chars or at least the MIDDLE DOT. 
  314.  
  315. Mac OS Roman character set is used for at least the following Mac OS
  316. localizations:
  317. U.S., British, Canadian French, French, Swiss French,
  318. German, Swiss German, Italian, Swiss Italian, Dutch,
  319. Swedish, Norwegian, Danish, Finnish, Spanish, Catalan,
  320. Portuguese, Brazilian, and the default International system.
  321.  
  322. In all Mac OS encodings, character codes 0x00-0x7F are identical to
  323. ASCII, except that
  324.   - in Mac OS Japanese, yen sign replaces reverse solidus
  325.   - in Mac OS Arabic, Farsi, and Hebrew, some of the punctuation in this
  326.     range is treated as having strong left-right directionality,
  327.     although the corresponding Unicode characters have neutral
  328.     directionality
  329. So, for best compatibility, confine filenames to the standard
  330. 7-bit ASCII character set.
  331.  
  332. If you generate a filename list of your archive (unzip -l), you will
  333. see the converted filenames. Your can also extract the archive with
  334. the switch '-i' (= ignore mac filenames), and test your result.
  335.  
  336. This MacZip-port uses its own filename stored in the archive.
  337. At the moment, the filename will be not converted. However,
  338. I'm planning to add support for unicode.
  339.  
  340. Currently, the following Mac OS encodings are NOT supported:
  341. Japanese, ChineseTrad, Korean, Arabic, Hebrew, Greek, Cyrillic,
  342. Devanagari, Gurmukhi, Gujarati, Oriya, Bengali, Tamil, Telugu
  343. Kannada, Malayalam, Sinhalese, Burmese, Khmer, Thai, Laotian,
  344. Georgian, Armenian, ChineseSimp, Tibetan, Mongolian, Ethiopic,
  345. Vietnamese, ExtArabic and finally:
  346. Symbol - this is the encoding for the font named "Symbol". 
  347. Dingbats - this is the encoding for the font named "Zapf Dingbats".
  348. If you extract an archive coded with one of these charsets
  349. you will propably get filenames with funny characters. 
  350.  
  351. These problems apply only to filenames and NOT to the file
  352. content.
  353. Of cause: The content of the files will NEVER be converted !!
  354.  
  355.  
  356.  
  357. File-/Creator Type:
  358. -------------
  359.  
  360. This port uses the creator type 'IZip' and it is registered at Apple
  361. (since 08. March 1998). File types can not be registered any more.
  362. This port uses 'ZIP ' for Zip archive files.
  363. The creator 'IZip' type should be used for all future versions.
  364.  
  365.  
  366.  
  367. Hints for proper restoration of filetime stamps:
  368. ------------------------------------------------
  369.  
  370. UnZip requires the host computer to have proper timezone information in
  371. order to handle certain tasks correctly (see unzip.doc).  To set the
  372. timezone on the Macintosh, go to the Map Control Panel and enter the
  373. correct number of hours (and, in a few locales, minutes) offset from
  374. Universal Time/Greenwich Mean Time.  For example, the US Pacific timezone
  375. is -8 hours from UTC/GMT during standard (winter) time and -7 hours from
  376. UTC/GMT during Daylight Savings Time.  The US Eastern timezone is -5 hours
  377. during the winter and -4 hours during the summer.
  378.  
  379. Discussion of Daylight Savings Time
  380. -----------------------------------
  381. The setting in the Date & Time control panel for Daylight Savings time 
  382. is a universal setting. That is, it assumes everybody in the world is 
  383. observing Daylight Savings time when its checkbox is selected.
  384.  
  385. If other areas of the world are not observing Daylight Savings time when 
  386. the checkbox is selected in the Date & Time control panel, then the Map 
  387. control panel will be off by an hour for all areas that are not recognizing
  388. Daylight Savings time.
  389.  
  390. Conversely, if you set the Map control panel to an area that does not observe
  391. Daylight Savings time and deselect/uncheck the checkbox for Daylight Savings 
  392. time in the Date & Time control panel, then time in all areas celebrating 
  393. Daylight Savings time will be off by an hour in the Map control panel.
  394.  
  395. Example:
  396.      In the case of Hawaiians, sometimes they are three hours
  397.      behind Pacific Standard Time (PST) and sometimes two hours
  398.      behind Pacific Daylight Time (PDT). The Map control panel
  399.      can only calculate differences between time zones relative
  400.      to Greenwich Mean Time (GMT). Hawaii will always show up as
  401.      three hours past the Pacific time zone and five hours past
  402.      the Central time zone.
  403.  
  404.      When Hawaiians are not observing Daylight Savings time, but
  405.      the rest of the country is, there is no combination of
  406.      settings in Map and Date & Time control panels which will
  407.      enable you to display Hawaiian local time correctly AND
  408.      concurrently display the correct time in other places that
  409.      do observe Daylight Savings time.
  410.  
  411.      The knowledge about which countries observe Daylight Savings
  412.      time and which do not is not built into the Map control
  413.      panel, so it does not allow for such a complex calculation.
  414.  
  415.      This same situation also occurs in other parts of the world
  416.      besides Hawaii. Phoenix, Arizona is an example of an area of
  417.      the U.S. which also does not observe Daylight Savings time.
  418.  
  419. Conclusion:
  420. MacZip only know the GMT and DST offsets for the current time, not 
  421. for the time in question.
  422.  
  423.  
  424. Projects & Packages:
  425. --------------------
  426.  
  427. A Note to version numbers: Version of MacZip is currently 1.00 and
  428. is based on the zip-code version 2.3 and unzip-code version 5.4.
  429. See About-Box for current version and compiler build-date.
  430.  
  431. Because of the amount of sources I splitted this port into
  432. serveral projects. See http://www.sitec.net/maczip for updates.
  433.  
  434. - core source parts:
  435.     unzxxx.zip
  436.     zipxxx.zip
  437.       These archives contains the main-parts of the port. You can build
  438.       libraries and a standalone-App with Metrowerks standard console SIOUX.
  439.       They contain only sources, no executables.
  440.       These archives are exact copies of the standard Info-ZIP source
  441.       distributions; they were only repacked under MacOS using MacZip,
  442.       with one minor addition: For those files that are stored in BinHex'ed
  443.       format in the Info-ZIP reference source archives, unpacked version
  444.       that are ready for use have been added.
  445.  
  446. - additional source part:
  447.     MacZipxxx.zip: contains all the GUI-staff and the project-files to
  448.       build the main-app.  Only sources of the GUI, no zip- or unzip-code.
  449.       To build MacZip successfully you will need to also download the zip-
  450.       and unzip-packages.
  451.  
  452. - executables:
  453.     MacZipxxxnc.hqx: contains only executables and some docs,
  454.                       version without en-/decryption support
  455.     MacZipxxxc.hqx:  contains only executables and some docs, Crypt version
  456.  
  457. - encryption sources:
  458.     zcryptxx.zip: To build crypt-versions of MacZip.
  459.     download from ftp://ftp.icce.rug.nl/infozip/ (and subdirectories)
  460.  
  461.  
  462.  
  463. Credits:
  464. --------
  465.  
  466. Macstuff.c and recurse.c: All the functions are from More Files.
  467. More Files fixes many of the broken or underfunctional
  468. parts of the file system. Thanks to Jim Luther.
  469. (see morefiles.doc)
  470.  
  471. MatWild.c: Originally C++ code written by JJS (jstrout@ucsd.edu).
  472.  
  473.  
  474.  
  475. ---------------------------------------------------------------------------
  476. Footnotes:
  477.  
  478. 1. wild card:      
  479.     The '*' is a wild card and means 'all files'
  480.     Just in case you don't know wild cards:
  481.     '*' is a place holder for any character.
  482.     e.g.: 
  483.     "this*" matches with "this_file" or  "this_textfile" but it
  484.     don't matches with "only_this_file" or  "first_this_textfile"
  485.     "*this*" matches with "this_file" or  "this_textfile" AND
  486.     matches with "only_this_file" or  "first_this_textfile"
  487.  
  488.  
  489. 2. Mac pathnames:
  490. The following characteristics of Macintosh pathnames should be noted:
  491.  
  492.     A full pathname never begins with a colon, but must contain at 
  493.     least one colon. 
  494.     A partial pathname always begins with a colon separator except in 
  495.     the case where the file partial pathname is a simple file or 
  496.     directory name. 
  497.     Single trailing separator colons in full or partial pathnames are 
  498.     ignored except in the case of full pathnames to volumes. 
  499.     In full pathnames to volumes, the trailing separator colon is required. 
  500.     Consecutive separator colons can be used to ascend a level from a 
  501.     directory to its parent directory. Two consecutive separator colons 
  502.     will ascend one level, three consecutive separator colons will ascend 
  503.     two levels, and so on. Ascending can only occur from a directory; 
  504.     not a file. 
  505.  
  506.  
  507.  
  508.  
  509.  
  510. ---------------------------------------------------------------------------
  511.  
  512. Dirk Haase
  513. ==========
  514.