Explain commands in more detail.

This commit is contained in:
Bastian Kleineidam 2010-03-18 19:26:07 +01:00
parent 5e21670b8e
commit 4850afd4bd
3 changed files with 62 additions and 67 deletions

View File

@ -1,6 +1,7 @@
0.9 "" (released xx.xx.2010) 0.9 "" (released xx.xx.2010)
* Do not use the diff -B option when comparing archives. * Do not use the diff -B option when comparing archives.
* Improved documentation: explain commands in more detail.
0.8 "Storage" (released 11.3.2010) 0.8 "Storage" (released 11.3.2010)

View File

@ -15,11 +15,11 @@
.SH NAME .SH NAME
patool - portable command line archive file manager patool - portable command line archive file manager
.SH SYNOPSIS .SH SYNOPSIS
\fBpatool\fP (\fBextract\fP|\fBlist\fP|\fBtest\fP) [\fIoptions\fP] <\fIarchive-file\fP>... \fBpatool\fP (\fBextract\fP|\fBlist\fP|\fBtest\fP) [\fI\-\-verbose\fP] <\fIarchive-file\fP>...
\fBpatool\fP \fBcreate\fP [\fIoptions\fP] <\fIarchive-file\fP> [\fIfiles\fP...] \fBpatool\fP \fBcreate\fP [\fI\-\-verbose\fP] <\fIarchive-file\fP> [\fIfiles\fP...]
\fBpatool\fP \fBdiff\fP <\fIarchive1\fP> <\fIarchive2\fP> \fBpatool\fP \fBdiff\fP <\fIarchive1\fP> <\fIarchive2\fP>
\fBpatool\fP \fBrepack\fP <\fIarchive1\fP> <\fIarchive2\fP> \fBpatool\fP \fBrepack\fP <\fIarchive1\fP> <\fIarchive2\fP>
\fBpatool\fP \fBformats\fP [\fIoptions\fP] \fBpatool\fP \fBformats\fP
.SH DESCRIPTION .SH DESCRIPTION
Various archive types can be created, extracted, tested and listed by Various archive types can be created, extracted, tested and listed by
\fBpatool\fP. The advantage of patool is its simplicity in handling archive \fBpatool\fP. The advantage of patool is its simplicity in handling archive
@ -45,65 +45,58 @@ It relies on helper applications to handle those archive formats
.SH COMMANDS .SH COMMANDS
Several commands and options are available. Several commands and options are available.
.SS \fBextract\fP .SS \fBextract\fP
Extract files from an archive. This is the default command if no Extract files from an archive. The original archive will never
command was given. be removed and is left as it is.
.br .br
Often one wants to extract all files This is the default command if no command was given.
in an archive to a single subdirectory. .PP
However, some archives contain multiple files in their root Files are always extracted to a unique temporary directory (in the
directories. The patool program overcomes this problem by current working directory). If the archive contains exactly one
first extracting files to a unique (temporary) directory, and file or directory, the archive contents are moved to the current
then moving its contents back if possible. This also prevents working directory and the temporary directory will be removed.
local files from being overwritten by mistake.
.br .br
This ensures that always one entry will be extracted.
.PP
All extracted files are checked that they are readable by the All extracted files are checked that they are readable by the
current user. current user.
.TP .TP
\fB\-v\fP, \fB\-\-verbose\fP \fB\-v\fP, \fB\-\-verbose\fP
Be verbose when extracting (if the helper application supports it). Be verbose when extracting (if the helper application supports it).
.TP
\fB\-\-help\fP
Show help for this command.
.SS \fBlist\fP .SS \fBlist\fP
List files in an archive. List files in an archive.
.TP .TP
\fB\-v\fP, \fB\-\-verbose\fP \fB\-v\fP, \fB\-\-verbose\fP
Verbose archive listing (if the helper application supports it). Verbose archive listing (if the helper application supports it).
.TP
\fB\-\-help\fP
Show help for this command.
.SS \fBcreate\fP .SS \fBcreate\fP
Create an archive from given files. At least on of the given files to add Create an archive from given files. At least on of the given files to add
to the archive has to exist. to the archive has to exist (non-existing files are ignored).
The format of the archive to create is determined by the archive file
extension.
.TP .TP
\fB\-v\fP, \fB\-\-verbose\fP \fB\-v\fP, \fB\-\-verbose\fP
Verbose operation (if the helper application supports it). Verbose operation (if the helper application supports it).
.TP
\fB\-\-help\fP
Show help for this command.
.SS \fBtest\fP .SS \fBtest\fP
Test files in an archive. Test files in an archive. If the helper application does not support
testing, the archive contents are listed instead.
.TP .TP
\fB\-v\fP, \fB\-\-verbose\fP \fB\-v\fP, \fB\-\-verbose\fP
Verbose archive testing (if the helper application supports it). Verbose archive testing (if the helper application supports it).
.TP
\fB\-\-help\fP
Show help for this command.
.SS \fBdiff\fP .SS \fBdiff\fP
Show differences between two archives. Show differences between two archives with the \fBdiff(1)\fP utility.
.TP The diff options used are \fB\-urN\fP.
\fB\-\-help\fP
Show help for this command.
.SS \fBrepack\fP .SS \fBrepack\fP
Repackage archive to a different format. Repackage archive to a different format. The target archive format is
.TP determined by the file extension.
\fB\-\-help\fP
Show help for this command.
.SS \fBformats\fP .SS \fBformats\fP
Show all supported archive formats. Show all supported archive formats (ie. which helper applications
.TP are available).
\fB\-\-help\fP .SH HELP OPTION
Show help for this command. Specifying the help option displays help for patool itself, or a
command.
.br
For example:
\fBpatool \-\-help\fP - display help for patool
\fBpatool extract \-\-help\fP - display help for the extract command
.SH AUTHOR .SH AUTHOR
Bastian Kleineidam <calvin@users.sourceforge.net> Bastian Kleineidam <calvin@users.sourceforge.net>
.SH COPYRIGHT .SH COPYRIGHT

