#   Copyright
#
#      Copyright (C) 2009-2010 Jari Aalto
#
#   License
#
#       This program is free software; you can redistribute it and/or modify
#       it under the terms of the GNU General Public License as published by
#       the Free Software Foundation; either version 2 of the License, or
#       (at your option) any later version.
#
#       This program is distributed in the hope that it will be useful,
#       but WITHOUT ANY WARRANTY; without even the implied warranty of
#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#       GNU General Public License for more details.
#
#       You should have received a copy of the GNU General Public License
#       along with this program. If not, see <http://www.gnu.org/licenses/>.
#
#   Description
#
#	To learn what TOP LEVEL section to use in manual pages,
#	see POSIX/Susv standard and "Utility Description Defaults" at
#	http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
#
#	This is manual page in Perl POD format. Read more at
#	http://perldoc.perl.org/perlpod.html or run command:
#
#	    perldoc perlpod | less
#
#	To check the syntax:
#
#	    podchecker *.pod
#
#	Create manual page with command:
#
#	    pod2man PAGE.N.pod > PAGE.N

=pod

=head1 NAME

zpaq - PAQ open standard maximum compressor

=head1 SYNOPSIS

  create : zpaq [opnsitqv]c<config>[,N...] archive.zpaq file [file ...]
  append : zpaq [opnsitqv]a<config>[,N...] archive.zpaq file [file ...]
  list   : zpaq l archive.zpaq
  extract: zpaq [opntq]x[N] archive.zpaq
  debug  : zpaq [pthv]rF[,N...] [args...]

=head1 DESCRIPTION

=head2 General

PAQ is a series of open source data compression archivers that have
evolved through collaborative development to top rankings on several
benchmarks measuring compression ratio although at the expense of
speed and memory usage.

Zpaq ia a proposed standard format for highly compressed data that
allows new compression algorithms to be developed without breaking
compatibility with older programs. Zpaq is based on PAQ-like context
mixing algorithms which are top ranked on many benchmarks. The format
supports archivers, single file compressors, and memory to memory
compression.

ZPAQ is a configurable file compressor and archiver. Its goal
is a high compression ratio in an open format without loss of
compatibility between versions as advanced compression techniques
are discovered.

Compression uses by default built-in configuration files. Three
examples are supplied:

  min.cfg - Fast, minimal compression (LZP + order 3). Requires 4 MB memory.
  mid.cfg - Average compression and speed. Requires 111 MB.
  max.cfg - Slow but good compression. Requires 278 MB.

The config file is not needed to extract.

NOTE: in extract mode, if the FILES are listed the files are renamed
during written out.

head2 Commands

=over 4

=item B<a>

Append to archive.

=item B<c>

Create archive.

=item B<i>

Don't store file sizes as comments (saves a few bytes). Normally the
input file size is stored as a decimal string, taking a few bytes. The
comment field has no effect on the program except that it is displayed
by the B<l> and B<x> commands.

=item B<l>

List contents of archive.

=item B<n>

I<In create mode>: Don't store filenames (names will be needed to
decompress). I<In extract mode>: decompress all to one file. The
effect is to require that filenames be given during decompression.

During extract ignore all stored filenames and append all output to
one file, the first file in [files...].

=item B<o>

Optimize (run faster). You need a C++ compiler installed to use this
option. If not, drop the "o". You can still use zpaq but it will take
about twice as long to run.

If successful, compression is typically 50% to 100% faster. Zpaq will
look for a program named C<zpaq_X> in the temporary directory, where X
is derived from the SHA1 checksum of the block header produced by
config file I<CONFIG> with arguments I<N>. If the program exists, then
Zpaq will call it with the same arguments to perform the compression.
If it does not exist then Zpaq will create a source code file
C<zpaq_X.cpp> in the temporary directory, compile it, and link it to
C<zpaq.cpp> or C<zpaq.o> depending on the installation.

The temporary directory is specified by the environment variable
TEMP if it exists, or else the current directory.

The program C<zpaq_X> will compress its input in the same format as
described by I<CONFIG>, but faster. If I<CONFIG> specifies a
preprocessor, then C<zpaq_X> will expect to find it too. It will also
decompress archive blocks in the same configuration but fail if it
attempts to decompress blocks in any other configuration.

