Merging upstream version 0.14.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 63 insertions, 33 deletions

diff --git a/doc/tarlz.texi b/doc/tarlz.texi
index 47f01a2..da7abfa 100644
--- a/doc/tarlz.texi
+++ b/doc/tarlz.texi
@@ -6,8 +6,8 @@
 @finalout
 @c %**end of header
 
-@set UPDATED 27 February 2019
-@set VERSION 0.13
+@set UPDATED 12 March 2019
+@set VERSION 0.14
 
 @dircategory Data Compression
 @direntry
@@ -69,7 +69,8 @@ tar, which treat it like any other tar.lz archive. Tarlz can append files to
 the end of such compressed archives.
 
 Tarlz can create tar archives with five levels of compression granularity;
-per file, per block (default), per directory, appendable solid, and solid.
+per file (---no-solid), per block (---bsolid, default), per directory
+(---dsolid), appendable solid (---asolid), and solid (---solid).
 
 @noindent
 Of course, compressing each file (or each directory) individually can't
@@ -140,8 +141,7 @@ equivalent to @samp{-1 --solid}
 tarlz supports the following options:
 
 @table @code
-@item -h
-@itemx --help
+@item --help
 Print an informative help message describing the options and exit.
 
 @item -V
@@ -151,13 +151,15 @@ This version number should be included in all bug reports.
 
 @item -A
 @itemx --concatenate
-Append tar.lz archives to the end of a tar.lz archive. All the archives
-involved must be regular (seekable) files compressed as multimember lzip
-files, and the two end-of-file blocks plus any zero padding must be
-contained in the last lzip member of each archive. The intermediate
-end-of-file blocks are removed as each new archive is concatenated. Exit
-with status 0 without modifying the archive if no @var{files} have been
-specified. Tarlz can't concatenate uncompressed tar archives.
+Append one or more archives to the end of an archive. All the archives
+involved must be regular (seekable) files, and must be either all compressed
+or all uncompressed. Compressed and uncompressed archives can't be mixed.
+Compressed archives must be multimember lzip files with the two end-of-file
+blocks plus any zero padding contained in the last lzip member of each
+archive. The intermediate end-of-file blocks are removed as each new archive
+is concatenated. If the archive is uncompressed, tarlz parses and skips tar
+headers until it finds the end-of-file blocks. Exit with status 0 without
+modifying the archive if no @var{files} have been specified.
 
 @anchor{--data-size}
 @item -B @var{bytes}
@@ -190,19 +192,34 @@ option appears after a relative filename in the command line.
 @itemx --diff
 Find differences between archive and file system. For each tar member in the
 archive, verify that the corresponding file exists and is of the same type
-(regular file, directory, etc). Report the differences found in type, mode
-(permissions), owner and group IDs, modification time, file size, file
-contents (of regular files), target (of symlinks) and device number (of
-block/character special files).
+(regular file, directory, etc). Report on standard output the differences
+found in type, mode (permissions), owner and group IDs, modification time,
+file size, file contents (of regular files), target (of symlinks) and device
+number (of block/character special files).
+
+As tarlz removes leading slashes from member names, the @samp{-C} option may
+be used in combination with @samp{--diff} when absolute filenames were used
+on archive creation: @w{@samp{tarlz -C / -d}}. Alternatively, tarlz may be
+run from the root directory to perform the comparison.
 
 @item --ignore-ids
 Make @samp{--diff} ignore differences in owner and group IDs. This option is
 useful when comparing an @samp{--anonymous} archive.
 
+@item --exclude=@var{pattern}
+Exclude files matching a shell pattern like @samp{*.o}. A file is considered
+to match if any component of the filename matches. For example, @samp{*.o}
+matches @samp{foo.o}, @samp{foo.o/bar} and @samp{foo/bar.o}.
+
 @item -f @var{archive}
 @itemx --file=@var{archive}
-Use archive file @var{archive}. @samp{-} used as an @var{archive}
-argument reads from standard input or writes to standard output.
+Use archive file @var{archive}. @samp{-} used as an @var{archive} argument
+reads from standard input or writes to standard output.
+
+@item -h
+@itemx --dereference
+Follow symbolic links during archive creation, appending or comparison.
+Archive or compare the files they point to instead of the links themselves.
 
 @item -n @var{n}
 @itemx --threads=@var{n}
