auth.texi (Secret Service API): Edit further and give examples.

2 files changed, 68 insertions, 46 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 525b03e929d..f6260ecc4ab 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,7 @@
+2012-04-05  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * auth.texi (Secret Service API): Edit further and give examples.
+
 2012-04-04  Glenn Morris  <rgm@gnu.org>
 
         * auth.texi (Secret Service API): Copyedits.
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 83975659405..bb413ad138b 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -229,13 +229,14 @@ necessary if you have an unusual (see earlier comment on those) setup.
 
 The @dfn{Secret Service API} is a standard from
 @uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
-to securely store passwords and other confidential information.
-Implementations of compliant daemons are the GNOME Keyring and the KDE
-Wallet.
+to securely store passwords and other confidential information.  This
+API is implemented by system daemons such as the GNOME Keyring and the
+KDE Wallet (these are GNOME and KDE packages respectively and should
+be available on most modern GNU/Linux systems).
 
-The auth-source library uses the @file{secrets.el} library as an
-interface to this feature.  You can also use that library in other
-packages.
+The auth-source library uses the @file{secrets.el} library to connect
+through the Secret Service API.  You can also use that library in
+other packages, it's not exclusive to auth-source.
 
 @defvar secrets-enabled
 After loading @file{secrets.el}, a non-@code{nil} value of this
@@ -244,63 +245,60 @@ Service API.
 @end defvar
 
 @deffn Command secrets-show-secrets
-This command inspects all collections, items, and their attributes.
+This command shows all collections, items, and their attributes.
 @end deffn
 
-The atomic objects to be managed by the Secret Service API are
-@dfn{secret items}, which are something an application wishes to store
-securely.  A good example is a password that an application needs to
-save and use at a later date.
+The atomic objects managed by the Secret Service API are @dfn{secret
+items}, which contain things an application wishes to store securely,
+like a password.  Secret items have a label (a name), the @dfn{secret}
+(which is the string we want, like a password), and a set of lookup
+attributes.  The attributes can be used to search and retrieve a
+secret item at a later date.
 
 Secret items are grouped in @dfn{collections}.  A collection is
-similar in concept to the terms @samp{keyring} or @samp{wallet}.  A
-common collection is called @samp{"login"}.  A collection is stored
-permanently under the user's permissions, and can be accessed in a
-user session context.
+sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring
+and KDE Wallet but it's the same thing, a group of secrets.
+Collections are personal and protected so only the owner can open them.
 
-A collection can have an alias name.  The use case for this is to
-set the alias @samp{"default"} for a given collection, making it
-transparent to clients as to which collection is used.  Other aliases
-are not supported (yet).  Since an alias is visible to all
-applications, this setting should be performed with care.
+The most common collection is called @samp{login}.
+
+A collection can have an alias.  The alias @samp{default} is
+commonly used so the clients don't have to know the specific name of
+the collection they open.  Other aliases are not supported yet.
+Since aliases are globally accessible, set the @samp{default} alias
+only when you're sure it's appropriate.
 
 @defun secrets-list-collections
-This function returns a list of collection names.
+This function returns all the collection names as a list.
 @end defun
 
 @defun secrets-set-alias collection alias
 Set @var{alias} as alias of collection labeled @var{collection}.
-For the time being, only the alias @samp{"default"} is supported.
+Currently only the alias @samp{default} is supported.
 @end defun
 
 @defun secrets-get-alias alias
 Return the collection name @var{alias} is referencing to.
-For the time being, only the alias @samp{"default"} is supported.
+Currently only the alias @samp{default} is supported.
 @end defun
 
 Collections can be created and deleted by the functions
 @code{secrets-create-collection} and @code{secrets-delete-collection}.
-Usually, this is not applied from within Emacs.  Common collections,
-like @samp{"login"}, should never be deleted.
-
-There exists a special collection called @samp{"session"}, which has
-the lifetime of the corresponding client session (aka Emacs's
-lifetime).  It is created automatically when Emacs uses the Secret
-Service interface, and it is deleted when Emacs is killed.  Therefore,
-it can be used to store and retrieve secret items temporarily.  This
-should be preferred over creation of a persistent collection, when the
-information should not live longer than Emacs.  The session collection
-can be addressed either by the string @samp{"session"}, or by
-@code{nil}, whenever a collection parameter is needed in the following
-functions.
-
-As already said, a collection is a group of secret items.  A secret
-item has a label, the @dfn{secret} (which is a string), and a set of
-lookup attributes.  The attributes can be used to search and retrieve
-a secret item at a later date.
+Usually, this is not done from within Emacs.  Do not delete standard
+collections such as @samp{login}.
+
+The special collection @samp{session} exists for the lifetime of the
+corresponding client session (in our case, Emacs's lifetime).  It is
+created automatically when Emacs uses the Secret Service interface and
+it is deleted when Emacs is killed.  Therefore, it can be used to
+store and retrieve secret items temporarily.  The @samp{session}
+collection is better than a persistent collection when the secret
+items should not live longer than Emacs.  The session collection can
+be specified either by the string @samp{session}, or by @code{nil},
+whenever a collection parameter is needed in the following functions.
 
 @defun secrets-list-items collection
-Returns a list of all item labels of @var{collection}.
+Returns all the item labels of @var{collection} as a list.
 @end defun
 
 @defun secrets-create-item collection item password &rest attributes
@@ -310,6 +308,8 @@ key-value pairs set for the created item.  The keys are keyword
 symbols, starting with a colon.  Example:
 
 @example
+;;; The session "session", the label is "my item"
+;;; and the secret (password) is "geheim"
 (secrets-create-item "session" "my item" "geheim"
  :method "sudo" :user "joe" :host "remote-host")
 @end example
@@ -327,7 +327,7 @@ This function deletes item @var{item} in @var{collection}.
 The lookup attributes, which are specified during creation of a
 secret item, must be a key-value pair.  Keys are keyword symbols,
 starting with a colon; values are strings.  They can be retrieved
-from a given secret item, and they can be used for searching of items.
+from a given secret item and they can be used for searching of items.
 
 @defun secrets-get-attribute collection item attribute
 Returns the value of key @var{attribute} of item labeled @var{item} in
@@ -347,9 +347,9 @@ attributes, it returns @code{nil}.  Example:
 @end defun
 
 @defun secrets-search-items collection &rest attributes
-Search items in @var{collection} with @var{attributes}.
-@var{attributes} are key-value pairs, as used in
-@code{secrets-create-item}.  Example:
+Search for the items in @var{collection} with matching
+@var{attributes}.  The @var{attributes} are key-value pairs, as used
+in @code{secrets-create-item}.  Example:
 
 @example
 (secrets-search-items "session" :user "joe")
@@ -357,6 +357,24 @@ Search items in @var{collection} with @var{attributes}.
 @end example
 @end defun
 
+The auth-source library uses the @file{secrets.el} library and thus
+the Secret Service API when you specify a source matching
+@samp{secrets:COLLECTION}.  For instance, you could use
+@samp{secrets:session} to use the @samp{session} collection, open only
+for the lifetime of Emacs.  Or you could use @samp{secrets:Login} to
+open the @samp{Login} collection.  As a special case, you can use the
+symbol @code{default} in @code{auth-sources} (not a string, but a
+symbol) to specify the @samp{default} alias.  Here is a contrived
+example that sets @code{auth-sources} to search three collections and
+then fall back to @file{~/.authinfo.gpg}.
+
+@example
+(setq auth-sources '(default
+                     "secrets:session"
+                     "secrets:Login"
+                     "~/.authinfo.gpg"))
+@end example
+
 @node Help for developers
 @chapter Help for developers