Program C<zpaq_X> will accept the B<c>, B<a> and B<x> commands with
all of the same modifiers, but will ignore the B<v> and B<o> modifiers
and ignore any CONFIG file and arguments passed to it. It will not
accept the B<l> or B<r> commands. Extraction requires a block number
("x1", "x2", etc). A different optimized program is used to extract
each block.

Zpaq will call the external program C<zpaqmake> to compile
C<zpaq_X.cpp>, passing it C<zpaq_X> as an argument. Normally this will
be a script that calls a C++ compiler to produce C<zpaq_X.o>, links to
C<zpaq.o> and outputs C<zpaq_X>. The script could link to C<zpaq.cpp>
instead of C<zpaq.o>.

=item B<p>

I<In create mode>: Store filename paths in archive. The default is to
store the name without the path. For example:

    zpaq pc<CONFIG> books.zpaq dir/file

will store the name as C<dir/file>. If the B<p> option is also given
during extraction, then ZPAQ will attempt to extract C<file> to the
subdirectory instead of the current directory. This will fail if
directory does not exist. ZPAQ does not create directories as needed.

I<In extract mode>: extract to stored paths instead of current
directory

The default is to extract to the current directory regardless of how
the file names are stored. Stored paths must be relative to the
current directory, not start with a "/", "\", a drive letter like "C:"
or contain "../" or "..\". If extracting to a subdirectory, it must
already exist. It will not be created.

[files...] overrides and has no restrictions on file names. Each
segment extracts to a different file. If any segments do not have a
stored filename then they can only be extracted using the B<p> or B<n>
modifiers.

=item B<q>

Quiet mode. Don't display compression progress on the screen.

=item B<s>

Don't store SHA1 checksums (saves 20 bytes).The decompressor will not
check that the output is identical to the original input.

=item B<t>

I<In create mode>: Append locator tag to non-ZPAQ data.

Append a locator tag to non-ZPAQ data. The tag is a string of 13 bytes
that allows ZPAQ and UNZPAQ to find the start of a sequence of ZPAQ
blocks embedded in other data. Program C<zpaqsfx> already has this tag
at the end. However, if a new stub is compiled from the source then
the B<t> command should be used when appending the first file.

I<In extract mode>: don't post-process (for debugging). Expect
checksum errors.

=item B<v>

Verbose mode. Show CONFIG file as it compiles. This is useful for
error checking.

=item B<x>

Extract. Use "ox" to extract fast. You can extract more slowly with
plain "x" if you don't have C++ installed. Output files are renamed in
the same order they are stored and listed. If you don't rename the
output files, then the files will be extracted to the current
directory with the same names they had when stored.

=item B<,N>

Usd in create mode. Pass numeric arguments to CONFIG file. Appended
suffix like ",2" means use 4 times more memory. Each increment doubles
usage. You need the same memory to decompress.

=item B<N>

I<Used in extract mode>. Extract only block N (1, 2, 3...), where 1 is
the first block. Otherwise all blocks are extracted. The B<l> command
shows which files are in each block.

=back

=head2 Debug and Development Options

To debug CONFIG file, use:

  zpaq [pthv]r<CONFIG>[,N...] [args...]

the B<r> runn the ZPAQL program in HCOMP section of configuration file
F. The program is run once for each byte of input from the file named
in the first argument and once at EOF with the input byte (or -1) in
the A register. Output is to the file named in the second argument. If
run with no arguments then take input from stdin and output to stdout.
Modifiers are listed below.

=over 4

=item B<h>

When tracing, display register and memory contents in hexadecimal
instead of decimal.

=item B<p>

Run PCOMP (default is to run HCOMP).

=item B<t>

Trace (single step), args are numeric inputs otherwise args are input,
output (default stdin, stdout). The arguments should be numbers rather
than file names. The program is run once for each argument with the
value in the A register. As each instruction is executed the register
contents are shown. At HALT, memory contents are displayed.

=item B<v>

Verbose compile. Display the CONFIG file as it is being compiled. If
an error occurs, it will be easier to locate. Modifier B<v> is also
useful for displaying jump targets.

