1 files changed, 348 insertions, 0 deletions
diff --git a/doc/tarlz.texi b/doc/tarlz.texi
new file mode 100644
index 0000000..db51dd6
--- /dev/null
+++ b/doc/tarlz.texi
@@ -0,0 +1,348 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename tarlz.info
+@documentencoding ISO-8859-15
+@settitle Tarlz Manual
+@finalout
+@c %**end of header
+
+@set UPDATED 23 April 2018
+@set VERSION 0.4
+
+@dircategory Data Compression
+@direntry
+* Tarlz: (tarlz).               Archiver with multimember lzip compression
+@end direntry
+
+
+@ifnothtml
+@titlepage
+@title Tarlz
+@subtitle Archiver with multimember lzip compression
+@subtitle for Tarlz version @value{VERSION}, @value{UPDATED}
+@author by Antonio Diaz Diaz
+
+@page
+@vskip 0pt plus 1filll
+@end titlepage
+
+@contents
+@end ifnothtml
+
+@node Top
+@top
+
+This manual is for Tarlz (version @value{VERSION}, @value{UPDATED}).
+
+@menu
+* Introduction::           Purpose and features of tarlz
+* Invoking tarlz::         Command line interface
+* Examples::               A small tutorial with examples
+* Problems::               Reporting bugs
+* Concept index::          Index of concepts
+@end menu
+
+@sp 1
+Copyright @copyright{} 2013-2018 Antonio Diaz Diaz.
+
+This manual is free documentation: you have unlimited permission
+to copy, distribute and modify it.
+
+
+@node Introduction
+@chapter Introduction
+@cindex introduction
+
+Tarlz is a small and simple implementation of the tar archiver. By
+default tarlz creates, lists and extracts archives in the 'ustar' format
+compressed with lzip on a per file basis. Tarlz can append files to the
+end of such compressed archives.
+
+Each tar member is compressed in its own lzip member, as well as the
+end-of-file blocks. This same method works for any tar format (gnu,
+ustar, posix) and is fully backward compatible with standard tar tools
+like GNU tar, which treat the resulting multimember tar.lz archive like
+any other tar.lz archive.
+
+Tarlz can create tar archives with four levels of compression
+granularity; per file, per directory, appendable solid, and solid.
+
+Tarlz is intended as a showcase project for the maintainers of real tar
+programs to evaluate the format and perhaps implement it in their tools.
+
+The diagram below shows the correspondence between tar members (formed
+by a header plus optional data) in the tar archive and
+@uref{http://www.nongnu.org/lzip/manual/lzip_manual.html#File-format,,lzip members}
+in the resulting multimember tar.lz archive:
+@ifnothtml
+@xref{File format,,,lzip}.
+@end ifnothtml
+
+@verbatim
+tar
++========+======+========+======+========+======+========+
+| header | data | header | data | header | data |   eof  |
++========+======+========+======+========+======+========+
+
+tar.lz
++===============+===============+===============+========+
+|     member    |     member    |     member    | member |
++===============+===============+===============+========+
+@end verbatim
+
+@noindent
+Of course, compressing each file (or each directory) individually is
+less efficient than compressing the whole tar archive, but it has the
+following advantages:
+
+@itemize @bullet
+@item
+The resulting multimember tar.lz archive can be decompressed in
+parallel with plzip, multiplying the decompression speed.
+
+@item
+New members can be appended to the archive (by removing the eof
+member) just like to an uncompressed tar archive.
+
+@item
+It is a safe posix-style backup format. In case of corruption,
+tarlz can extract all the undamaged members from the tar.lz
+archive, skipping over the damaged members, just like the standard
+(uncompressed) tar. Moreover, lziprecover can be used to recover at
+least part of the contents of the damaged members.
+
+@item
+A multimember tar.lz archive is usually smaller than the
+corresponding solidly compressed tar.gz archive, except when
+individually compressing files smaller than about 32 KiB.
+@end itemize
+
+
+@node Invoking tarlz
+@chapter Invoking tarlz
+@cindex invoking
+@cindex options
+@cindex usage
+@cindex version
+
+The format for running tarlz is:
+
+@example
+tarlz [@var{options}] [@var{files}]
+@end example
+
+@noindent
+On archive creation or appending, tarlz removes leading and trailing
+slashes from file names, as well as file name prefixes containing a
+@samp{..} component. On extraction, archive members containing a
+@samp{..} component are skipped.
+
+tarlz supports the following options:
+
+@table @code
+@item -h
+@itemx --help
+Print an informative help message describing the options and exit.
+
+@item -V
+@itemx --version
+Print the version number of tarlz on the standard output and exit.
+
+@item -c
+@itemx --create
+Create a new archive.
+
+@item -C @var{dir}
+@itemx --directory=@var{dir}
+Change to directory @var{dir}. When creating or appending, the position
+of each @code{-C} option in the command line is significant; it will
+change the current working directory for the following @var{files} until
+a new @code{-C} option appears in the command line. When extracting, all
+the @code{-C} options are executed in sequence before starting the
+extraction. Listing ignores any @code{-C} options specified. @var{dir}
+is relative to the then current working directory, perhaps changed by a
+previous @code{-C} option.
+
+@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.
+
+@item -q
+@itemx --quiet
+Quiet operation. Suppress all messages.
+
+@item -r
+@itemx --append
+Append files to the end of an 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.
+
+@item -t
+@itemx --list
+List the contents of an archive.
+
+@item -v
+@itemx --verbose
+Verbosely list files processed.
+
+@item -x
+@itemx --extract
+Extract files from an archive.
+
+@item -0 .. -9
+Set the compression level. The default compression level is @samp{-6}.
+
+@item --asolid
+When creating or appending to a compressed archive, use appendable solid
+compression. All the files being added to the archive are compressed
+into a single lzip member, but the end-of-file blocks are compressed
+into a separate lzip member. This creates a solidly compressed
+appendable archive.
+
+@item --dsolid
+When creating or appending to a compressed archive, use solid
+compression for each directory especified in the command line. The
+end-of-file blocks are compressed into a separate lzip member. This
+creates a compressed appendable archive with a separate lzip member for
+each top-level directory.
+
+@item --solid
+When creating or appending to a compressed archive, use solid
+compression. The files being added to the archive, along with the
+end-of-file blocks, are compressed into a single lzip member. The
+resulting archive is not appendable. No more files can be later appended
+to the archive without decompressing it first.
+
+@item --group=@var{group}
+When creating or appending, use @var{group} for files added to the
+archive. If @var{group} is not a valid group name, it is decoded as a
+decimal numeric group ID.
+
+@item --owner=@var{owner}
+When creating or appending, use @var{owner} for files added to the
+archive. If @var{owner} is not a valid user name, it is decoded as a
+decimal numeric user ID.
+
+@item --uncompressed
+With @code{--create}, don't compress the created tar archive. Create an
+uncompressed tar archive instead.
+
+@end table
+
+Exit status: 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 tarlz to panic.
+
+
+@node Examples
+@chapter A small tutorial with examples
+@cindex examples
+
+@noindent
+Example 1: Create a multimember compressed archive @samp{archive.tar.lz}
+containing files @samp{a}, @samp{b} and @samp{c}.
+
+@example
+tarlz -cf archive.tar.lz a b c
+@end example
+
+@sp 1
+@noindent
+Example 2: Append files @samp{d} and @samp{e} to the multimember
+compressed archive @samp{archive.tar.lz}.
+
+@example
+tarlz -rf archive.tar.lz d e
+@end example
+
+@sp 1
+@noindent
+Example 3: Create a solidly compressed appendable archive
+@samp{archive.tar.lz} containing files @samp{a}, @samp{b} and @samp{c}.
+Then append files @samp{d} and @samp{e} to the archive.
+
+@example
+tarlz --asolid -cf archive.tar.lz a b c
+tarlz --asolid -rf archive.tar.lz d e
+@end example
+
+@sp 1
+@noindent
+Example 4: Create a compressed appendable archive containing directories
+@samp{dir1}, @samp{dir2} and @samp{dir3} with a separate lzip member per
+directory. Then append files @samp{a}, @samp{b}, @samp{c}, @samp{d} and
+@samp{e} to the archive, all of them contained in a single lzip member.
+The resulting archive @samp{archive.tar.lz} contains 5 lzip members
+(including the eof member).
+
+@example
+tarlz --dsolid -cf archive.tar.lz dir1 dir2 dir3
+tarlz --asolid -rf archive.tar.lz a b c d e
+@end example
+
+@sp 1
+@noindent
+Example 5: Create a solidly compressed archive @samp{archive.tar.lz}
+containing files @samp{a}, @samp{b} and @samp{c}. Note that no more
+files can be later appended to the archive without decompressing it
+first.
+
+@example
+tarlz --solid -cf archive.tar.lz a b c
+@end example
+
+@sp 1
+@noindent
+Example 6: Extract all files from archive @samp{archive.tar.lz}.
+
+@example
+tarlz -xf archive.tar.lz
+@end example
+
+@sp 1
+@noindent
+Example 7: Extract files @samp{a} and @samp{c} from archive
+@samp{archive.tar.lz}.
+
+@example
+tarlz -xf archive.tar.lz a c
+@end example
+
+@sp 1
+@noindent
+Example 8: Copy the contents of directory @samp{sourcedir} to the
+directory @samp{targetdir}.
+
+@example
+tarlz -C sourcedir -c . | tarlz -C targetdir -x
+@end example
+
+
+@node Problems
+@chapter Reporting bugs
+@cindex bugs
+@cindex getting help
+
+There are probably bugs in tarlz. There are certainly errors and
+omissions in this manual. If you report them, they will get fixed. If
+you don't, no one will ever know about them and they will remain unfixed
+for all eternity, if not longer.
+
+If you find a bug in tarlz, please send electronic mail to
+@email{lzip-bug@@nongnu.org}. Include the version number, which you can
+find by running @w{@code{tarlz --version}}.
+
+
+@node Concept index
+@unnumbered Concept index
+
+@printindex cp
+
+@bye