Merging upstream version 0.8.

Signed-off-by: Daniel Baumann <mail@daniel-baumann.ch>

3 files changed, 107 insertions, 63 deletions

diff --git a/doc/plzip.1 b/doc/plzip.1
index 5fe6e3b..ec3fc36 100644
--- a/doc/plzip.1
+++ b/doc/plzip.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.37.1.
-.TH PLZIP "1" "December 2010" "Plzip 0.7" "User Commands"
+.TH PLZIP "1" "January 2012" "Plzip 0.8" "User Commands"
 .SH NAME
 Plzip \- reduces the size of files
 .SH SYNOPSIS
@@ -15,7 +15,7 @@ display this help and exit
 \fB\-V\fR, \fB\-\-version\fR
 output version information and exit
 .TP
-\fB\-B\fR, \fB\-\-data\-size=\fR<n>
+\fB\-B\fR, \fB\-\-data\-size=\fR<bytes>
 set input data block size in bytes
 .TP
 \fB\-c\fR, \fB\-\-stdout\fR
@@ -27,10 +27,13 @@ decompress
 \fB\-f\fR, \fB\-\-force\fR
 overwrite existing output files
 .TP
+\fB\-F\fR, \fB\-\-recompress\fR
+force recompression of compressed files
+.TP
 \fB\-k\fR, \fB\-\-keep\fR
 keep (don't delete) input files
 .TP
-\fB\-m\fR, \fB\-\-match\-length=\fR<n>
+\fB\-m\fR, \fB\-\-match\-length=\fR<bytes>
 set match length limit in bytes [36]
 .TP
 \fB\-n\fR, \fB\-\-threads=\fR<n>
@@ -42,7 +45,7 @@ if reading stdin, place the output into <file>
 \fB\-q\fR, \fB\-\-quiet\fR
 suppress all messages
 .TP
-\fB\-s\fR, \fB\-\-dictionary\-size=\fR<n>
+\fB\-s\fR, \fB\-\-dictionary\-size=\fR<bytes>
 set dictionary size limit in bytes [8MiB]
 .TP
 \fB\-t\fR, \fB\-\-test\fR
@@ -64,6 +67,10 @@ If no file names are given, plzip compresses or decompresses
 from standard input to standard output.
 Numbers may be followed by a multiplier: k = kB = 10^3 = 1000,
 Ki = KiB = 2^10 = 1024, M = 10^6, Mi = 2^20, G = 10^9, Gi = 2^30, etc...
+The bidimensional parameter space of LZMA can't be mapped to a linear
+scale optimal for all files. If your files are large, very repetitive,
+etc, you may need to use the \fB\-\-match\-length\fR and \fB\-\-dictionary\-size\fR
+options directly to achieve optimal performance.
 .SH "REPORTING BUGS"
 Report bugs to lzip\-bug@nongnu.org
 .br
@@ -71,8 +78,8 @@ Plzip home page: http://www.nongnu.org/lzip/plzip.html
 .SH COPYRIGHT
 Copyright \(co 2009 Laszlo Ersek.
 .br
-Copyright \(co 2010 Antonio Diaz Diaz.
-Using Lzlib 1.1\-rc1
+Copyright \(co 2012 Antonio Diaz Diaz.
+Using Lzlib 1.3\-rc1
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 .br
 This is free software: you are free to change and redistribute it.
diff --git a/doc/plzip.info b/doc/plzip.info
index 22f0052..3a12bef 100644
--- a/doc/plzip.info
+++ b/doc/plzip.info
@@ -12,7 +12,7 @@ File: plzip.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Plzip Manual
 ************
 
-This manual is for Plzip (version 0.7, 3 December 2010).
+This manual is for Plzip (version 0.8, 17 January 2012).
 
 * Menu:
 
@@ -24,7 +24,7 @@ This manual is for Plzip (version 0.7, 3 December 2010).
 * Concept Index::       Index of concepts
 
 
-   Copyright (C) 2009, 2010 Antonio Diaz Diaz.
+   Copyright (C) 2009, 2010, 2011, 2012 Antonio Diaz Diaz.
 
    This manual is free documentation: you have unlimited permission to
 copy, distribute and modify it.
@@ -39,7 +39,7 @@ Plzip is a massively parallel (multi-threaded), lossless data compressor
 based on the lzlib compression library, with very safe integrity
 checking and a user interface similar to the one of bzip2, gzip or lzip.
 Plzip uses the lzip file format; the files produced by plzip are fully
-compatible with lzip-1.4 or newer.
+compatible with lzip-1.4 or newer, and can be rescued with lziprecover.
 
    Plzip is intended for faster compression/decompression of big files
 on multiprocessor machines, which makes it specially well suited for
@@ -106,8 +106,8 @@ The format for running plzip is:
 `--version'
      Print the version number of plzip on the standard output and exit.
 
-`-B'
-`--data-size=SIZE'
+`-B BYTES'
+`--data-size=BYTES'
      Set the input data block size in bytes. The input file will be
      divided in chunks of this size before compression is performed.
      Valid values range from 8KiB to 1GiB. Default value is two times
@@ -125,21 +125,27 @@ The format for running plzip is:
 
 `-f'
 `--force'
-     Force overwrite of output file.
+     Force overwrite of output files.
+
+`-F'
+`--recompress'
+     Force recompression of files whose name already has the `.lz' or
+     `.tlz' suffix.
 
 `-k'
 `--keep'
      Keep (don't delete) input files during compression or
      decompression.
 
-`-m LENGTH'
-`--match-length=LENGTH'
-     Set the match length limit in bytes. Valid values range from 5 to
-     273.  Larger values usually give better compression ratios but
-     longer compression times.
+`-m BYTES'
+`--match-length=BYTES'
+     Set the match length limit in bytes. After a match this long is
+     found, the search is finished. Valid values range from 5 to 273.
+     Larger values usually give better compression ratios but longer
+     compression times.
 
-`-n THREADS'
-`--threads=THREADS'
+`-n N'
+`--threads=N'
      Set the number of worker threads. Valid values range from 1 to "as
      many as your system can support". If this option is not used,
      plzip tries to detect the number of processors in the system and
@@ -156,24 +162,35 @@ The format for running plzip is:
 `--quiet'
      Quiet operation. Suppress all messages.
 
-`-s SIZE'
-`--dictionary-size=SIZE'
+`-s BYTES'
+`--dictionary-size=BYTES'
      Set the dictionary size limit in bytes. Valid values range from
-     4KiB to 512MiB. Note that dictionary sizes are quantized. If the
-     specified size does not match one of the valid sizes, it will be
-     rounded upwards.
+     4KiB to 512MiB. Plzip will use the smallest possible dictionary
+     size for each member without exceeding this limit. Note that
+     dictionary sizes are quantized. If the specified size does not
+     match one of the valid sizes, it will be rounded upwards by adding
+     up to (BYTES / 16) to it.
+
+     For maximum compression you should use a dictionary size limit as
+     large as possible, but keep in mind that the decompression memory
+     requirement is affected at compression time by the choice of
+     dictionary size limit.
 
 `-t'
 `--test'
      Check integrity of the specified file(s), but don't decompress
      them.  This really performs a trial decompression and throws away
-     the result.  Use `-tvv' or `-tvvv' to see information about the
-     file.
+     the result.  Use it together with `-v' to see information about
+     the file.
 
 `-v'
 `--verbose'
-     Verbose mode. Show the compression ratio for each file processed.
-     Further -v's increase the verbosity level.
+     Verbose mode.
+     When compressing, show the compression ratio for each file
+     processed.
+     When decompressing or testing, further -v's (up to 4) increase the
+     verbosity level, showing status, compression ratio, decompressed
+     size, and compressed size.
 
 `-1 .. -9'
      Set the compression parameters (dictionary size and match length
@@ -265,13 +282,13 @@ additional information before, between, or after them.
    All multibyte values are stored in little endian order.
 
 `ID string'
-     A four byte string, identifying the member type, with the value
+     A four byte string, identifying the lzip format, with the value
      "LZIP".
 
 `VN (version number, 1 byte)'
      Just in case something needs to be modified in the future. Valid
-     values are 0 and 1. Version 0 files have only one member and lack
-     `Member size'.
+     values are 0 and 1. Version 0 files are deprecated. They can
+     contain only one member and lack the `Member size' field.
 
 `DS (coded dictionary size, 1 byte)'
      Bits 4-0 contain the base 2 logarithm of the base dictionary size.
@@ -292,7 +309,7 @@ additional information before, between, or after them.
 
 `Member size (8 bytes)'
      Total size of the member, including header and trailer. This
-     facilitates safe recovery of undamaged members from multimember
+     facilitates safe recovery of undamaged members from multi-member
      files.
 
 
@@ -334,11 +351,16 @@ Concept Index
 
 Tag Table:
 Node: Top223
-Node: Introduction833
-Node: Invoking Plzip3592
-Node: Program Design7840
-Node: File Format8502
-Node: Problems10458
-Node: Concept Index10987
+Node: Introduction845
+Node: Invoking Plzip3641
+Node: Program Design8597
+Node: File Format9259
+Node: Problems11254
+Node: Concept Index11783
 
 End Tag Table
+
+
+Local Variables:
+coding: iso-8859-15
+End:
diff --git a/doc/plzip.texinfo b/doc/plzip.texinfo
index 517dc11..c83d5a5 100644
--- a/doc/plzip.texinfo
+++ b/doc/plzip.texinfo
@@ -1,12 +1,13 @@
 \input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename plzip.info
+@documentencoding ISO-8859-15
 @settitle Plzip Manual
 @finalout
 @c %**end of header
 
-@set UPDATED 3 December 2010
-@set VERSION 0.7
+@set UPDATED 17 January 2012
+@set VERSION 0.8
 
 @dircategory Data Compression
 @direntry
@@ -43,7 +44,7 @@ This manual is for Plzip (version @value{VERSION}, @value{UPDATED}).
 @end menu
 
 @sp 1
-Copyright @copyright{} 2009, 2010 Antonio Diaz Diaz.
+Copyright @copyright{} 2009, 2010, 2011, 2012 Antonio Diaz Diaz.
 
 This manual is free documentation: you have unlimited permission
 to copy, distribute and modify it.
@@ -57,7 +58,7 @@ Plzip is a massively parallel (multi-threaded), lossless data compressor
 based on the lzlib compression library, with very safe integrity
 checking and a user interface similar to the one of bzip2, gzip or lzip.
 Plzip uses the lzip file format; the files produced by plzip are fully
-compatible with lzip-1.4 or newer.
+compatible with lzip-1.4 or newer, and can be rescued with lziprecover.
 
 Plzip is intended for faster compression/decompression of big files on
 multiprocessor machines, which makes it specially well suited for
@@ -131,8 +132,8 @@ Print an informative help message describing the options and exit.
 @itemx --version
 Print the version number of plzip on the standard output and exit.
 
-@item -B
-@itemx --data-size=@var{size}
+@item -B @var{bytes}
+@itemx --data-size=@var{bytes}
 Set the input data block size in bytes. The input file will be divided
 in chunks of this size before compression is performed. Valid values
 range from 8KiB to 1GiB. Default value is two times the dictionary size.
@@ -150,20 +151,25 @@ Decompress.
 
 @item -f
 @itemx --force
-Force overwrite of output file.
+Force overwrite of output files.
+
+@item -F
+@itemx --recompress
+Force recompression of files whose name already has the @samp{.lz} or
+@samp{.tlz} suffix.
 
 @item -k
 @itemx --keep
 Keep (don't delete) input files during compression or decompression.
 
-@item -m @var{length}
-@itemx --match-length=@var{length}
-Set the match length limit in bytes. Valid values range from 5 to 273.
-Larger values usually give better compression ratios but longer
-compression times.
+@item -m @var{bytes}
+@itemx --match-length=@var{bytes}
+Set the match length limit in bytes. After a match this long is found,
+the search is finished. Valid values range from 5 to 273. Larger values
+usually give better compression ratios but longer compression times.
 
-@item -n @var{threads}
-@itemx --threads=@var{threads}
+@item -n @var{n}
+@itemx --threads=@var{n}
 Set the number of worker threads. Valid values range from 1 to "as many
 as your system can support". If this option is not used, plzip tries to
 detect the number of processors in the system and use it as default
@@ -180,22 +186,31 @@ and a file named @samp{@var{file}.lz} when compressing.
 @itemx --quiet
 Quiet operation. Suppress all messages.
 
-@item -s @var{size}
-@itemx --dictionary-size=@var{size}
+@item -s @var{bytes}
+@itemx --dictionary-size=@var{bytes}
 Set the dictionary size limit in bytes. Valid values range from 4KiB to
-512MiB. Note that dictionary sizes are quantized. If the specified size
-does not match one of the valid sizes, it will be rounded upwards.
+512MiB. Plzip will use the smallest possible dictionary size for each
+member without exceeding this limit. Note that dictionary sizes are
+quantized. If the specified size does not match one of the valid sizes,
+it will be rounded upwards by adding up to (@var{bytes} / 16) to it.
+
+For maximum compression you should use a dictionary size limit as large
+as possible, but keep in mind that the decompression memory requirement
+is affected at compression time by the choice of dictionary size limit.
 
 @item -t
 @itemx --test
 Check integrity of the specified file(s), but don't decompress them.
 This really performs a trial decompression and throws away the result.
-Use @samp{-tvv} or @samp{-tvvv} to see information about the file.
+Use it together with @samp{-v} to see information about the file.
 
 @item -v
 @itemx --verbose
-Verbose mode. Show the compression ratio for each file processed.
-Further -v's increase the verbosity level.
+Verbose mode.@*
+When compressing, show the compression ratio for each file processed.@*
+When decompressing or testing, further -v's (up to 4) increase the
+verbosity level, showing status, compression ratio, decompressed size,
+and compressed size.
 
 @item -1 .. -9
 Set the compression parameters (dictionary size and match length limit)
@@ -297,12 +312,12 @@ All multibyte values are stored in little endian order.
 
 @table @samp
 @item ID string
-A four byte string, identifying the member type, with the value "LZIP".
+A four byte string, identifying the lzip format, with the value "LZIP".
 
 @item VN (version number, 1 byte)
 Just in case something needs to be modified in the future. Valid values
-are 0 and 1. Version 0 files have only one member and lack @samp{Member
-size}.
+are 0 and 1. Version 0 files are deprecated. They can contain only one
+member and lack the @samp{Member size} field.
 
 @item DS (coded dictionary size, 1 byte)
 Bits 4-0 contain the base 2 logarithm of the base dictionary size.@*
@@ -323,7 +338,7 @@ Size of the uncompressed original data.
 
 @item Member size (8 bytes)
 Total size of the member, including header and trailer. This facilitates
-safe recovery of undamaged members from multimember files.
+safe recovery of undamaged members from multi-member files.
 
 @end table