=item B<,N>

Pass numeric arguments to CONFIG file. Pass up to 9 numeric arguments
to CONFIG file (like the B<c> and B<a> commands).

=back

=head1 OPTIONS

=over 4

=item B<-h>

Display short help.

=back

=head1 EXAMPLES

=head2 Create

To create an archive:

    zpaq c<CONFIG> archive.zpaq files ...

If the archive exists then it is overwritten. File names are stored
without a path.

=head2 Append

To (a)ppend to an existing archive. If the archive does not exist then
it is created as with the c command:

    zpaq a<CONFIG> archive.zpaq files ...

=head2 List

To list the contents of an archive. Files are listed in the same order
they were added:

    zpaq l archive.zpaq

To extract the contents of the archive. New files are created and
named according to the stored filenames. Does not clobber existing
files. Extracts to current directory:

    zpaq x archive.zpaq

If the files to be extracted already exist, then zpaq will
refuse to clobber them and skip to the next file. If the files
are compressed with a path (folder or directory), then that
directory must exist when the file is extracted. zpaq will
not create directories.

To extract files and renames in the order they were added to the
archive. Clobbers any already existing output files. The number of
files extracted is the smaller of the number of filenames on the
command line or the number of files in the archive.

    zpaq x archive.zpaq file ...

=head2 Extract

To extract and rename:

    zpaq x archive.zpaq files ...
    unzpaq x archive.zpaq files ...

Files are extracted in the same order they are saved and renamed.
Unlike using stored names, if the file exists, then it is
overwritten (clobbered). Only files named on the command line
are extracted. Any additional files in the archive are ignored.
For example:

    zpaq x archive.zpaq foo bar

To extracts files like B<x>, but without post-processing. This may be
useful for debugging or developing config files:

    zpaq t archive.zpaq [files ...]

=head2 Config file

The distribution contain several default CONFIG files:

  min.cfg - for fast but poor compression.
  max.cfg - for slow but good compression.
  mid.cfg - for moderate speed and compression (default).

Other config files are available as add-on options or you can write
them as explained later.

A numeric argument may be appended to CONGIF to increase memory usage
for better compression. Each increment doubles usage. There should be
no space before or after the comma. For example:

  zpaq cmax.cfg archive files...    = 246 MB
  zpaq cmax.cfg,1 archive files...  = 476 MB
  zpaq cmax.cfg,2 archive files...  = 938 MB
  zpaq cmax.cfg,3 archive files...  = 1861 MB
  zpaq cmax.cfg,-1 archive files... = 130 MB (negative values allowed)

Modifiers may be in any order before the "c" or "a" command. The
modifiers, command, and configuration file must be written together
without any spaces. An example: to create archive with options B<i, p,
s> and configuration file C<max.cfg>. Modifiers have the following
meaning:

  zpaq ipsc<CONFIG> archive.zpaq file1 file22

=head1 ENVIRONMENT

Temporary directory B<TEMPDIR> is use during optimize command B<o>.

None.

=head1 FILES

Compression commands B<c> and B<a> need a configuration file. See examples in
directory C</usr/share/doc/zpaq>.

=head1 STANDARDS

See zpaq*.pdf (ZPAQ Level 1 and later) in section AVAILABILITY . It is
anticipated that future levels (ZPAQ-2, ZPAQ-3, etc.) will be backward
compatible, such that newer levels can read archives produced by older
programs.

=head1 AVAILABILITY

http://mattmahoney.net/dc

=head1 SEE ALSO

C<bzip2(1)>
C<gzip(1)>
C<lzop(1)>
C<lzma(1)>
C<p7zip(1)>
C<rzip(1)>
C<unace(1)>
C<unrar(1)>
C<unzip(1)>
C<zip(1)>

=head1 AUTHORS

Program was written by Matt Mahoney <matmahoney@yahoo.com>

This manual page was put together by Jari Aalto
<jari.aalto@cante.net>. under license GNU GPL version 2 or (at your
option) any later version. For more information about license, visit
<http://www.gnu.org/copyleft/gpl.html>.

=cut
