.!
.!  File:	UNZIP_CLI.HELP
.!
.!  Author:	Hunter Goatley
.!
.!  Date:	12 Jul 94 (orig. UNZIP.RNH, 23 Oct 91)
.!
.!  Description:
.!
.!	TPU-processable source file to produce VMS on-line help for
.!	portable UnZip.  Adapted from UNZIP.RNH, originally based on
.!	UNZIP.MAN (now UNZIP.DOC).
.!
.!	To build:
.!	    $ EDIT /TPU/NOSECTION/NODISPLAY/COMMAND=CVTHELP.TPU UNZIP_CLI.HELP
.!	    $ REN UNZIP_CLI.RNH UNZIP.RNH
.!	    $ RUNOFF UNZIP.RNH
.!	    $ LIBR /HELP/INSERT libr UNZIP
.!
.!  Modification history:
.!
.!	02-001		Hunter Goatley		12-JUL-1994 16:59
.!		Genesis.
.!	02-002		Cave Newt		14-JUL-1994 11:36
.!		Fixed /*TEXT options and added/removed various options.
.!	02-003		Cave Newt		28-JUL-1994 08:54
.!		Removed semicolons from comments and moved /ZIPINFO.
.!	02-004		Christian Spieler	06-OCT-1995 02:02
.!		Changed to conform to revised .CLD definition.
.!	02-005		Christian Spieler	06-FEB-1996 02:20
.!		Added description of /HELP qualifier.
.!
<INIT>
<MAIN>
UNZIP

UnZip is used to extract files compressed and packaged by Zip (see HELP ZIP
for information on ZIP).

For a brief help on Zip and Unzip, run each without specifying any
parameters on the command line (or apply the /HELP qualifier).

UNZIP will list, test, or extract from a ZIP archive.  ZIP archives are commonly
found on MS-DOS systems; a VMS version of ZIP can also be found here.

Archive member extraction is implied by the absence of the -c, -p, -t, -l, -v or
-z options.  All archive members are processed unless a filespec is provided to
specify a subset of the archive members.
<FORMAT>
UNZIP zipfile [file[,...]] [/qualifiers]

.!
<TOPIC>
Parameters

<PARAMETER>
zipfile

<PTEXT>
File specification for the ZIP archive(s) with optional wildcards. UnZip will
perform actions specified for every zipfile matching the specification.
The default file specification is SYS$DISK:[].ZIP.

Note that self-extracting ZIP files are supported; just specify the .EXE
suffix yourself.
<TXETP>

<PARAMETER>
file

<PTEXT>
An optional comma-separated list of archive members to be processed;
if no list is given, all archive members are processed.  Expressions
may be used to match multiple members.  Expressions should be enclosed
in double-quotes to prevent interpretation by DCL.  Multiple filenames
should be separated by blanks.  Each file specification is similar to
a Unix egrep expression and may contain:

<LITERAL>
|*       matches a sequence of 0 or more characters
|?       matches exactly 1 character
|[...]   matches any single character found inside the brackets;
|        ranges are specified by a beginning character,
|        a hyphen, and an ending character.  If a '!' or '^'
|        immediately follows the left bracket, then any character
|        not in the given range is matched.
<LARETIL>
<TXETP>

<QUALIFIERS>
<QUALIFIER>
/ZIPINFO

/ZIPINFO

Displays information about the Zip archive and the files contained therein.
This function used to be provided by a separate ZipInfo program.

The following qualifiers may be specified with /ZIPINFO:

<LITERAL>
|  /SHORT     Short UNIX "ls -l" format (default)
|  /MEDIUM    Medium UNIX "ls -l" format
|  /LONG      Long UNIX "ls -l" format
|  /ONE_LINE  Filenames only, one per line
|  /VERBOSE   Verbose, multi-page format
|  /HEADER    Print header lines
|  /TOTALS    Print totals for files
|  /TIMES     Print file times in sortable decimal format
|  /[NO]PAGE  Page screen output through built-in "more"
<LARETIL>
<QUALIFIER>
/BINARY

/BINARY[=KEYWORD]
/NOBINARY (default)

Selects conversion to VMS "standard" binary file format, which is
"fixed length 512 byte records, no record attributes".
The optional keywords recognized are:
<LITERAL>
|  AUTO      Automatically extracts files marked as "binary" (rather than
|            "text") in in standard VMS binary file format. (default)
|  ALL       Extracts all files in standard VMS binary file format.
|  NONE      Same as /NOBINARY.
<LARETIL>

Note that a combination of /BINARY[=AUTO] and /TEXT[=AUTO] is allowed.
(see /TEXT qualifier)
<QUALIFIER>
/BRIEF

/BRIEF (default)

When used with /LIST, specifies that a brief listing of the archive's
contents is to be displayed.  A brief listing shows the length, date,
time, and file name for the files in the archive.
<QUALIFIER>
/CASE_INSENSITIVE

/CASE_INSENSITIVE
/NOCASE_INSENSITIVE (default)

Match filenames case-insensitively.  (Good default option under VMS.)
<QUALIFIER>
/COMMENT

/COMMENT
/NOCOMMENT

Display the archive comment.
<QUALIFIER>
/DIRECTORY

/DIRECTORY=directory-spec

Specifies the output directory where all the extracted files are to be
placed.
<QUALIFIER>
/EXCLUDE

/EXCLUDE=(file[,...])

A comma-separated list of files to exclude when extracting files.
If multiple files are specified, the list should be included in
parentheses.

<QUALIFIER>
/FRESHEN

/FRESHEN
/NOFRESHEN

Freshen existing files; replace if newer.  Does not cause any new files to
be created.
<QUALIFIER>
/FULL

/FULL

When used with /LIST, specifies that a full listing of the archive's
contents is to be displayed.  A full listing shows the length,
compression method, compressed size, compression ratio, date,
time, CRC value, and file name for the files in the archive.
<QUALIFIER>
/HELP

/HELP

Displays a one-page brief help screen and exits quietly.
<QUALIFIER>
/JUNK

/JUNK
/NOJUNK (default)

Junk the stored paths (don't recreated the archive's directory
structure.
<QUALIFIER>
/LIST

/LIST

List the contents of the archive.  /BRIEF and /FULL can be used to
specify the amount of information displayed.  The default is /BRIEF.
<QUALIFIER>
/LOWERCASE

/LOWERCASE
/NOLOWERCASE (default)

Convert filenames from all-uppercase operating systems to lowercase.  This
option has no effect under VMS.
<QUALIFIER>
/OVERWRITE

/OVERWRITE
/NOOVERWRITE

The qualifier /OVERWRITE forces overwriting of existing files when extracting.
The negation /NOOVERWRITE results in never overwriting an existing file.
The default action is to prompt for desired action when about to
overwrite an existing file.

For VMS, "overwriting" results in the creation of a new version of the file,
unless version numbers are stored in the archive and /VERSION is specified.
<QUALIFIER>
/PAGE

/PAGE
/NOPAGE

Feed all screen output through the built-in "more" pager.
<QUALIFIER>
/PIPE

/PIPE

Extract files to SYS$OUTPUT with no informational messages.
<QUALIFIER>
/QUIET

/QUIET[=SUPER]

Perform operations quietly.  The keyword SUPER can be specified to make
operations even more quiet.
<QUALIFIER>
/RESTORE

/RESTORE
/NORESTORE

Restore file owner and protection settings.
<QUALIFIER>
/SCREEN

/SCREEN
/NOSCREEN

Extracts matching files to SYS$OUTPUT (the terminal).
<QUALIFIER>
/TEST

/TEST
/NOTEST

Test archive files.
<QUALIFIER>
/TEXT

/TEXT[=KEYWORD]
/NOTEXT (default)

Selects conversion to VMS standard text file format.
The optional keywords recognized are:
<LITERAL>
|  AUTO      Automatically extracts files marked as "text" (rather than
             "binary") in in standard VMS text file format. (default)
|  ALL       Extracts all files in standard VMS text file format.
|  NONE      Same as /NOTEXT.
<LARETIL>

A similar functionality is available for binary files, see qualifier /BINARY.
<QUALIFIER>
/UPDATE

/UPDATE
/NOUPDATE

Update existing files; create new ones if needed.
<QUALIFIER>
/VERSION

/VERSION
/NOVERSION (default)

Retain VMS file version numbers.

<TOPIC>
Authors

Info-ZIP; currently maintained by Greg Roelofs.  VMS support maintained
by Igor Mandrichenko and Hunter Goatley.  Originally based on a program
by Samuel H. Smith.

VMS on-line help ported from UNZIP.DOC by Hunter Goatley.

<TOPIC>
UNIX_Options

The default action of UnZip is to extract all zipfile entries.  The following
options and modifiers can be provided:

<LITERAL>
|   -Z   ZipInfo mode
|   -c   extract files to SYS$OUTPUT (terminal)
|   -f   freshen existing files (replace if newer); create none
|   -h   show brief help screen and exit quietly
|   -l   list archive files (short format)
|   -p   extract files to SYS$OUTPUT; no informational messages
|   -t   test archive files
|   -u   update existing files; create new ones if needed
|   -v   list archive files (verbose format)
|   -z   display only the archive comment
|
| MODIFIERS
|   -a   auto-extract only text files in standard VMS text file format
|   -aa  extract all files as text
|   -b   auto-extract only binary files in VMS fixed 512 record file format
|   -bb  extract all files as binary in VMS fixed 512 byte record format
|   -j   junk paths (don't recreate archive's directory structure)
|   -n   never overwrite existing files; don't prompt
|   -o   OK to overwrite files without prompting
|   -q   perform operations quietly (-qq => even quieter)
|   -C   match filenames case-insensitively
|   -L   convert filenames to lowercase if created under MS-DOS, VMS, etc.
|   -M   page output through built-in "more" function
|   -V   retain (VMS) file version numbers
|   -X   restore owner/protection info (may require privileges)
<LARETIL>

Note that uppercase options such as -C, -L, -M, -V, -X and -Z must be specified
in quotes.  For example:

<LITERAL>
|  $ unzip "-VX" -a zipfile
<LARETIL>

.![this should probably be a separate section]:
In addition, default options may be specified via the UNZIP_OPTS logical.
For example, the following will cause UnZip to match filenames without regard
to case, restore owner/protection information and perform all operations at
quiet-level 1 by default:

<LITERAL>
|  $ define UNZIP_OPTS "-qCX"
<LARETIL>

Note that the quotation marks here are required to preserve lowercase options
(opposite of the command-line behavior). To negate a default option on the
command line, add one or more minus  signs before the option letter, in
addition to the leading switch character `-':

<LITERAL>
|  $ unzip --ql zipfile
<LARETIL>

or

<LITERAL>
|  $ unzip -l-q zipfile
<LARETIL>

At present it is not possible to decrement an option below zero--that is,
more than a few minuses have no effect.

UNZIP_OPTS may be defined as a symbol rather than a logical, but if both
are defined, the logical is used.
