From 4850afd4bd49df457b87d52277f779bd33052450 Mon Sep 17 00:00:00 2001 From: Bastian Kleineidam Date: Thu, 18 Mar 2010 19:26:07 +0100 Subject: [PATCH] Explain commands in more detail. --- doc/changelog.txt | 1 + doc/patool.1 | 69 +++++++++++++++++++++-------------------------- doc/patool.txt | 59 ++++++++++++++++++++-------------------- 3 files changed, 62 insertions(+), 67 deletions(-) diff --git a/doc/changelog.txt b/doc/changelog.txt index 212afc9..958a979 100644 --- a/doc/changelog.txt +++ b/doc/changelog.txt @@ -1,6 +1,7 @@ 0.9 "" (released xx.xx.2010) * Do not use the diff -B option when comparing archives. + * Improved documentation: explain commands in more detail. 0.8 "Storage" (released 11.3.2010) diff --git a/doc/patool.1 b/doc/patool.1 index 4460356..3356238 100644 --- a/doc/patool.1 +++ b/doc/patool.1 @@ -15,11 +15,11 @@ .SH NAME patool - portable command line archive file manager .SH SYNOPSIS - \fBpatool\fP (\fBextract\fP|\fBlist\fP|\fBtest\fP) [\fIoptions\fP] <\fIarchive-file\fP>... - \fBpatool\fP \fBcreate\fP [\fIoptions\fP] <\fIarchive-file\fP> [\fIfiles\fP...] + \fBpatool\fP (\fBextract\fP|\fBlist\fP|\fBtest\fP) [\fI\-\-verbose\fP] <\fIarchive-file\fP>... + \fBpatool\fP \fBcreate\fP [\fI\-\-verbose\fP] <\fIarchive-file\fP> [\fIfiles\fP...] \fBpatool\fP \fBdiff\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 Various archive types can be created, extracted, tested and listed by \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 Several commands and options are available. .SS \fBextract\fP -Extract files from an archive. This is the default command if no -command was given. +Extract files from an archive. The original archive will never +be removed and is left as it is. .br -Often one wants to extract all files -in an archive to a single subdirectory. -However, some archives contain multiple files in their root -directories. The patool program overcomes this problem by -first extracting files to a unique (temporary) directory, and -then moving its contents back if possible. This also prevents -local files from being overwritten by mistake. +This is the default command if no command was given. +.PP +Files are always extracted to a unique temporary directory (in the +current working directory). If the archive contains exactly one +file or directory, the archive contents are moved to the current +working directory and the temporary directory will be removed. .br +This ensures that always one entry will be extracted. +.PP All extracted files are checked that they are readable by the current user. .TP \fB\-v\fP, \fB\-\-verbose\fP Be verbose when extracting (if the helper application supports it). -.TP -\fB\-\-help\fP -Show help for this command. .SS \fBlist\fP List files in an archive. .TP \fB\-v\fP, \fB\-\-verbose\fP Verbose archive listing (if the helper application supports it). -.TP -\fB\-\-help\fP -Show help for this command. .SS \fBcreate\fP 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 \fB\-v\fP, \fB\-\-verbose\fP Verbose operation (if the helper application supports it). -.TP -\fB\-\-help\fP -Show help for this command. .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 \fB\-v\fP, \fB\-\-verbose\fP Verbose archive testing (if the helper application supports it). -.TP -\fB\-\-help\fP -Show help for this command. .SS \fBdiff\fP -Show differences between two archives. -.TP -\fB\-\-help\fP -Show help for this command. +Show differences between two archives with the \fBdiff(1)\fP utility. +The diff options used are \fB\-urN\fP. .SS \fBrepack\fP -Repackage archive to a different format. -.TP -\fB\-\-help\fP -Show help for this command. +Repackage archive to a different format. The target archive format is +determined by the file extension. .SS \fBformats\fP -Show all supported archive formats. -.TP -\fB\-\-help\fP -Show help for this command. +Show all supported archive formats (ie. which helper applications +are available). +.SH HELP OPTION +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 Bastian Kleineidam .SH COPYRIGHT diff --git a/doc/patool.txt b/doc/patool.txt index 8fdb550..cee420e 100644 --- a/doc/patool.txt +++ b/doc/patool.txt @@ -6,11 +6,11 @@ NAME patool - portable command line archive file manager SYNOPSIS - patool (extract|list|test) [options] ... - patool create [options] [files...] + patool (extract|list|test) [--verbose] ... + patool create [--verbose] [files...] patool diff patool repack - patool formats [options] + patool formats DESCRIPTION Various archive types can be created, extracted, tested and listed by @@ -40,14 +40,16 @@ COMMANDS Several commands and options are available. extract - Extract files from an archive. This is the default command if no com‐ - mand was given. - Often one wants to extract all files in an archive to a single subdi‐ - rectory. However, some archives contain multiple files in their root - directories. The patool program overcomes this problem by first - extracting files to a unique (temporary) directory, and then moving its - contents back if possible. This also prevents local files from being - overwritten by mistake. + Extract files from an archive. The original archive will never be + removed and is left as it is. + This is the default command if no command was given. + + Files are always extracted to a unique temporary directory (in the cur‐ + rent working directory). If the archive contains exactly one file or + directory, the archive contents are moved to the current working direc‐ + 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 user. @@ -55,47 +57,46 @@ COMMANDS Be verbose when extracting (if the helper application supports it). - --help Show help for this command. - list List files in an archive. -v, --verbose Verbose archive listing (if the helper application supports it). - --help Show help for this command. - create 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 Verbose operation (if the helper application supports it). - --help Show help for this command. - 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 Verbose archive testing (if the helper application supports it). - --help Show help for this command. - diff - Show differences between two archives. - - --help Show help for this command. + Show differences between two archives with the diff(1) utility. The + diff options used are -urN. repack - Repackage archive to a different format. - - --help Show help for this command. + Repackage archive to a different format. The target archive format is + determined by the file extension. 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 Bastian Kleineidam