From 1caca14f2cd64528f6b1ccdd76536400e9385211 Mon Sep 17 00:00:00 2001
From: Bastian Kleineidam <bastian.kleineidam@web.de>
Date: Thu, 28 Feb 2013 21:58:37 +0100
Subject: [PATCH] Updated development docs. [ci skip]

---
 doc/development.txt | 57 ++++++++++++++++++++++-----------------------
 1 file changed, 28 insertions(+), 29 deletions(-)

diff --git a/doc/development.txt b/doc/development.txt
index e14868d..834c2ca 100644
--- a/doc/development.txt
+++ b/doc/development.txt
@@ -6,15 +6,15 @@ To do this, install the patool program, import the library and
 use one or more of the convenience functions.
 
 import patoolib
-if patoolib.extract("myarchive.zip", verbose=True) == 0:
-    print "Success."
-else:
-    print "Error."
+try:
+    patoolib.extract("myarchive.zip", verbose=True)
+    print("Success.")
+except patoolib.util.PatoolError as msg:
+    print("Error:", msg)
 
 General rules for all convenience functions:
 
-* All convenience function return zero when no error occurred, else
-  an integer unequal zero.
+* All convenience functions raise PatoolError on errors.
 
 * Error messages are printed on stderr, informative messages
   are printed on stdout.
@@ -24,55 +24,54 @@ General rules for all convenience functions:
 
 * Filenames can be relative or absolute.
 
+* If verbosity is increased, additional output of the archive
+  program is shown.
+
+* Usually the program to be executed is automatically determined
+  but it can be set manually with the program parameter.
+
 The convenience functions are:
 
-* ``def extract(archive, verbose=False, outdir=None)``
+* ``def extract_archive(archive, verbosity=0, outdir=None, program=None)``
   
   Extracts the given archive filename to the current working directory
   or if specified to the given directory name in outdir.
-  If verbose operation is set to True, additional output of the archive
-  program is shown.
   Checks that the archive exists and is readable before extracting it.
 
-* ``def list(archive, verbose=False)``
+* ``def list_archive(archive, verbosity=1, program=None)``
   
   Lists the contents of the given archive filename on stdout.
-  If verbose operation is set to True, additional output of the archive
-  program is shown.
   Checks that the archive exists and is readable before listing it.
 
-* ``def test(archive, verbose=False)``
+* ``def test_archive(archive, verbosity=0, program=None)``
   
   Tests the given archive filename.
-  If verbose operation is set to True, additional output of the archive
-  program is shown.
   Checks that the archive exists and is readable before testing it.
 
-* ``def create(archive, *filenames, **kwargs)``
+* ``def create_archive(archive, filenames, verbosity=0, program=None)``
   
   Creates a new archive. The type of archive is determined
   by the archive filename extension.
-  If verbose operation is set to True, additional output of the archive
-  program is shown.
   Checks that the archive is not already existing to avoid overwriting it.
   Also checks that the filename list is not empty and that all files exist
   and are readable.
 
-* ``def diff(archive1, archive2, verbose=False)``
+* ``diff_archives(archive1, archive2, verbosity=0)``
   
   This function lists differences in the content of the two archives.
   Both archives are extracted and the contents are compared
   recursively with the diff(1) program.
-  If verbose operation is set to True, additional output of the archive
-  program is shown.
   Checks that both archives exist and are readable.
 
-* ``def repack(archive1, archive2, verbose=False)``
-  
-  This function extracts the contents of archive1 and packs them
-  into archive2.
-  If verbose operation is set to True, additional output of the archive
-  program is shown.
-  Checks that archive1 exists and is readable. Also checks that
-  archive2 does not exist to avoid overwriting it.
+* ``def search_archive(pattern, archive, verbosity=0)``
 
+  This function searches the given pattern in the archive file contents
+  with grep(1).
+  Checks that archive exists and is readable.
+
+* ``repack_archive (archive, archive_new, verbosity=0)``
+  
+  This function extracts the contents of the archive and packs them
+  into archive_new.
+  Checks that archive exists and is readable. Also checks that
+  archive_new does not exist to avoid overwriting it.