Merging upstream version 1.17~rc1.

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

3 files changed, 131 insertions, 35 deletions

diff --git a/doc/lziprecover.1 b/doc/lziprecover.1
index 7eefb7a..c2f55d7 100644
--- a/doc/lziprecover.1
+++ b/doc/lziprecover.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.46.1.
-.TH LZIPRECOVER "1" "October 2014" "lziprecover 1.17-pre1" "User Commands"
+.TH LZIPRECOVER "1" "January 2015" "lziprecover 1.17-rc1" "User Commands"
 .SH NAME
 lziprecover \- recovers data from damaged lzip files
 .SH SYNOPSIS
@@ -7,6 +7,7 @@ lziprecover \- recovers data from damaged lzip files
 [\fI\,options\/\fR] [\fI\,files\/\fR]
 .SH DESCRIPTION
 Lziprecover \- Data recovery tool and decompressor for the lzip format.
+.PP
 Lziprecover can repair perfectly most files with small errors (up to one
 single\-byte error per member), without the need of any extra redundance
 at all. Losing an entire archive just because of a corrupt byte near the
@@ -76,7 +77,7 @@ Report bugs to lzip\-bug@nongnu.org
 .br
 Lziprecover home page: http://www.nongnu.org/lzip/lziprecover.html
 .SH COPYRIGHT
