Merging upstream version 1.0~rc1.

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

3 files changed, 130 insertions, 84 deletions

diff --git a/doc/plzip.1 b/doc/plzip.1
index ec3fc36..2b1261b 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" "January 2012" "Plzip 0.8" "User Commands"
+.TH PLZIP "1" "March 2013" "Plzip 1.0-rc1" "User Commands"
 .SH NAME
 Plzip \- reduces the size of files
 .SH SYNOPSIS
@@ -37,7 +37,7 @@ keep (don't delete) input files
 set match length limit in bytes [36]
 .TP
 \fB\-n\fR, \fB\-\-threads=\fR<n>
-set the number of (de)compression threads
+set number of (de)compression threads [1]
 .TP
 \fB\-o\fR, \fB\-\-output=\fR<file>
 if reading stdin, place the output into <file>
@@ -78,8 +78,8 @@ Plzip home page: http://www.nongnu.org/lzip/plzip.html
 .SH COPYRIGHT
 Copyright \(co 2009 Laszlo Ersek.
 .br
-Copyright \(co 2012 Antonio Diaz Diaz.
-Using Lzlib 1.3\-rc1
+Copyright \(co 2013 Antonio Diaz Diaz.
+Using Lzlib 1.4\-rc2
 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 3a12bef..bf22e32 100644
--- a/doc/plzip.info
+++ b/doc/plzip.info
@@ -12,25 +12,25 @@ File: plzip.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Plzip Manual
 ************
 
-This manual is for Plzip (version 0.8, 17 January 2012).
+This manual is for Plzip (version 1.0-rc1, 8 March 2013).
 
 * Menu:
 
-* Introduction::        Purpose and features of plzip
-* Invoking Plzip::      Command line interface
-* Program Design::      Internal structure of plzip
-* File Format::         Detailed format of the compressed file
-* Problems::            Reporting bugs
-* Concept Index::       Index of concepts
+* Introduction::          Purpose and features of plzip
+* Program Design::        Internal structure of plzip
+* Invoking Plzip::        Command line interface
+* File Format::           Detailed format of the compressed file
+* Problems::              Reporting bugs
+* Concept Index::         Index of concepts
 
 
-   Copyright (C) 2009, 2010, 2011, 2012 Antonio Diaz Diaz.
+   Copyright (C) 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz.
 
    This manual is free documentation: you have unlimited permission to
 copy, distribute and modify it.
 
 
-File: plzip.info,  Node: Introduction,  Next: Invoking Plzip,  Prev: Top,  Up: Top
+File: plzip.info,  Node: Introduction,  Next: Program Design,  Prev: Top,  Up: Top
 
 1 Introduction
 **************
@@ -81,15 +81,45 @@ processed. Be aware, though, that the check occurs upon decompression,
 so it can only tell you that something is wrong. It can't help you
 recover the original uncompressed data.
 
+   WARNING! Even if plzip is bug-free, other causes may result in a
+corrupt compressed file (bugs in the system libraries, memory errors,
+etc).  Therefore, if the data you are going to compress is important,
+give the `--keep' option to plzip and do not remove the original file
+until you verify the compressed file with a command like
+`plzip -cd file.lz | cmp file -'.
+
    Return values: 0 for a normal exit, 1 for environmental problems
 (file not found, invalid flags, I/O errors, etc), 2 to indicate a
 corrupt or invalid input file, 3 for an internal consistency error (eg,
 bug) which caused plzip to panic.
 
 
-File: plzip.info,  Node: Invoking Plzip,  Next: Program Design,  Prev: Introduction,  Up: Top
+File: plzip.info,  Node: Program Design,  Next: Invoking Plzip,  Prev: Introduction,  Up: Top
+
+2 Program Design
+****************
+
+For each input file, a splitter thread and several worker threads are
+created, acting the main thread as muxer (multiplexer) thread. A "packet
+courier" takes care of data transfers among threads and limits the
+maximum number of data blocks (packets) being processed simultaneously.
+
+   The splitter reads data blocks from the input file, and distributes
+them to the workers. The workers (de)compress the blocks received from
+the splitter. The muxer collects processed packets from the workers, and
+writes them to the output file.
+
+   When decompressing from a regular file, the splitter is removed and
+the workers read directly from the input file. If the output file is
+also a regular file, the muxer is also removed, and the workers write
+directly to the output file. With these optimizations, decompression
+speed of large files with many members is only limited by the number of
+processors available and by I/O speed.
+
+
+File: plzip.info,  Node: Invoking Plzip,  Next: File Format,  Prev: Program Design,  Up: Top
 
-2 Invoking Plzip
+3 Invoking Plzip
 ****************
 
 The format for running plzip is:
@@ -149,7 +179,8 @@ The format for running plzip is:
      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 value.
+     use it as default value. `plzip --help' shows the system's default
+     value.
 
 `-o FILE'
 `--output=FILE'
@@ -236,28 +267,17 @@ Z        zettabyte (10^21)         |   Zi       zebibyte (2^70)
 Y        yottabyte (10^24)         |   Yi       yobibyte (2^80)
 
 
-File: plzip.info,  Node: Program Design,  Next: File Format,  Prev: Invoking Plzip,  Up: Top
-
-3 Program Design
-****************
-
-For each input file, a splitter thread and several worker threads are
-created, acting the main thread as muxer (multiplexer) thread. A "packet
-courier" takes care of data transfers among threads and limits the
-maximum number of data blocks (packets) being processed simultaneously.
-
-   The splitter reads data blocks from the input file, and distributes
-them to the workers. The workers (de)compress the blocks received from
-the splitter. The muxer collects processed packets from the workers, and
-writes them to the output file.
-
-
-File: plzip.info,  Node: File Format,  Next: Problems,  Prev: Program Design,  Up: Top
+File: plzip.info,  Node: File Format,  Next: Problems,  Prev: Invoking Plzip,  Up: Top
 
 4 File Format
 *************
 
-In the diagram below, a box like this:
+Perfection is reached, not when there is no longer anything to add, but
+when there is no longer anything to take away.
+-- Antoine de Saint-Exupery
+
+
+   In the diagram below, a box like this:
 +---+
 |   | <-- the vertical bars might be missing
 +---+
@@ -286,15 +306,19 @@ additional information before, between, or after them.
      "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 are deprecated. They can
-     contain only one member and lack the `Member size' field.
+     Just in case something needs to be modified in the future. 1 for
+     now.
 
 `DS (coded dictionary size, 1 byte)'
-     Bits 4-0 contain the base 2 logarithm of the base dictionary size.
-     Bits 7-5 contain the number of "wedges" to substract from the base
-     dictionary size to obtain the dictionary size. The size of a wedge
-     is (base dictionary size / 16).
+     Lzip divides the distance between any two powers of 2 into 8
+     equally spaced intervals, named "wedges". The dictionary size is
+     calculated by taking a power of 2 (the base size) and substracting
+     from it a number of wedges between 0 and 7. The size of a wedge is
+     (base_size / 16).
+     Bits 4-0 contain the base 2 logarithm of the base size (12 to 29).
+     Bits 7-5 contain the number of wedges (0 to 7) to substract from
+     the base size to obtain the dictionary size.
+     Example: 0xD3 = (2^19 - 6 * 2^15) = (512KiB - 6 * 32KiB) = 320KiB
      Valid values for dictionary size range from 4KiB to 512MiB.
 
 `Lzma stream'
@@ -308,9 +332,9 @@ additional information before, between, or after them.
      Size of the uncompressed original data.
 
 `Member size (8 bytes)'
-     Total size of the member, including header and trailer. This
-     facilitates safe recovery of undamaged members from multi-member
-     files.
+     Total size of the member, including header and trailer. This field
+     acts as a distributed index, and facilitates safe recovery of
+     undamaged members from multi-member files.
 
 
 
@@ -351,12 +375,12 @@ Concept Index
 
 Tag Table:
 Node: Top223
-Node: Introduction845
-Node: Invoking Plzip3641
-Node: Program Design8597
-Node: File Format9259
-Node: Problems11254
-Node: Concept Index11783
+Node: Introduction864
+Node: Program Design4030
+Node: Invoking Plzip5084
+Node: File Format10093
+Node: Problems12473
+Node: Concept Index13002
 
 End Tag Table
 
diff --git a/doc/plzip.texinfo b/doc/plzip.texinfo
index c83d5a5..5e62234 100644
--- a/doc/plzip.texinfo
+++ b/doc/plzip.texinfo
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 17 January 2012
-@set VERSION 0.8
+@set UPDATED 8 March 2013
+@set VERSION 1.0-rc1
 
 @dircategory Data Compression
 @direntry
@@ -35,16 +35,16 @@
 This manual is for Plzip (version @value{VERSION}, @value{UPDATED}).
 
 @menu
-* Introduction::        Purpose and features of plzip
-* Invoking Plzip::      Command line interface
-* Program Design::      Internal structure of plzip
-* File Format::         Detailed format of the compressed file
-* Problems::            Reporting bugs
-* Concept Index::       Index of concepts
+* Introduction::          Purpose and features of plzip
+* Program Design::        Internal structure of plzip
+* Invoking Plzip::        Command line interface
+* File Format::           Detailed format of the compressed file
+* Problems::              Reporting bugs
+* Concept Index::         Index of concepts
 @end menu
 
 @sp 1
-Copyright @copyright{} 2009, 2010, 2011, 2012 Antonio Diaz Diaz.
+Copyright @copyright{} 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz.
 
 This manual is free documentation: you have unlimited permission
 to copy, distribute and modify it.
@@ -102,12 +102,41 @@ the check occurs upon decompression, so it can only tell you that
 something is wrong. It can't help you recover the original uncompressed
 data.
 
+WARNING! Even if plzip is bug-free, other causes may result in a corrupt
+compressed file (bugs in the system libraries, memory errors, etc).
+Therefore, if the data you are going to compress is important, give the
+@samp{--keep} option to plzip and do not remove the original file until
+you verify the compressed file with a command like
+@w{@samp{plzip -cd file.lz | cmp file -}}.
+
 Return values: 0 for a normal exit, 1 for environmental problems (file
 not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
 invalid input file, 3 for an internal consistency error (eg, bug) which
 caused plzip to panic.
 
 
+@node Program Design
+@chapter Program Design
+@cindex program design
+
+For each input file, a splitter thread and several worker threads are
+created, acting the main thread as muxer (multiplexer) thread. A "packet
+courier" takes care of data transfers among threads and limits the
+maximum number of data blocks (packets) being processed simultaneously.
+
+The splitter reads data blocks from the input file, and distributes them
+to the workers. The workers (de)compress the blocks received from the
+splitter. The muxer collects processed packets from the workers, and
+writes them to the output file.
+
+When decompressing from a regular file, the splitter is removed and the
+workers read directly from the input file. If the output file is also a
+regular file, the muxer is also removed, and the workers write directly
+to the output file. With these optimizations, decompression speed of
+large files with many members is only limited by the number of
+processors available and by I/O speed.
+
+
 @node Invoking Plzip
 @chapter Invoking Plzip
 @cindex invoking
@@ -173,7 +202,7 @@ usually give better compression ratios but longer compression times.
 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
-value.
+value. @w{@samp{plzip --help}} shows the system's default value.
 
 @item -o @var{file}
 @itemx --output=@var{file}
@@ -261,25 +290,15 @@ Table of SI and binary prefixes (unit multipliers):
 @end multitable
 
 
-@node Program Design
-@chapter Program Design
-@cindex program design
-
-For each input file, a splitter thread and several worker threads are
-created, acting the main thread as muxer (multiplexer) thread. A "packet
-courier" takes care of data transfers among threads and limits the
-maximum number of data blocks (packets) being processed simultaneously.
-
-The splitter reads data blocks from the input file, and distributes them
-to the workers. The workers (de)compress the blocks received from the
-splitter. The muxer collects processed packets from the workers, and
-writes them to the output file.
-
-
 @node File Format
 @chapter File Format
 @cindex file format
 
+Perfection is reached, not when there is no longer anything to add, but
+when there is no longer anything to take away.@*
+--- Antoine de Saint-Exupery
+
+@sp 1
 In the diagram below, a box like this:
 @verbatim
 +---+
@@ -315,15 +334,17 @@ All multibyte values are stored in little endian order.
 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 are deprecated. They can contain only one
-member and lack the @samp{Member size} field.
+Just in case something needs to be modified in the future. 1 for now.
 
 @item DS (coded dictionary size, 1 byte)
-Bits 4-0 contain the base 2 logarithm of the base dictionary size.@*
-Bits 7-5 contain the number of "wedges" to substract from the base
-dictionary size to obtain the dictionary size. The size of a wedge is
-(base dictionary size / 16).@*
+Lzip divides the distance between any two powers of 2 into 8 equally
+spaced intervals, named "wedges". The dictionary size is calculated by
+taking a power of 2 (the base size) and substracting from it a number of
+wedges between 0 and 7. The size of a wedge is (base_size / 16).@*
+Bits 4-0 contain the base 2 logarithm of the base size (12 to 29).@*
+Bits 7-5 contain the number of wedges (0 to 7) to substract from the
+base size to obtain the dictionary size.@*
+Example: 0xD3 = (2^19 - 6 * 2^15) = (512KiB - 6 * 32KiB) = 320KiB@*
 Valid values for dictionary size range from 4KiB to 512MiB.
 
 @item Lzma stream
@@ -337,8 +358,9 @@ CRC of the uncompressed original data.
 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 multi-member files.
+Total size of the member, including header and trailer. This field acts
+as a distributed index, and facilitates safe recovery of undamaged
+members from multi-member files.
 
 @end table