Update README file.

Several pieces of information were outdated for the 3.2 release.  Add a
section for the API changes between 3.1 and 3.2.

Signed-off-by: Xavier Chantry <shiningxc@gmail.com>
[Dan: small updates/grammar corrections]
Signed-off-by: Dan McGee <dan@archlinux.org>

1 files changed, 99 insertions, 70 deletions

diff --git a/README b/README
index 46b5bb2b..1dadc921 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ ALPM library overview & internals
 =================================
 
 Here is a list of the main objects and files from the ALPM (i.e. Arch Linux
-Package Management) library. This document, whilst not exhaustive, also
+Package Management) library. This document, while not exhaustive, also
 indicates some limitations (on purpose, or sometimes due to its poor design) of
 the library at the present time.
 
@@ -13,9 +13,8 @@ the frontend. Lots of structures are of an opaque type and their fields are
 only accessible in read-only mode, through some clearly defined functions.
 
 In addition to "alpm.h", the interfaces of "alpm_list.h" have also been made
-available to the frontend. It is not a requirement for the frontend to use
-these list functions; however, it prevents frontends from having to reimplement
-a list data structure.
+available to the frontend, for allowing it to manipulate the lists returned by
+the backend.
 
 Several structures and functions have been renamed compared to pacman 2.9 code.
 This was done at first for the sake of naming scheme consistency, and then
@@ -25,7 +24,7 @@ same name declared in both spaces. To avoid such conflicts, internal function
 names have been prepended with "_alpm_".
 
 In a general manner, public library functions are named "alpm_<type>_<action>"
-(examples: alpm_trans_commit(), alpm_release(), alpm_pkg_getinfo(), ...).
+(examples: alpm_trans_commit(), alpm_release(), alpm_pkg_get_name(), ...).
 Internal (and thus private) functions should be named "_alpm_XXX" for instance
 (examples: _alpm_needbackup(), _alpm_runscriplet(), ...). Functions defined and
 used inside a single file should be defined as "static".
@@ -33,59 +32,63 @@ used inside a single file should be defined as "static".
 
 [Initialization]
 
-alpm_init() is used to initialize library internals and to create
+alpm_initialize() is used to initialize library internals and to create
 a transparent handle object. Before its call, the library can't be used.
 
-alpm_lib_release() just does the opposite (memory used by the library, and the
-handle is freed).  After its call, the library is no longer available.
+alpm_release() just does the opposite (memory used by the library, and the
+handle is freed). After its call, the library is no longer available.
 
 
 [Options]
 
-In the future, the library will not use any configuration file.  It will be up
-to the front end to The handle holds a
-number of configuration options instead (IGNOREPKG, SYSLOG usage,
-log file name, registered databases, ...).
+The library does not use any configuration file. It is up to the front end to
+configure the library as needed; the handle holds a number of configuration
+options instead.
 
 All of the following options have a alpm_option_get_* and alpm_option_set_*
-function for getting and setting the value.  The cannot be set before the
+function for getting and setting the value. They cannot be set before the
 library is initialized.
 
 * logcb: The callback function for "log" operations.
-* dlcb: The callback function for download progress.
-* logmask: The logging mask for which level of output is sent to the logcb.
-* root: The root directory on which pacman operates (Default: /)
-* dbpath: The base path to pacman's databases (Default: var/lib/pacman)
-* cachedir: The base path to pacman's download cache (Default: var/cache/pacman)
-* logfile: The base path to pacman's log file (Default: var/log/pacman.log)
+* dlcb: The callback function for download progress of each package.
+* totaldlcb: The callback function for overall download progress.
+* root: The root directory for pacman to install to (Default: /)
+* dbpath: The toplevel database directory (Default: /var/lib/pacman)
+* logfile: The base path to pacman's log file (Default: /var/log/pacman.log)
 * usesyslog: Log to syslog instead of `logfile` for file-base logging.
 * xfercommand: The command to use for downloading instead of pacman's internal
-             downloading functionality.
+               downloading functionality.
 * nopassiveftp: Do not use passive FTP commands for ftp connections.
-* chomp: No way, easter eggs are secret!
-* usecolor: Unimplemented, but for the future. You can assume what it means.
 
-The following options also have a `alpm_option_add_*` function, as the values
-are list structures (NOTE: The add functions are NOT plural, as they're in
-english: alpm_option_get_noupgrades -> alpm_option_add_noupgrade).
+The following options also have `alpm_option_{add,remove}_*` functions, as the
+values are list structures.
+NOTE: The add and remove functions are NOT plural, as they are in English:
+alpm_option_{get,set}_noupgrades -> alpm_option_{add,remove}_noupgrade.
 