-Copyright \(co 2014 Antonio Diaz Diaz.
+Copyright \(co 2015 Antonio Diaz Diaz.
 License GPLv2+: GNU GPL version 2 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/lziprecover.info b/doc/lziprecover.info
index 6c636e8..05c1196 100644
--- a/doc/lziprecover.info
+++ b/doc/lziprecover.info
@@ -12,12 +12,13 @@ File: lziprecover.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Lziprecover Manual
 ******************
 
-This manual is for Lziprecover (version 1.17-pre1, 16 October 2014).
+This manual is for Lziprecover (version 1.17-rc1, 21 January 2015).
 
 * Menu:
 
 * Introduction::           Purpose and features of lziprecover
 * Invoking lziprecover::   Command line interface
+* Data safety::            Protecting data from accidental loss
 * Repairing files::        Fixing bit-flip and similar errors
 * Merging files::          Fixing several damaged copies
 * File names::             Names of the files produced by lziprecover
@@ -28,7 +29,7 @@ This manual is for Lziprecover (version 1.17-pre1, 16 October 2014).
 * Concept index::          Index of concepts
 
 
-   Copyright (C) 2009-2014 Antonio Diaz Diaz.
+   Copyright (C) 2009-2015 Antonio Diaz Diaz.
 
    This manual is free documentation: you have unlimited permission to
 copy, distribute and modify it.
@@ -104,7 +105,7 @@ like lzip or lunzip.
 line of defense for the case where the backups are also damaged.
 
 
-File: lziprecover.info,  Node: Invoking lziprecover,  Next: Repairing files,  Prev: Introduction,  Up: Top
+File: lziprecover.info,  Node: Invoking lziprecover,  Next: Data safety,  Prev: Introduction,  Up: Top
 
 2 Invoking lziprecover
 **********************
@@ -252,20 +253,66 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
 caused lziprecover to panic.
 
 
-File: lziprecover.info,  Node: Repairing files,  Next: Merging files,  Prev: Invoking lziprecover,  Up: Top
+File: lziprecover.info,  Node: Data safety,  Next: Repairing files,  Prev: Invoking lziprecover,  Up: Top
 
-3 Repairing files
+3 Protecting data from accidental loss
+**************************************
+
+There are 3 main types of data corruption that may cause data loss:
+single-byte errors, multi-byte errors (generally affecting a whole
+sector in a block device), and total device failure.
+
+   Lziprecover protects natively against single-byte errors (*note
+Repairing files::), as long as file integrity is checked frequently
+enough that a second single-byte error does not develop in the same
+member before the first one is repaired.
+
+   Lziprecover also protects against multi-byte errors (*note Merging
+files::), if at least one backup copy of the file is made.
+
+   The only remedy for total device failure is storing backup copies in
+separate media.
+
+   How does lzip compare with gzip and bzip2 with respect to data
+safety?  Lets suppose that you made a backup copy of your valuable
+scientific data, compressed it, and stored two copies on separate
+media. Years later you notice that both copies are corrupt.
+
+   If you compressed with gzip and both copies suffer any damage in the
+data stream, even if it is just one altered bit, the original data can't
+be recovered.
+
+   If you used bzip2, and if the file is large enough to contain more
+than one compressed data block (usually larger than 900 kB), and if no
+block is damaged in both files, then the data can be manually recovered
+by splitting the files with bzip2recover, verifying every block and then
+copying the right blocks in the right order in another file.
+
+   But if you used lzip, the data can be automatically recovered as
+long as no byte is damaged in both files.
+
+   Note that each error in a bzip2 file makes a whole block unusable,
+but each error in a lzip file only affects the damaged bytes, making it
+possible to recover a file with thousands of errors.
+
+
+File: lziprecover.info,  Node: Repairing files,  Next: Merging files,  Prev: Data safety,  Up: Top
+
+4 Repairing files
 *****************
 
 Lziprecover can repair perfectly most files with small errors (up to one
 single-byte error per member), without the need of any extra redundance
 at all. If the reparation is successful, the repaired file will be
-identical bit for bit to the original.
+identical bit for bit to the original. This makes lzip files resistant
+to bit-flip, one of the most common forms of data corruption.
 
    The error may be located anywhere in the file except in the header
 (first 6 bytes of each member) or in the 'Member size' field of the
-trailer (last 8 bytes of each member). This makes lzip files resistant
-to bit-flip, one of the most common forms of data corruption.
+trailer (last 8 bytes of each member). If the error is in the header it
+can be easily repaired with a text editor like GNU Moe (*note File
+format::). If the error is in the member size, it is enough to ignore
+the message about 'bad member size' when decompressing.
 
    Bit-flip happens when one bit in the file is changed from 0 to 1 or
 vice versa. It may be caused by bad RAM or even by natural radiation. I
@@ -289,7 +336,7 @@ lziprecover repairs more efficiently the worst errors.
 
 File: lziprecover.info,  Node: Merging files,  Next: File names,  Prev: Repairing files,  Up: Top
 
-4 Merging files
+5 Merging files
 ***************
 
 If you have several copies of a file but all of them are too damaged to
@@ -330,7 +377,7 @@ errors are randomly located inside each copy).
 
 File: lziprecover.info,  Node: File names,  Next: File format,  Prev: Merging files,  Up: Top
 
-5 Names of the files produced by lziprecover
+6 Names of the files produced by lziprecover
 ********************************************
 
 The name of the fixed file produced by '--merge' and '--repair' is made
@@ -341,7 +388,7 @@ original file name ends with one of the extensions '.tar.lz', '.lz' or
 
 File: lziprecover.info,  Node: File format,  Next: Examples,  Prev: File names,  Up: Top
 
-6 File format
+7 File format
 *************
 
 Perfection is reached, not when there is no longer anything to add, but
@@ -414,7 +461,7 @@ additional information before, between, or after them.
 
 File: lziprecover.info,  Node: Examples,  Next: Unzcrash,  Prev: File format,  Up: Top
 
-7 A small tutorial with examples
+8 A small tutorial with examples
 ********************************
 
 Example 1: Restore a regular file from its compressed version
@@ -485,7 +532,7 @@ correct file produced is saved in 'big_db_00001.lz'.
 
 File: lziprecover.info,  Node: Unzcrash,  Next: Problems,  Prev: Examples,  Up: Top
 
-8 Testing the robustness of decompressors
+9 Testing the robustness of decompressors
 *****************************************
 
 The lziprecover package also includes unzcrash, a program written to
@@ -562,8 +609,8 @@ caused unzcrash to panic.
 
 File: lziprecover.info,  Node: Problems,  Next: Concept index,  Prev: Unzcrash,  Up: Top
 
-9 Reporting bugs
-****************
+10 Reporting bugs
+*****************
 
 There are probably bugs in lziprecover. There are certainly errors and
 omissions in this manual. If you report them, they will get fixed. If
@@ -584,6 +631,7 @@ Concept index
 * Menu:
 
 * bugs:                                  Problems.              (line 6)
+* data safety:                           Data safety.           (line 6)
 * examples:                              Examples.              (line 6)
 * file format:                           File format.           (line 6)
 * file names:                            File names.            (line 6)
@@ -598,17 +646,18 @@ Concept index
 
 Tag Table:
 Node: Top231
-Node: Introduction1153
-Node: Invoking lziprecover4249
-Node: Repairing files9686
-Node: Merging files11371
-Node: File names13212
-Node: File format13676
-Node: Examples16183
-Ref: ddrescue-example17384
-Node: Unzcrash18493
-Node: Problems21047
-Node: Concept index21597
+Node: Introduction1216
+Node: Invoking lziprecover4312
+Node: Data safety9745
+Node: Repairing files11661
+Node: Merging files13563
+Node: File names15404
+Node: File format15868
+Node: Examples18375
+Ref: ddrescue-example19576
+Node: Unzcrash20685
+Node: Problems23239
+Node: Concept index23791
 
 End Tag Table
 
diff --git a/doc/lziprecover.texi b/doc/lziprecover.texi
index 08d4312..85f0385 100644
--- a/doc/lziprecover.texi
+++ b/doc/lziprecover.texi
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 16 October 2014
-@set VERSION 1.17-pre1
+@set UPDATED 21 January 2015
+@set VERSION 1.17-rc1
 
 @dircategory Data Compression
 @direntry
@@ -37,6 +37,7 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
 @menu
 * Introduction::           Purpose and features of lziprecover
 * Invoking lziprecover::   Command line interface
+* Data safety::            Protecting data from accidental loss
 * Repairing files::        Fixing bit-flip and similar errors
 * Merging files::          Fixing several damaged copies
 * File names::             Names of the files produced by lziprecover
@@ -48,7 +49,7 @@ This manual is for Lziprecover (version @value{VERSION}, @value{UPDATED}).
 @end menu
 
 @sp 1
-Copyright @copyright{} 2009-2014 Antonio Diaz Diaz.
+Copyright @copyright{} 2009-2015 Antonio Diaz Diaz.
 
 This manual is free documentation: you have unlimited permission
 to copy, distribute and modify it.
@@ -281,6 +282,48 @@ invalid input file, 3 for an internal consistency error (eg, bug) which
 caused lziprecover to panic.
 
 
+@node Data safety
+@chapter Protecting data from accidental loss
+@cindex data safety
+
+There are 3 main types of data corruption that may cause data loss:
+single-byte errors, multi-byte errors (generally affecting a whole
+sector in a block device), and total device failure.
+
+Lziprecover protects natively against single-byte errors
+(@pxref{Repairing files}), as long as file integrity is checked
+frequently enough that a second single-byte error does not develop in
+the same member before the first one is repaired.
+
+Lziprecover also protects against multi-byte errors (@pxref{Merging
+files}), if at least one backup copy of the file is made.
+
+The only remedy for total device failure is storing backup copies in
+separate media.
+
+How does lzip compare with gzip and bzip2 with respect to data safety?
+Lets suppose that you made a backup copy of your valuable scientific
+data, compressed it, and stored two copies on separate media. Years
+later you notice that both copies are corrupt.
+
+If you compressed with gzip and both copies suffer any damage in the
+data stream, even if it is just one altered bit, the original data can't
+be recovered.
+
+If you used bzip2, and if the file is large enough to contain more than
+one compressed data block (usually larger than 900 kB), and if no block
+is damaged in both files, then the data can be manually recovered by
+splitting the files with bzip2recover, verifying every block and then
+copying the right blocks in the right order in another file.
+
+But if you used lzip, the data can be automatically recovered as long as
+no byte is damaged in both files.
+
+Note that each error in a bzip2 file makes a whole block unusable, but
+each error in a lzip file only affects the damaged bytes, making it
+possible to recover a file with thousands of errors.
+
+
 @node Repairing files
 @chapter Repairing files
 @cindex repairing files
@@ -288,12 +331,15 @@ caused lziprecover to panic.
 Lziprecover can repair perfectly most files with small errors (up to one
 single-byte error per member), without the need of any extra redundance
 at all. If the reparation is successful, the repaired file will be
-identical bit for bit to the original.
+identical bit for bit to the original. This makes lzip files resistant
+to bit-flip, one of the most common forms of data corruption.
 
 The error may be located anywhere in the file except in the header
 (first 6 bytes of each member) or in the @samp{Member size} field of the
-trailer (last 8 bytes of each member). This makes lzip files resistant
-to bit-flip, one of the most common forms of data corruption.
+trailer (last 8 bytes of each member). If the error is in the header it
+can be easily repaired with a text editor like GNU Moe (@pxref{File
+format}). If the error is in the member size, it is enough to ignore the
+message about @samp{bad member size} when decompressing.
 
 Bit-flip happens when one bit in the file is changed from 0 to 1 or vice
 versa. It may be caused by bad RAM or even by natural radiation. I have
@@ -641,7 +687,7 @@ for all eternity, if not longer.
 
 If you find a bug in lziprecover, please send electronic mail to
 @email{lzip-bug@@nongnu.org}. Include the version number, which you can
-find by running @w{@samp{lziprecover --version}}.
+find by running @w{@code{lziprecover --version}}.
 
 
 @node Concept index