@@ -226,14 +243,17 @@ Quiet operation. Suppress all messages.
 
 @item -r
 @itemx --append
-Append files to the end of a tar.lz archive. The archive must be a
-regular (seekable) file compressed as a multimember lzip file, and the
-two end-of-file blocks plus any zero padding must be contained in the
-last lzip member of the archive. First this last member is removed, then
-the new members are appended, and then a new end-of-file member is
-appended to the archive. Exit with status 0 without modifying the
-archive if no @var{files} have been specified. Tarlz can't append files
-to an uncompressed tar archive.
+Append files to the end of an archive. The archive must be a regular
+(seekable) file either compressed or uncompressed. Compressed members can't
+be appended to an uncompressed archive, nor vice versa. If the archive is
+compressed, it must be a multimember lzip file with the two end-of-file
+blocks plus any zero padding contained in the last lzip member of the
+archive. Appending works as follows; first the end-of-file blocks are
+removed, then the new members are appended, and finally two new end-of-file
+blocks are appended to the archive. If the archive is uncompressed, tarlz
+parses and skips tar headers until it finds the end-of-file blocks. Exit
+with status 0 without modifying the archive if no @var{files} have been
+specified.
 
 @item -t
 @itemx --list
@@ -250,9 +270,10 @@ Extract files from an archive. If @var{files} are given, extract only
 the @var{files} given. Else extract all the files in the archive.
 
 @item -0 .. -9
-Set the compression level. The default compression level is @samp{-6}.
-Like lzip, tarlz also minimizes the dictionary size of the lzip members
-it creates, reducing the amount of memory required for decompression.
+Set the compression level for @samp{--create} and @samp{--append}. The
+default compression level is @samp{-6}. Like lzip, tarlz also minimizes the
+dictionary size of the lzip members it creates, reducing the amount of
+memory required for decompression.
 
 @multitable {Level} {Dictionary size} {Match length limit}
 @item Level @tab Dictionary size @tab Match length limit
@@ -269,8 +290,10 @@ it creates, reducing the amount of memory required for decompression.
 @end multitable
 
 @item --uncompressed
-With @samp{--create}, don't compress the created tar archive. Create an
-uncompressed tar archive instead.
+With @samp{--create}, don't compress the tar archive created. Create an
+uncompressed tar archive instead. With @samp{--append}, don't compress the
+new members appended to the tar archive. Compressed members can't be
+appended to an uncompressed archive, nor vice versa.
 
 @item --asolid
 When creating or appending to a compressed archive, use appendable solid
@@ -340,6 +363,13 @@ missing CRC instead of as a corrupt record. This misleading
 format; i.e., the lack of a mandatory check sequence in the extended
 records. @xref{crc32}.
 
+@item --out-slots=@var{n}
+Number of @w{1 MiB} output packets buffered per worker thread during
+multi-threaded creation or appending to compressed archives. Increasing the
+number of packets may increase compression speed if the files being archived
+are larger than @w{64 MiB} compressed, but requires more memory. Valid
+values range from 1 to 1024. The default value is 64.
+
 @ignore
 @item --permissive
 Allow some violations of the archive format, like consecutive extended
@@ -382,7 +412,7 @@ The members simply appear one after another in the file, with no
 additional information before, between, or after them.
 
 Each lzip member contains one or more tar members in a simplified posix
-pax interchange format; the only pax typeflag value supported by tarlz
+pax interchange format. The only pax typeflag value supported by tarlz
 (in addition to the typeflag values defined by the ustar format) is
 @samp{x}. The pax format is an extension on top of the ustar format that
 removes the size limitations of the ustar format.
@@ -766,7 +796,7 @@ the number of available processors), the uncompressed archive must be at
 least as large as the number of worker threads times the block size
 (@pxref{--data-size}). Else some processors will not get any data to
 compress, and compression will be proportionally slower. The maximum speed
-increase achievable on a given file is limited by the ratio
+increase achievable on a given archive is limited by the ratio
 @w{(uncompressed_size / data_size)}. For example, a tarball the size of gcc
 or linux will scale up to 10 or 12 processors at level -9.