+* cachedirs: Paths to pacman's download caches (Default: /var/cache/pacman/pkg)
 * noupgrades: Files which will never be touched by pacman (extracted as .pacnew)
 * noextracts: Files which will never be extracted at all (no .pacnew file)
 * ignorepkgs: Packages to ignore when upgrading.
-* holdpkgs: Packages which must be upgraded before continuing.
+* ignoregrps: Groups to ignore when upgrading.
+* holdpkgs: Important packages which need a confirmation before being removed.
 
 The following options are read-only, having ONLY alpm_option_get_* functions:
 
+* lockfile: The file used for locking the database
+  (Default: <dbpath>/db.lck)
 * localdb: A pmdb_t structure for the local (installed) database
 * syncdbs: A list of pmdb_t structures to which pacman can sync from.
 
+The following options are write-only, having ONLY alpm_option_set_* functions:
+
+* usedelta: Download delta files instead of complete packages if possible.
 
 [Transactions]
 
-The transaction sturcture permits easy manipulations of several packages
+The transaction structure permits easy manipulations of several packages
 at a time (i.e. adding, upgrade and removal operations).
 
-A transaction can be initiated with a type (ADD, UPGRADE or REMOVE),
+A transaction can be initiated with a type (SYNC, UPGRADE or REMOVE),
 and some flags (NODEPS, FORCE, CASCADE, ...).
 
 Note: there can only be one type at a time: a transaction is either
@@ -105,7 +108,7 @@ These targets represent the list of packages to be handled.
 
 Then, a transaction needs to be prepared (alpm_trans_prepare()). It
 means that the various targets added, will be inspected and challenged
-against the set of already installed packages (dependency checkings,
+against the set of already installed packages (dependency checking, etc...)
 
 Last, a callback is associated with each transaction. During the
 transaction resolution, each time a new step is started or done (i.e
@@ -116,27 +119,27 @@ the resolution. Can be useful to implement a progress bar.
 
 [Package Cache]
 
-libalpm maintains two caches for each DB.  One is a general package cache, the
-other is a group cache (for package groups).  These caches are loaded on demand,
-and freed when the libary is.
-It is important to note tha, as a general rule, package structures should NOT be
-freed manually, as they SHOULD be part of the cache.
-The cache of a database is always updated by the library after
-an operation changing the database content (adding and/or removal of
-packages). Beware frontends ;)
+libalpm maintains two caches for each DB. One is a general package cache, the
+other is a group cache (for package groups). These caches are loaded on demand,
+and freed when the library is.
+
+It is important to note that, as a general rule, package structures should NOT
+be freed manually, as they SHOULD be part of the cache.  The cache of a
+database is always updated by the library after an operation changing the
+database content (adding and/or removal of packages).  Beware frontends ;)
 
 
 [Package]
 
-The package structure maintains all information for a package.  In general,
-packages should never be freed from front-ends, as they should always be part of
-the package cache.
+The package structure maintains all information for a package. In general,
+packages should never be freed from front-ends, as they should always be part
+of the package cache.
 
-The 'origin' data member indicates whether the package is from a file
-(i.e. -U operations) or from the package cache.  In the case of a file, all data
-members available are present in the structure.  Packages indicated as being
-from the cache have data members filled on demand.  For this reason, the
-alpm_pkg_get_* functions will load the data from the DB as needed.
+The 'origin' data member indicates whether the package is from a file (i.e. -U
+operations) or from the package cache. In the case of a file, all data members
+available are present in the structure. Packages indicated as being from the
+cache have data members filled on demand. For this reason, the alpm_pkg_get_*
+functions will load the data from the DB as needed.
 
 
 [Errors]
@@ -149,13 +152,15 @@ indicating success, -1 indicating a failure.
 If -1 is returned, the variable pm_errno is set to a meaningful value
 Wise frontends should always care for these returned values.
 
-Note: the helper function alpm_strerror() can also be used to translate
-the error code into a more friendly sentence.
+Note: the helper function alpm_strerror() can also be used to translate one
+specified error code into a more friendly sentence, and alpm_strerrorlast()
+does the same for the last error encountered (represented by pm_errno).
 
 
 [List - alpm_list_t] 