View File

@ -6,11 +6,11 @@ NAME
patool - portable command line archive file manager patool - portable command line archive file manager
SYNOPSIS SYNOPSIS
patool (extract|list|test) [options] <archive-file>... patool (extract|list|test) [--verbose] <archive-file>...
patool create [options] <archive-file> [files...] patool create [--verbose] <archive-file> [files...]
patool diff <archive1> <archive2> patool diff <archive1> <archive2>
patool repack <archive1> <archive2> patool repack <archive1> <archive2>
patool formats [options] patool formats
DESCRIPTION DESCRIPTION
Various archive types can be created, extracted, tested and listed by Various archive types can be created, extracted, tested and listed by
@ -40,14 +40,16 @@ COMMANDS
Several commands and options are available. Several commands and options are available.
extract extract
Extract files from an archive. This is the default command if no com Extract files from an archive. The original archive will never be
mand was given. removed and is left as it is.
Often one wants to extract all files in an archive to a single subdi This is the default command if no command was given.
rectory. However, some archives contain multiple files in their root
directories. The patool program overcomes this problem by first Files are always extracted to a unique temporary directory (in the cur
extracting files to a unique (temporary) directory, and then moving its rent working directory). If the archive contains exactly one file or
contents back if possible. This also prevents local files from being directory, the archive contents are moved to the current working direc
overwritten by mistake. tory and the temporary directory will be removed.
This ensures that always one entry will be extracted.
All extracted files are checked that they are readable by the current All extracted files are checked that they are readable by the current
user. user.
@ -55,47 +57,46 @@ COMMANDS
Be verbose when extracting (if the helper application supports Be verbose when extracting (if the helper application supports
it). it).
--help Show help for this command.
list list
List files in an archive. List files in an archive.
-v, --verbose -v, --verbose
Verbose archive listing (if the helper application supports it). Verbose archive listing (if the helper application supports it).
--help Show help for this command.
create create
Create an archive from given files. At least on of the given files to Create an archive from given files. At least on of the given files to
add to the archive has to exist. add to the archive has to exist (non-existing files are ignored). The
format of the archive to create is determined by the archive file
extension.
-v, --verbose -v, --verbose
Verbose operation (if the helper application supports it). Verbose operation (if the helper application supports it).
--help Show help for this command.
test test
Test files in an archive. Test files in an archive. If the helper application does not support
testing, the archive contents are listed instead.
-v, --verbose -v, --verbose
Verbose archive testing (if the helper application supports it). Verbose archive testing (if the helper application supports it).
--help Show help for this command.
diff diff
Show differences between two archives. Show differences between two archives with the diff(1) utility. The
diff options used are -urN.
--help Show help for this command.
repack repack
Repackage archive to a different format. Repackage archive to a different format. The target archive format is
determined by the file extension.
--help Show help for this command.
formats formats
Show all supported archive formats. Show all supported archive formats (ie. which helper applications are
available).
--help Show help for this command. HELP OPTION
Specifying the help option displays help for patool itself, or a com
mand.
For example:
patool --help - display help for patool
patool extract --help - display help for the extract command
AUTHOR AUTHOR
Bastian Kleineidam <calvin@users.sourceforge.net> Bastian Kleineidam <calvin@users.sourceforge.net>