home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / n / nulib324.zip / NULIB.DOC < prev    next >
Text File  |  1993-03-16  |  38KB  |  890 lines
  1.  
  2.  
  3. NuFile eXchange (NuFX) Archive Utility
  4. NuLib v3.2 Documentation
  5.  
  6. By Andy McFadden
  7.  
  8.  
  9.  
  10. Updated September 23, 1992
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24. Overview
  25. --------
  26.  
  27. NuLib is a shell-based NuFX archive utility, based loosely on "ARC"
  28. for the IBM PC and "ar" under UNIX.  It allows you to perform certain
  29. operations on the same archives used by ShrinkIt, including view
  30. archive contents, add to archive, extract from archive, and delete
  31. from archive.  In addition, it will list and unpack files from Binary
  32. II archives.
  33.  
  34. This program is primarily targeted at users of non-Apple II computer
  35. systems, from IBM PC compatibles to Sun workstations to Amdahl
  36. mainframes.  It will also be of use to people who use a GS/OS shell on
  37. the Apple //gs, such as APW, ORCA, or ECP-16 (although it is
  38. considerably slower than ShrinkIt).  NuLib may require more than 256K
  39. of free RAM to function properly.  Apple //gs users can use YankIt
  40. instead, which is much smaller and many times faster (though
  41. considerably less powerful).
  42.  
  43.  
  44. Background
  45. ----------
  46.  
  47. For our purposes, an archive is simply a collection of one or more
  48. files stored as a single file.  This allows groups of related files to
  49. be stored under a single filename, reducing directory clutter, and
  50. makes it possible to transfer groups of files without the use of a
  51. batch transfer utility.
  52.  
  53. To reduce the space required to store the archives and the time it
  54. takes to transfer archives, most popular archiving programs
  55. automatically compress files as they are stored.  Two popular
  56. compression methods are Huffman (variable-size codes are used, with
  57. smaller codes assigned to bytes that appear frequently) and
  58. Lempel-Ziv-Welch (LZW; finds common substrings in the file).
  59.  
  60. Popular archiving programs include "BLU" (Apple II), "ShrinkIt" (Apple
  61. II), "GS/ShrinkIt" (Apple IIgs), "ARC"/"PKARC" (MS-DOS), "PKZIP"
  62. (MS-DOS), "lharc" (MS-DOS/Amiga), "zoo" (MS-DOS/Amiga), "PackIt"
  63. (Macintosh), "StuffIt" (Macintosh), "tar" (UNIX), and "ar" (UNIX).
  64. UNIX archivers don't generally compress files; a separate program
  65. (called "compress" of all things) is usually used.  NuLib works with
  66. archives that ShrinkIt produces (NuFX).
  67.  
  68.  
  69. New Features/Bug Fixes
  70. ----------------------
  71.  
  72. Major changes since last release:
  73.  
  74. + Compression speed improvement
  75. + Can add a file as if it were a disk image
  76.  
  77.  
  78. How to Use NuLib
  79. ----------------
  80.  
  81. Usage: nulib option[suboption] archive [filespec1] [filespec2] [...]
  82.  
  83. "option" is a single character, as specified below.
  84. "suboption" is one or more characters, which modify the performance of
  85. the option (see each specific option for details).
  86. "archive" is the name of a NuFX archive.  It doesn't need to exist for
  87. the add, create, and move options.
  88. "filespecN" is the name of a file, either on disk or in the archive.
  89. More than one file may be named on the command line.
  90.  
  91. The option/suboption string may be entered in upper or lower case, and
  92. may be preceeded by a hyphen (ex: "nulib -XT0 ..." is equivalent to
  93. "nulib -xt0 ..." and "nulib xt0 ...").  Suboptions may be entered in
  94. any order.
  95.  
  96. Side note: Under APW, both the archive filename and all file
  97. specifications relating to files ON DISK are expanded by NuLib (device
  98. names, wildcards, etc).  Under UNIX, all filename expansion and
  99. wildcards are handled by the shell or the kernal.  The filenames of
  100. files in the ARCHIVE do not undergo wildcard expansion on any system.
  101.  
  102. Examples:
  103. $ nulib av foo.shk file1 subdir/file2
  104. Adds "file1" and "subdir/file2" to "foo.shk", listing each file as it
  105. is archived.
  106. $ nulib av foo.shk subdir
  107. Recursively adds all files in subdir and all files in subdirectories
  108. of subdir.
  109. $ nulib mv foo.shk =.doc    (APW)
  110. $ nulib mv foo.shk *.doc    (UNIX)
  111. $ nulib mv foo.shk *.doc    (MS-DOS)
  112. Adds all files with the suffix ".doc" to the archive "foo.shk",
  113. listing them as it goes, then deletes them from the disk.
  114. $ nulib d+ foo.shk work/
  115. Deletes all files in "foo.shk" that start with "work/"; this would
  116. likely be used to delete all files archived from the directory "work".
  117. No output is produced.
  118.  
  119.  
  120. The various options are:
  121.  
  122. *** Add/Append files:
  123.     nulib A[V][U|C<val>|S<val>][R][F<type>[/<aux>]][D] archive files
  124. Quickly appends the specified files to the end of the archive.  This
  125. option does not scan the archive to see if the files already exist,
  126. and will create a new archive file if one is not found.  This option
  127. corresponds roughly to N)ew archive or A)dd files on the ShrinkIt
  128. menu.
  129.  
  130. If you add files from the current directory or a subdirectory of the
  131. current directory, then the entire partial pathname is stored (ex:
  132. "nulib av fubar.shk foo/bar/filename" will store "foo/bar/filename" in
  133. the archive "fubar.shk.")  If you add files from directory that is not
  134. a subdirectory of the current directory, only the filename will be
  135. stored (ex: "nulib av fubar.shk ../zip/bang/filename" will store
  136. "filename" in the archive).  Unfortunately, this does not work under
  137. UNIX, since filenames are expanded by the kernel instead of by NuLib.
  138.  
  139. Wildcards are allowed, and subdirectories are recursively descended
  140. (the depth is limited only by the maximum length of a pathname and the
  141. number of files in the subdirectories), unless the R suboption is
  142. used.  The R suboption will prevent subdirectories from being
  143. processed, so that "nulib avr fubar.shk *" under UNIX will add all
  144. files in the current directory, but will not descend into any
  145. subdirectories.  The V suboption displays the filenames as they are
  146. added.
  147.  
  148. The U suboption adds a file without compressing it.  The C suboption
  149. allows you to insert a file in the archive with a specific compression
  150. algorithm (specified by the argument "value", which must immediately
  151. follow the suboption - no spaces between.  Ex: "nulib ac5v fubar.shk
  152. file1" would store "file1" in "fubar.shk" using 16-bit UNIX-style LZW
  153. compression).  "value" corresponds to the appopriate thread_format as
  154. specified in the section on compression methods.
  155.  
  156. The S suboption does not compress the file, but will store it as if it
  157. were by setting the thread_format field to "value".  One use for this
  158. is adding compressed files without having to uncompress them first
  159. (ex: "nulib as1 foo.shk file1.qq" adds a squeezed file).  This
  160. suboption could conceivably cause a NuFX extractor to crash; please
  161. don't use it unless you are sure of what you are doing.  Note also
  162. that some compression methods (like ShrinkIt LZW) require both the
  163. "compressed length" and "uncompressed length" values to be correct;
  164. use of this suboption will (incorrectly) set them both to the current
  165. file length.
  166.  
  167. Only one of U, C, or S may be specified.
  168.  
  169. The F suboption allows specification of the filetype attribute.  It
  170. should be three characters long, and will be matched against a list of
  171. standard ProDOS file types.  Common ones are "BIN" (binary), "TXT"
  172. (text), "SRC" (source code), "OBJ" (object code), "EXE" (executable),
  173. and "NON" (typeless, the default).  Both upper and lower case letters
  174. will match.
  175.  
  176. If the filetype is followed by a "/", then the auxtype field will also
  177. be set.  NuLib expects the auxtype to be a four-byte hexadecimal
  178. number; entering less than four digits could cause the auxtype to be
  179. misinterpreted.  A good example is storing APW C source files: "nulib
  180. cvfSRC/000a nulib.shk file1.c file2.c ...".
  181.  
  182. If the D suboption is given, the entry will be tweaked to make it
  183. appear that the file is actually a disk image.  This may be useful
  184. somewhere.  Don't use it if you don't know what you're doing.
  185.  
  186. Adding comments is not currently supported.
  187.  
  188.  
  189. *** Binary II Operations
  190.     nulib B[X][V][T<value>][I] binary2-archive [archived-files]
  191. This option is included for compatibility with the older Binary II
  192. standard, since it is still in use by many communications programs.
  193.  
  194. With no suboptions, this will list the information on the archived
  195. files specified by "archived-files".  The X suboption extracts the
  196. named files from the archive, unsqueezing them if necessary.  If the
  197. archived-files parameter is omitted, then all files will be listed or
  198. extracted.  Note that matches are case-independent.
  199.  
  200. When the V suboption is used in conjunction with the X suboption, the
  201. names of the archived files are printed as they are extracted.  The V
  202. suboption has no effect otherwise.
  203.  
  204. The T suboption will perform a text substitution as it works; see the
  205. section of conversion of line terminators for more information.
  206.  
  207. If the filename of an extracted file would conflict with an existing
  208. file, the file will be overwritten and a message will be printed.  If
  209. the "I" suboption is used, then NuLib will give an "overwrite (y/n)?"
  210. prompt.  An affirmative answer overwrites the file; a negative answer
  211. will skip the file and continue processing.
  212.  
  213. Attempting to perform NuFX operations on a Binary II archive will
  214. fail.  If the file appears to be Binary II format, then a message
  215. indicating this will be printed.  Providing transparent support for
  216. Binary II archives is not impossible, but isn't needed often enough to
  217. be worth doing.
  218.  
  219.  
  220. *** Create Archive
  221.     nulib C[V][U|C<val>|S<val>][R][F<type>[/<aux>]][D] archive files
  222. This is identical to the A option, but the "creating archive" message
  223. is suppressed.  This behavior is similar to "ar".
  224.  
  225.  
  226. *** Delete from Archive
  227.     nulib D[V][+] archive archived-files
  228. Deletes the named files from the archive.  NuLib scans the archive,
  229. marking all records that match the names in the file specification
  230. (case-independent).  If all files are marked for deletion, then the
  231. archive file itself is deleted.  Otherwise, a new archive is created,
  232. the unmarked records are transferred, and the old archive is deleted.
  233. An error during this process will leave the original archive
  234. unmodified.
  235.  
  236. Note that this does not require an exact match if the "+" suboption is
  237. used; "nulib d+ fubar.shk foo" will delete "foo", "Foozle",
  238. "food/recipies" and "food/stock."  The V suboption prints the list of
  239. marked records as it works.
  240.  
  241.  
  242. *** Freshen Archive
  243.     nulib F[V][U|C<val>|S<val>][R][F<type>[/<aux>]][D] archive files
  244. Updates files in the archive, but doesn't add any new files.  Creates
  245. a new archive file, and either transfers the old record or adds the
  246. file depending on which is more recent.  Only exact filename matches
  247. are allowed (case-independent), including partial paths.  The archive
  248. being updated must already exist.
  249.  
  250. Wildcards are allowed, and subdirectories are automatically expanded
  251. unless the R suboption is used.  The V suboption displays the
  252. filenames as they are added.  The U/C/S/F suboptions, explained under
  253. A)dd, only apply to files being added to the archive or being updated
  254. (files that aren't updated are left unaltered).
  255.  
  256. Files that are updated will retain their previous filetype.  New files
  257. will get either the default filetype, the filetype specified by the F
  258. suboption, or the actual filetype (under APW only) in that order.
  259.  
  260.  
  261. *** Command Help
  262.     nulib H[NWS]
  263. Displays a help screen.  Three screens are available.
  264.  
  265. "nulib h" alone displays help on the options.  The N suboption gives
  266. help with numbers; it lists the known compression methods and text
  267. translation types.  The W suboption gives a brief listing of
  268. contributors, and how to contact me.  The S suboption gives help on
  269. the suboptions.
  270.  
  271.  
  272. *** Integrity Check
  273.     nulib I[V] archive
  274. Verifies that the archive is intact.  Does not modify the archive in
  275. any way.  The V suboption prints a list of CRCs for each entire record
  276. (this is different from those listed by the TZ option, which are only
  277. for the record headers and (sometimes) threads; this includes not only
  278. the headers but *all* data as well).
  279.  
  280. Please note that this doesn't do much more than read the file, unless
  281. the record_version is $0002 or greater (which means that the data has
  282. a checksum stored; currently these records are only generated by
  283. GS/ShrinkIt), AND no compression was used.  This merely scans the
  284. records and verifies the header CRCs, NOT the data CRCs.  The main
  285. purpose of the V suboption is to make a list of CRCs that can be sent
  286. along with the archive.
  287.  
  288.  
  289. *** Move Files to Archive
  290.     nulib M[V][U|C<val>|S<val>][R][F<type>[/<aux>]][D] archive files
  291. This is identical to the A option, but the files are deleted after
  292. they are added to the archive.  Note that the actual directory files
  293. are NOT deleted, unless they were given distinct record entries.
  294.  
  295. Care should be taken to avoid trying to M)ove an archive into itself.
  296. The act of adding may (depending on the OS and the archive) go into an
  297. infinite loop creating a huge file, and the coup de grace is when
  298. NuLib then deletes the archive you were adding to.
  299.  
  300.  
  301. *** Print an Archived File
  302.     nulib P[V][T<value>][+] archive files
  303. Print the contents of an archived file without extracting it.  Useful
  304. for viewing archived text files without having to actually unpack
  305. them.  Note this only allows viewing of data_threads; resource forks
  306. and disk images will not be displayed, and comments are not shown.  I
  307. take no responsibility for pagination or filtering of funky control
  308. characters...
  309.  
  310. The V suboption will print the file's name right before it is
  311. extracted.  The + suboption allows you to specify the first part of a
  312. pathname; see the D or X options for details.
  313.  
  314. The T suboption will perform a text substitution as it works; see the
  315. section on conversion of line terminators for more information.
  316.  
  317.  
  318. *** Table of Contents
  319.     nulib T[VAZ] archive
  320. With no suboptions, this lists only the filenames of the archived
  321. files.  Not only does this make it easier to view the archive contents
  322. (the ShrinkIt format filename field is about 20 characters wide; this
  323. is as wide as it has to be), but the output is suitable for
  324. transmission via a pipe to other utilities.
  325.  
  326. Using the V suboption will make it use ShrinkIt v2.0 output format
  327. (same as using the V option); it is included as a suboption mainly for
  328. people used to "ar".  Using the A suboption will produce a list
  329. similar to the output of ARC or ZOO.
  330.  
  331. Using the Z suboption will dump everything known about the archive,
  332. including all information in headers, CRCs, relative file position,
  333. sizes of individual threads, etc.
  334.  
  335.  
  336. *** Update Archive
  337.     nulib U[V][U|C<val>|S<val>][R][F<type>[/<aux>]][D] archive files
  338. Updates files in the archive, keeping the archived file or the file
  339. listed on the command line, whichever is most recent (or exists).
  340. Unlike freshen, this will add new files as necessary.  Creates a new
  341. archive file, and either transfers the old record or adds the file.
  342. Only exact filename matches are allowed (case-independent), including
  343. partial pathnames.  The archive being updated must already exist.
  344.  
  345. Wildcards are allowed, and subdirectories are automatically expanded
  346. unless the R suboption is used.  The V suboption displays the
  347. filenames as they are added.  The U/C/S/F suboptions, explained under
  348. A)dd, only apply to files being added to the archive (files that
  349. aren't updated are left unaltered).  Note that the order of files in
  350. the archive will be preserved.
  351.  
  352. Files that are updated will retain their previous filetype.  New files
  353. will get either the default filetype, the filetype specified by the F
  354. suboption, or the actual filetype (under APW only) in that order.
  355.  
  356.  
  357. *** Verbose Archive Listing
  358.     nulib V archive
  359. Lists the archive contents in a format indentical to that used by the
  360. ShrinkIt v2.0 L)ist archive contents option.  Same thing as "-tv".
  361.  
  362.  
  363. *** Extract from Archive
  364.     nulib X[V][T<value>][U][I][M][+] archive [archived-files]
  365.     nulib E...
  366. The X and E options are synonymous.  Extract the archived-files from
  367. the archive.  If the file already exists, you are asked if you want to
  368. overwrite it.  If part of a partial pathname does not exist, the
  369. subdirectory will be created.  Omitting the "archived-files"
  370. specification will cause the entire archive to be unpacked.
  371.  
  372. When files are archived, a pathname separator is stored (e.g., "/" for
  373. ProDOS and UNIX, "\" for MS-DOS, ":" for Mac HFS).  During extraction,
  374. the pathnames are broken down into component file names, converted to
  375. names legal under the current operating system, and then recombined
  376. using the pathname separator for the current OS.  This facilitates
  377. extraction of files archived under any OS, but can lead to filename
  378. conflicts that didn't exist when the files were added (e.g., a UNIX
  379. file that contained a backslash is unpacked under MS-DOS).
  380.  
  381. If the filename of an extracted file would conflict with an existing
  382. file, the file will be overwritten and a message will be printed.  If
  383. the "I" suboption is used, then NuLib will give an "overwrite (y/n)?"
  384. prompt.  An affirmative answer overwrites the file; a negative answer
  385. will skip the file and continue processing.
  386.  
  387. Note that extraction does not require an exact match if the "+"
  388. suboption is specified; "nulib x+ fubar.shk foo" will extract "FOO",
  389. "Foozle", "food/recipies" and "food/stock."  This makes it possible to
  390. extract entire subdirectories at a time.  The V suboption prints the
  391. list of marked records.
  392.  
  393. If comments are present, then the V suboption also prints those as it
  394. extracts.  Using the M suboption will cause the comments to be
  395. printed, but the files will not be extracted.  **NOTE**: the exact use
  396. of the M suboption has not been entirely settled.  Since it may be
  397. desirable to extract comments into a file, future versions of NuLib
  398. may use eXtract to put them in a file and Print to view them.
  399. Comments welcome, caveat emptor, have a nice day.
  400.  
  401. The T suboption will perform a text substitution as it extracts; see
  402. the section on converson of line terminators for more information.
  403.  
  404. The U suboption will extract the files without uncompressing them.
  405. This is rarely useful, but is easy to implement and is present for the
  406. curious.
  407.  
  408.  
  409. Non-NuFX files
  410. --------------
  411.  
  412. NuLib will only work with Binary II and NuFX archives.  If you try to
  413. view some other kind of file, you will get an error message and an
  414. indication of what kind of file NuLib thinks it is.  NuLib can
  415. recognize files processed with compress, Zip, Zoo, StuffIt, ar, shar,
  416. GIF, and many others.
  417.  
  418.  
  419. Compression Methods
  420. -------------------
  421.  
  422. The following methods are defined in the NuFX documentation:
  423. (# = method number, Name = method name [abbreviation], Pack? and
  424. Unpack? refer to the ability of NuLib to perform that operation using
  425. the given compression method.
  426.  
  427. #    Name                             Pack?    Unpack?
  428. 00   Uncompressed [unc]                 Y         Y
  429. 01   SQueezed [squ]                     N         Y
  430. 02   Dynamic LZW I (ShrinkIt) [shk]     Y         Y
  431. 03   Dynamic LZW II (ShrinkIt) [sh2]    N         Y
  432. 04   12-bit UNIX Compress [u12]         Y         Y
  433. 05   16-bit UNIX Compress [u16]         Y         Y
  434.  
  435. Attempting to use a compression method that does not exist will result
  436. in an error message like "[can't squeeze; storing]...".  This means
  437. that the compression method you requested is unavailable, and it
  438. simply stored the file without compression.
  439.  
  440. If you try to extract a file that has been compressed with an
  441. algorithm that NuLib is not familiar with, an error message will be
  442. printed and the file will not be extracted.
  443.  
  444.  
  445. Converting Line Terminators
  446. ---------------------------
  447.  
  448. Different operating systems use different line terminators in text
  449. files.  The table below shows them for some popular systems:
  450.  
  451. Operating System         Line Terminator
  452. Apple ProDOS             CR ($0d)
  453. UNIX                     LF ($0a)
  454. MS-DOS                   CRLF ($0d0a)
  455.  
  456. While NuLib will know what kind of terminators the operating system it
  457. is running under uses, it cannot reliably determine what kind an
  458. archived file uses.  Thus, the terminator used on the system where the
  459. file was created must be specified.
  460.  
  461. Note that text translation should *not* be performed on non-ASCII
  462. files (non-ASCII means anything other than pure text; word processing
  463. files and executables are two examples of files that should *never*
  464. have text translation performed on them).  Doing so will probably ruin
  465. the file, causing strange errors.  Because of the wide range of files
  466. that NuLib must handle, it is impossible to automatically determine
  467. which files are binaries and which are text.
  468.  
  469. In order to tell NuLib what format to expect, you have to specify a
  470. value parameter (although it will default to zero if you don't).  The
  471. following examples illustrate their usage:
  472.  
  473. nulib xt0 ...       Convert from CR   (Apple II -> current system)
  474. nulib xt1 ...       Convert from LF   (UNIX -> current system)
  475. nulib xt2 ...       Convert from CRLF (MS-DOS -> current system)
  476.  
  477.  
  478. Shell Variables
  479. ---------------
  480.  
  481. NuLib looks for a shell variable called "NULIBOPT" to get default
  482. values for certain things.  This must be an environment variable
  483. ("setenv" using csh, "set" and "export" using sh or APW), and may
  484. contain the following:
  485.  
  486.      verbose             Default to Verbose output (otherwise Silent).
  487.      type=xxx            Default type for storing files (under UNIX or
  488.                          MS-DOS).  "xxx" should match the 3-letter
  489.                          ProDOS abbreviation (NON, BIN, TXT, SRC).
  490.                          Normally "NON".
  491.      aux=xxxx            Default auxtype for storing files (under UNIX
  492.                          or MS-DOS).  "xxxx" is a four-character hex
  493.                          number (000a, 8002, abcd).  Normally "0000".
  494.      interactive         Default to Interactive mode (prompt before
  495.                          overwriting files).
  496.      compress=n          Set default compression to type n.  This is
  497.                          useful if you prefer 16-bit UNIX compress
  498.                          (which would be compress=5).
  499.  
  500. Note that the type= and aux= settings do NOT apply when running under
  501. APW.  Files will be stored with their actual filetypes, regardless of
  502. the variable setting.
  503.  
  504. Also, the 'F' suboption will override these settings.
  505.  
  506. An example from csh:
  507.   setenv NULIBOPT type=BIN,compress=5,interactive
  508.  
  509. ** WARNING: As of this writing, GS/ShrinkIt 1.0.6 and ShrinkIt v3.4
  510. are not able to extract archived files compressed with UNIX compress.
  511. It is likely that GS/ShrinkIt will be able to in the future, but the
  512. //e version of ShrinkIt will probably never handle them.
  513.  
  514.  
  515. Error Handling
  516. --------------
  517.  
  518. Many errors simply cause the program to exit, leaving the archive in
  519. an uncertain state (which sounds fairly evil).  If you were
  520. extracting, deleting, viewing, or updating when the error occurred,
  521. the worst that can happen is you will be left with a bogus temporary
  522. file in the current directory (something like "nulib.tmp5610").
  523.  
  524. If you were adding to an existing archive, the files that were there
  525. will be unharmed, but additional files will not appear, and the
  526. archive will be oversized.  This is because the master header block
  527. (which keeps a count of the number of records in the archive) is
  528. written last.
  529.  
  530. If you were creating a new archive, the file will be guano.  This is
  531. because, as mentioned before, the Master Header Block is not written
  532. until the very end.  Since NuLib identifies NuFX archives by looking
  533. at certain bytes in the MHB, the file will not be identifiable as
  534. NuFX.  Note that the M)ove option is safer than it looks, because
  535. files on disk are not deleted until the archive is safely closed.
  536.  
  537.  
  538. Revision History
  539. ----------------
  540.  
  541. NuLib v3.22 (September 1992)
  542. - improved speed of LZW-I compression
  543. - added ability to add files as if they were disks (patches provided
  544. by somebody whose name I've lost)
  545. - updated the list of 3-letter filetype abbreviations
  546.  
  547. NuLib v3.21 (August 1992)
  548. - minor stuff
  549.  
  550. NuLib v3.2 (April 1992)
  551. - fixed two bugs in the LZW-II uncompression.
  552. - made it compatible with SysV Expanded Fundamental Types (stuff like
  553. eight byte file offsets on lseek()s).
  554.  
  555. NuLib v3.11 - v3.14 (November 1991)
  556. - fixed a problem with LZW-II uncompression.
  557. - added fixes to make it compile on a NeXT and with MS C 6.0.
  558. - fixed XENIX directory compatibility problems.
  559.  
  560. NuLib v3.1 (October 1991)
  561. - added ability to uncompress LZW-II compression (GS/ShrinkIt).
  562. - improved speed of compression routines.
  563. - improved System V compatibility.
  564. - cleaned up code a bit and fixed minor bugs.
  565.  
  566. Nulib v3.01 - v3.03 (February 1991)
  567. - fixed XENIX problems with includes and libs.
  568. - fixed bug in directory expansion.
  569. - silenced screaming about bad dates.
  570. - fixed glitches in nulib.lnk and nulib.mak
  571. - fixed non-compression bug in ShrinkIt LZW.
  572.  
  573. NuLib v3.0 (Sep 1990):
  574. - added ability to compress files using ShrinkIt LZW-I compression
  575. (replaces "fake" compression used previously).
  576. - added "compress" parameter to NULIBOPT environment variable.
  577. - added ARCZOO output format for people used to MS-DOS archivers.
  578. - added M suboption for comment ("message") printing.
  579.  
  580. NuLib v2.3 (May 1990 - not released):
  581. - addition of UNIX compress.
  582. - threw in some benchmarks.
  583.  
  584. NuLib v2.2 - v2.22 (Apr 1990):
  585. - second release as NuLib (after a brief vacation).
  586. - fixed incompatibility problems with GS/ShrinkIt and ShrinkIt v3.0.
  587. - added some support for comments.
  588. - unpacks disk archives to files (good for the UNIX Apple ][+
  589. simulator).
  590. - fake compression correctly handles files that don't compress (it
  591. used to store them as compressed whether or not they got smaller).
  592. - various minor changes/improvements (more help screens, etc).
  593.  
  594. NuLib v2.1.1 (Nov 1989):
  595. - first wide distribution as NuLib.
  596. - fixed command processing bugs.
  597.  
  598. NuLib v2.1 (Nov 1989):
  599. - yet another name change (thanks loads, L&L).
  600. - ShrinkIt LZW uncompression added.
  601. - MS-DOS code added.
  602. - shell variable used for defaults.
  603. - CRLF translation.
  604. - added R, I, and F suboptions.
  605.  
  606. CShrink v2.08 (Oct 1989):
  607. - altered help screens, some commands.
  608. - added recognition of other kinds of files (compressed, shar, etc).
  609. - switched to table lookups for calculating CRC (much faster).
  610.  
  611. CShrink v2.07 (Sep 1989):
  612. - Another name change (legal reasons).
  613. - UNIX port completed.
  614. - Binary II operations are fully functional.
  615. - some compression code added (unSQueeze, fake ShrinkIt pack).
  616. - '+' suboption added.
  617. - text translation improved.
  618. - printing of archived files (P option) now works.
  619.  
  620. NuARC v2.03 (Aug 1989):
  621. - first NuARC distribution (APW executable only).
  622. - added subdirectory expansion.
  623. - added suboption processing.
  624. - replaced buffered I/O (fopen(), fread(), etc) on files with
  625. lower-level read()/write() routines.
  626. - added automatic byte-order determination.
  627. - implemented move, extract all, and update/freshen.
  628. - added Print archived file option.
  629. - added Verbose, Text translation, and Uncompressed storage
  630. suboptions.
  631. - wrote this documentation.
  632.  
  633. NuARC v2.0 (Aug 1989):
  634. - added archive manipulation routines (EXtract, Add and Delete for
  635. uncompressed archived files).
  636. - added filename-only output format.
  637. - added CRC verification.
  638. - added byte order and data element size checks.
  639. - removed the LAMESEEK option.
  640.  
  641. NuView v1.2 (July 1989):
  642. - major overhaul of all source code to make it work under APW C.
  643. - new //gs-specific routines added.
  644. - minor alterations to output format.
  645.  
  646. NuView v1.1 (June 1989):
  647. - major rewrite of the way archives are read (had problems with
  648. machines requiring word-alignment of data).
  649. - added thread file position storage to internal archive structure.
  650. - fixed non-(void) sprintf() bug.
  651.  
  652. NuView v1.0 (May 1989):
  653. - initial release.
  654. - works only on a Sun 3/50 running BSD UNIX.
  655.  
  656.  
  657. Limitations
  658. -----------
  659.  
  660. NuLib works just fine with records containing more than one thread
  661. (i.e., comments and resource forks).  However, while comments can be
  662. printed, they can't be added.
  663.  
  664. The big problem this program has is speed.  Since it is meant to be
  665. portable first and efficient second, it won't run as fast as something
  666. like ShrinkIt (written entirely in assembly).  What I envision is
  667. people using ShrinkIt at home on their Apple //s, but NuLib on UNIX
  668. systems or other microcomputers.  This will facilitate transfers of
  669. large compressed files, which can then be quickly unpacked on the
  670. destination system (which will likely have greater computing power, or
  671. a C compiler more efficient than APW).
  672.  
  673.  
  674. System Dependencies
  675. -------------------
  676.  
  677. When compiling this on a Sun 3/50, I noticed a problem: the byte
  678. ordering for the //gs (65816) and the Sun (68020) are backward.  The
  679. present version of NuLib will automatically determine the byte
  680. ordering and treat data appropriately (although this may fail if the
  681. data size definitions are wrong).
  682.  
  683. There are definitions for one byte, two byte, and four byte variable
  684. types; my compiler uses char, short, and long.  If these are different
  685. for your compiler, be sure to change the typedefs in "nudefs.h".  If
  686. you don't have 8-bit bytes, though, it may not work (most machines
  687. do).
  688.  
  689. Notes on UNIX implementation:
  690. If this is being run under UNIX, you should #define UNIX in
  691. "nudefs.h".  This will enable certain UNIX functions (like system()
  692. calls and time routines), and disable others (like file types and
  693. "binary mode" for file I/O).  If this is being run under BSD UNIX, you
  694. should also #define BSD43 in "nudefs.h"; certain small differences
  695. were unavoidable (strrchr() vs rindex()).  System V users should
  696. #define SYSV.  See "nudefs.h" for examples.
  697.  
  698. Under APW, breaking down the full pathnames into relative pathnames is
  699. easy (and should be under MS-DOS as well...).  Under UNIX ".." is an
  700. actual directory link, so obtaining a fully expanded pathname with no
  701. redundancies is difficult.  Thus, storing "dir1/../dir1/foo" would
  702. appear as "dir1/foo" under APW but "dir1/../dir1/foo" under UNIX.
  703. Care must be taken when extracting such files on non-UNIX systems;
  704. they are best avoided entirely.  One nasty pitfall is using "~/foo"
  705. under the C shell...
  706.  
  707. If the UNIX owner access permissions include write permission, the
  708. file will be stored as unlocked.  If write permission is denied, it
  709. will be stored as locked.  As far as dates are concerned, the
  710. modification and access times will both be set to the modification
  711. time.
  712.  
  713. Notes on //gs implementation:
  714. There is very little //gs-specific code, except where absolutely
  715. necessary (time routines, file type handling, etc).  GS/OS support is
  716. absent (extended files are not handled yet, different file systems are
  717. not recognized, and pseudo-mixed-case ProDOS filenames are stored as
  718. upper case).  Some of the faults belong to APW...
  719.  
  720. Unfortunately, the startup code (2/start) provided with APW and the
  721. methods of argument passing used by ECP-16 and ProSel-16 aren't
  722. compatible.  This means that you can run NuLib from ECP or ProSel, but
  723. you can't pass it any arguments (which pretty much defeats the
  724. purpose...).
  725.  
  726. At any rate, the program is linked with the compression routines in
  727. dynamic load segments, so that simple operations should run faster.
  728. Additionally, it should be restartable from memory.  [actually, the
  729. ZapLink version doesn't have dynamic segments...]
  730.  
  731. There is a bug (not my fault) when using the P option to print a file.
  732. The file gets printed on one line for some reason...  If you redirect
  733. the I/O to a file, everything comes out fine.  Weird.
  734.  
  735. APW shell-specific code has been avoided where possible.  Places where
  736. I couldn't easily work around it include wildcard expansion and
  737. ERROR().  It was deliberately used in several places to allow the user
  738. to STOP() processing with Apple-period.
  739.  
  740. NOTE: NuLib was written to work with APW C, ** NOT **  Orca/C.
  741. Attempting to compile it with Orca/C would be a major undertaking (as
  742. several people who have tried and failed can attest to).
  743.  
  744. Notes on MS-DOS implementation:
  745. The user interface may be slightly different from the UNIX and APW
  746. versions, so that MS-DOS users will feel more at home when using the
  747. program.  The only major deviation is in the handling of subdirectory
  748. expansion.
  749.  
  750. A future version may select the ARC/ZOO output format as default.
  751.  
  752.  
  753. Bugs / Glitches
  754. ---------------
  755.  
  756. UNIX lseek uses longs, which are usually four bytes.  Signed.  If an
  757. archive is larger than 2 gigabytes, there may be a problem (cough).
  758. This isn't a problem if the system has EFT.
  759.  
  760. Pathnames longer than the #defined maximum (1024 bytes) will not be
  761. processed.  This is the limit on most machines, and is well in excess
  762. of most people's sanity.  Pathnames with a null ('\0') in them should
  763. generally be avoided.
  764.  
  765. Some partial pathname comparisons may fail because pathname separators
  766. vary between operating systems.  File naming conventions can result in
  767. collisions (ex: "foo+" and "foo~" are unpacked under ProDOS, where
  768. both are translated to "foo.").  Also, you will probably need to be in
  769. the same directory each time you U)pdate an archive, or else the
  770. partial pathnames won't match (update requires an EXACT match), and
  771. you'll end up with two different copies of the same file.
  772.  
  773. A maximum of 255 files may be added/deleted/whatever at at time.
  774. Expanded subdirectories count.  This is an arbitrary number and is
  775. easy to change if someone can convice me that you'd need to archive
  776. more than 255 files at a time.
  777.  
  778. The same file may be added/extracted/whatever more than once if the
  779. user enters multiple file selectors on the command line ("nulib av
  780. foo.shk file1 file1 file1").  This means that U)pdate could insert the
  781. same file twice, etc.
  782.  
  783. NuLib does not at present prevent an archive from being added to
  784. itself.  This can have unfortunate consequences, especially in
  785. conjunction with the M)ove option.
  786.  
  787. The ProDOS three-letter filetype names may or may not be the offical
  788. Apple versions.  Some users may have problems with things like "$00"
  789. because '$' is a csh metacharacter (job control).
  790.  
  791. Error output is informative but ugly (mostly debugging-type messages).
  792. Error handling is somewhat fatal in most cases.
  793.  
  794. The code is fairly large, currently around 260K (around 7000 lines of
  795. C).  It takes a while to compile it, and can be difficult if you only
  796. have 1.25MB of RAM (kill your DAs and purge before you link!)
  797.  
  798.  
  799. In the Works
  800. ------------
  801.  
  802. This is a wishlist of sorts.  Don't hold your breath:
  803. - Allow CR <-> LF translation when ADDING files.
  804. - Improve GS/OS handling.  Need to handle resource forks and file
  805. system IDs. Would probably help if I had a GS/OS reference...
  806. - Add to thread methods (insert ASCII messages, etc).
  807. - Add different compression methods (LZH?).
  808.  
  809.  
  810. Author Info
  811. -----------
  812.  
  813. I'm currently an Associate Software Engineer for Amdahl Corp. in Santa
  814. Clara, California.
  815.  
  816. e-mail: fadden@uts.amdahl.com (Andy McFadden)
  817.  
  818. No relation to the author of ShrinkIt and NuFX, Andy Nicholas.  This
  819. was and continues to be my idea; throw all kudos and blame in my
  820. general direction.  All code herein is mine, developed from the NuFX
  821. Documentation Revisions three through five (the latter from Call
  822. -A.P.P.L.E.), except as noted below.
  823.  
  824. Dynamic LZW-I (ShrinkIt) by Kent Dickey.  LZW-II compression (LZW-I
  825. with table clears) designed by Andy Nicholas.  C implementation by
  826. Frank Petroski and Kent Dickey (independently and simultaneously).
  827.  
  828. MS-DOS code by Robert B. Hess and Bruce Kahn.
  829.  
  830. The Binary II routines and the unSQueeze code were adapted from the C
  831. source by Marcel J.E. Mol (usq.c based on usq2/sq3 by Don Elton).
  832.  
  833. UNIX compress code from COMPRESS v4.3 (see source for detailed author
  834. information).
  835.  
  836. If you have suggestions or comments and can't send mail to my Internet
  837. address, you can send US mail to:
  838. Andy McFadden
  839. 1474 Saskatchewan Dr.
  840. Sunnyvale, CA  94087
  841.  
  842. Andy Nicholas, the author of ShrinkIt and affiliated products
  843. (ShrinkIt ][+, UnshrinkIt ][+, GS/ShrinkIt), may be contacted at:
  844.      Internet    :  shrinkit@Apple.COM
  845.      CompuServe  :  70771,2615
  846.      GEnie and
  847.       America OL :  shrinkit
  848.  
  849.  
  850. Legal Stuff
  851. -----------
  852.  
  853. (I'm not sure about all of these, but I'd like to cover all the
  854. bases):
  855.  
  856. ShrinkIt is a trademark of L&L Productions, Inc (...or is it?).
  857. ARC is owned by SeaWare.
  858. Apple is a tradmark of Apple Computer, Inc.
  859. MS-DOS is (probably) a trademark of Microsoft, Inc.
  860. PKZIP is (probably) a trademark of PKWare.
  861.  
  862. I have not seen source code for ShrinkIt(tm) or for the compression
  863. routines used within it, except as provided to me in C by Kent Dickey.
  864.  
  865. Disclaimers, borrowed from Dave Whitney and Andy Nicholas:
  866.  
  867. This program is FREEWARE; both source and binaries may be distributed
  868. freely, but not sold.  If you wish to include NuLib in the
  869. distribution of a commercial product, you will need to get my
  870. permission beforehand.
  871.  
  872. Distribute as widely as possible, but please include this
  873. documentation with the binaries and/or sources.
  874.  
  875. Copyright (C) 1989-1991 by Andy McFadden. All rights reserved.
  876.  
  877. I (Andy McFadden) MAKE NO WARRANTY ON THIS MANUAL OR SOFTWARE, EITHER
  878. EXPRESS OR IMPLIED, WITH RESPECT TO QUALITY, MANUAL'S ACCURACY,
  879. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
  880.  
  881. IN NO EVENT WILL I BE HELD RESPONSIBLE FOR DIRECT, INDIRECT, SPECIAL,
  882. INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OF THE
  883. SOFTWARE OR INACCURACY IN THE MANUAL.
  884.  
  885. In other words, I have tested the program to the best of my ability,
  886. and I find that as distributed by me, it is safe for general use. It
  887. isn't necessarily bug-free, and as a result, loss of data, however
  888. unlikely, is entirely possible. Use at your own risk, but also for
  889. your own enjoyment.
  890.