+
 The alpm_list_t structure is a doubly-linked list for use with the libalpm
-routines.  This type is provided publicly so that frontends are free to use it
+routines. This type is provided publicly so that frontends are free to use it
 if they have no native list type (C++, glib, python, etc all have list types).
 See the proper man pages for alpm_list_t references.
 
@@ -179,41 +184,65 @@ perform a special action.
 
 [MAIN] (see pacman.c)
 
-Calls for alpm_lib_init(), and alpm_lib_release().
+Calls for alpm_initialize(), and alpm_release().
 Read the configuration file, and parse command line arguments.
 Based on the action requested, it initiates the appropriate transactions
-(see pacman_add(), pacman_remove(), pacman_sync() in files add.c,
+(see pacman_upgrade(), pacman_remove(), pacman_sync() in files upgrade.c,
 remove.c and sync.c).
 
 
-[CONFIGURATION] (see conf.c)
+[CONFIGURATION] (see conf.h)
 
-The frontend is using a configuration file, usually "/etc/pacman.conf".
-Part of these options are only useful for the frontend only (mainly,
-the download stuffs, and some options like HOLDPKG).
-The rest is used to configure the library.
+The frontend is using a configuration file, usually "/etc/pacman.conf".  Some
+of these options are only useful for the frontend only (mainly the ones used to
+control the output like showsize or totaldownload, or the behavior with
+cleanmethod and syncfirst).  The rest is used to configure the library.
 
 
-[ADD/UPGRADE/REMOVE/SYNC]
-
-Nothing new here, excepted some reorganization.
+[UPGRADE/REMOVE/SYNC]
 
 The file pacman.c has been divided into several smaller files, namely
-add.c, remove.c, sync.c and query.c, to hold the big parts: pacman_add,
+upgrade.c, remove.c, sync.c and query.c, to hold the big parts: pacman_upgrade,
 pacman_remove, pacman_sync.
 
 These 3 functions have been split to ease the code reading.
 
 
-LIMITATIONS/BEHAVIOR CHANGES COMPARED TO PACMAN 2.9
-===================================================
-
-Excepted missing features still needing to be implemented, one can
-notice the following limitations:
-
-- If pacman is out of date, the frontend displays a warning and recommends
-to give up the on-going transanction. The frontend does not allow to
-upgrade pacman itself on-the-fly, and thus it should be restarted with
-only "pacman" as a target.
 
-- ...
+API CHANGES BETWEEN 3.1 AND 3.2
+===============================
+
+[REMOVED]
+- alpm_db_whatprovides()
+- alpm_splitdep (no longer public)
+- trans->targets was removed, so alpm_trans_get_targets() as well
+- error codes:
+    PM_ERR_OPT_*, PM_ERR_PKG_INSTALLED, PM_ERR_DLT_CORRUPTED,
+    PM_ERR_LIBARCHIVE_ERROR
+- event: PM_TRANS_EVT_EXTRACT_DONE
+- PM_TRANS_TYPE_ADD pmtranstype_t (add transaction)
+- PM_TRANS_FLAG_DEPENDSONLY pmtransflag_t
+
+[CHANGED]
+- alpm_grp_get_pkgs returns with pmpkg_t list, not package-name list
+- Swap parameters on PM_TRANS_CONV_INSTALL_IGNOREPKG callback function
+- download callback API changed: alpm_cb_download, alpm_cb_totaldl split
+  (+ new alpm_option_get_totaldlcb(), alpm_option_set_totaldlcb() functions)
+- unsigned long->off_t changes where size is used
+- pmsyncpkg_t struct changes:
+  - pmsynctype_t and alpm_sync_get_type() were removed
+  - alpm_sync_get_data() was removed
+  - alpm_sync_get_removes() was added
+
+[ADDED]
+- alpm_delta_get_from_md5sum(), alpm_delta_get_to_md5sum()
+- alpm_miss_get_causingpkg() (new causingpkg field in pmdepmissing_t)
+- alpm_checkdbconflicts()
+- alpm_sync_newversion()
+- alpm_deptest()
+- error codes :
+    PM_ERR_DLT_INVALID, PM_ERR_LIBARCHIVE, PM_ERR_LIBDOWNLOAD and
+    PM_ERR_EXTERNAL_DOWNLOAD
+- flags:
+    PM_TRANS_FLAG_ALLEXPLICIT, PM_TRANS_FLAG_UNNEEDED and
+    PM_TRANS_FLAG_RECURSEALL