Document the --outdir option.

doc/changelog.txt

@@ -1,5 +1,8 @@
 0.16 "" (released xx.xx.2012)
 
+  * Document the --outdir option for the extract command.
+    Closes: SF Bug #3363964
+
 0.15 "Contraband" (released 8.4.2012)
 
   * Print help when unknown options are given.

doc/patool.1

@@ -1,5 +1,5 @@
 .\"                                      -*- nroff -*-
-.\" Copyright (C) 2010-2011 Bastian Kleineidam
+.\" Copyright (C) 2010-2012 Bastian Kleineidam
 .\"
 .\" This program is free software: you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
@@ -15,8 +15,9 @@
 .SH NAME
 patool - portable command line archive file manager
 .SH SYNOPSIS
- \fBpatool\fP (\fBextract\fP|\fBlist\fP|\fBtest\fP) [\fI\-\-verbose\fP] <\fIarchive-file\fP>...
+ \fBpatool\fP (\fBlist\fP|\fBtest\fP) [\fB\-\-verbose\fP] <\fIarchive-file\fP>...
- \fBpatool\fP \fBcreate\fP [\fI\-\-verbose\fP] <\fIarchive-file\fP> [\fIfiles\fP...]
+ \fBpatool\fP \fBextract\fP [\fB\-\-verbose\fP] [\fB\-\-outdir=\fP\fIDIRNAME\fP] <\fIarchive-file\fP>...
+ \fBpatool\fP \fBcreate\fP [\fB\-\-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
@@ -102,4 +103,4 @@ For example:
 .SH AUTHOR
 Bastian Kleineidam <calvin@users.sourceforge.net>
 .SH COPYRIGHT
-Copyright \(co 2010-2011 Bastian Kleineidam
+Copyright \(co 2010-2012 Bastian Kleineidam

doc/patool.txt

@@ -6,29 +6,31 @@ NAME
        patool - portable command line archive file manager
 
 SYNOPSIS
-        patool (extract|list|test) [--verbose] <archive-file>...
+        patool (list|test) [--verbose] <archive-file>...
+        patool   extract   [--verbose]   [--outdir=DIRNAME]  <archive-
+       file>...
         patool create [--verbose] <archive-file> [files...]
         patool diff <archive1> <archive2>
         patool repack <archive1> <archive2>
         patool formats
 
 DESCRIPTION
-       Various  archive  types  can  be created, extracted, tested and
+       Various archive types can be  created,  extracted,  tested  and
-       listed by patool. The advantage of patool is its simplicity  in
+       listed  by patool. The advantage of patool is its simplicity in
-       handling  archive  files without having to remember a myriad of
+       handling archive files without having to remember a  myriad  of
        programs and options.
 
-       The archive format is determined by the file(1) program and  as
+       The  archive format is determined by the file(1) program and as
        a fallback by the archive file extension.
 
-       patool  supports  7z  (.7z), ACE (.ace), ALZIP (.alz), AR (.a),
+       patool supports 7z (.7z), ACE (.ace), ALZIP  (.alz),  AR  (.a),
-       ARC (.arc), ARJ (.arj),  BZIP2  (.bz2),  CAB  (.cab),  compress
+       ARC  (.arc),  ARJ  (.arj),  BZIP2  (.bz2), CAB (.cab), compress
-       (.Z),  CPIO  (.cpio), DEB (.deb), GZIP (.gz), LRZIP (.lrz), LZH
+       (.Z), CPIO (.cpio), DEB (.deb), DMS (.dms), GZIP  (.gz),  LRZIP
-       (.lha, .lzh),  LZIP  (.lz),  LZMA  (.lzma),  LZOP  (.lzo),  RPM
+       (.lrz),  LZH  (.lha,  .lzh),  LZIP  (.lz),  LZMA  (.lzma), LZOP
-       (.rpm),  RAR  (.rar),  RZIP  (.rz),  TAR  (.tar), XZ (.xz), ZIP
+       (.lzo), RPM (.rpm), RAR (.rar),  RZIP  (.rz),  TAR  (.tar),  XZ
-       (.zip, .jar) and ZOO  (.zoo)  formats.   It  relies  on  helper
+       (.xz),  ZIP  (.zip, .jar) and ZOO (.zoo) formats.  It relies on
-       applications to handle those archive formats (for example bzip2
+       helper applications to handle those archive formats (for  exam‐
-       for BZIP2 archives).
+       ple bzip2 for BZIP2 archives).
 
 EXAMPLES
          patool extract archive.zip otherarchive.rar
@@ -42,48 +44,48 @@ COMMANDS
        Several commands and options are available.
 
    extract
-       Extract files from an archive. The original archive will  never
+       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
+       Files are always extracted to a unique temporary  directory  in
-       the current working directory. If the archive contains  exactly
+       the  current working directory. If the archive contains exactly
-       one  file  or  directory, the archive contents are moved to the
+       one file or directory, the archive contents are  moved  to  the
-       current working directory and the temporary directory  will  be
+       current  working  directory and the temporary directory will be
        removed.
-       This  prevents  cluttering the current working directory with a
+       This prevents cluttering the current working directory  with  a
        lot of files from the extracted archive.
 
-       All extracted files are ensured that they are readable  by  the
+       All  extracted  files are ensured that they are readable by the
        current user.
 
        -v, --verbose
-              Be  verbose  when  extracting (if the helper application
+              Be verbose when extracting (if  the  helper  application
               supports it).
 
    list
        List files in an archive.
 
        -v, --verbose
-              Verbose archive listing (if the helper application  sup‐
+              Verbose  archive listing (if the helper application sup‐
               ports it).
 
    create
-       Create  an  archive  from given files. At least on of the given
+       Create an archive from given files. At least on  of  the  given
-       files to add to the archive has to  exist  (non-existing  files
+       files  to  add  to the archive has to exist (non-existing files
-       are  ignored).   The  format of the archive to create is deter‐
+       are ignored).  The format of the archive to  create  is  deter‐
        mined by the archive file extension.
 
        -v, --verbose
-              Verbose operation (if the  helper  application  supports
+              Verbose  operation  (if  the helper application supports
               it).
 
    test
-       Test  files  in  an archive. If the helper application does not
+       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  sup‐
+              Verbose  archive testing (if the helper application sup‐
               ports it).
 
    diff
@@ -91,15 +93,15 @@ COMMANDS
        The diff options used are -urN.
 
    repack
-       Repackage archive to a different  format.  The  target  archive
+       Repackage  archive  to  a  different format. The target archive
        format is determined by the file extension.
 
    formats
-       Show  all  supported archive formats (ie. which helper applica‐
+       Show all supported archive formats (ie. which  helper  applica‐
        tions are available).
 
 HELP OPTION
-       Specifying the help option displays help for patool itself,  or
+       Specifying  the help option displays help for patool itself, or
        a command.
        For example:
          patool --help - display help for patool
@@ -109,7 +111,7 @@ AUTHOR
        Bastian Kleineidam <calvin@users.sourceforge.net>
 
 COPYRIGHT
-       Copyright © 2010 Bastian Kleineidam
+       Copyright © 2010-2012 Bastian Kleineidam
 
 
 

patool

@@ -46,7 +46,11 @@ def handle_multi_archive(archives, cmd, **kwargs):
     return res
 
 
-@baker.command(default=True, shortopts=shortopts, params=params)
+extract_params = {
+  "outdir": "Extract to given directory.",
+}
+extract_params.update(params)
+@baker.command(default=True, shortopts=shortopts, params=extract_params)
 def extract (archive, *archives, **kwargs):
     """Extract files from archive(s)."""
     return handle_multi_archive((archive,)+archives, 'extract', **kwargs)