* doc/misc/auth.texi (The Unix password store): Complete rewrite

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index a46e3d73fce676fe08473bb3d74fbbd846283eec..bbb66ecab5b108a7c23ee317c033b40ff6deaa74 100644 (file)
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -445,19 +445,60 @@ then fall back to @file{~/.authinfo.gpg}.
 
 @uref{http://www.passwordstore.org,,The standard unix password
 manager} (or just @code{pass}) stores your passwords in
-@code{gpg}-protected files following the Unix philosophy.
+@code{gpg}-protected files following the Unix philosophy.  The store
+location (any directory) must be specified in the
+@code{auth-source-pass-filename} variable which defaults to
+@file{~/.password-store}.
 
-Emacs integration of @code{pass} follows the first approach suggested
-by the pass project itself for data organization to find data. This
-means that the filename of the file containing the password for a user
-on a particular host must contain the host name.  The file itself must
-contain the password on the first line, as well as a @code{username}
-field containing the username on a subsequent line. A @code{port}
-field can be used to differentiate the authentication data for several
-services with the same username on the same host.
+Emacs integration of @code{pass} follows the approach suggested by the
+pass project itself for data organization to find data.  In
+particular, to store a password for the user @code{rms} on the host
+@code{gnu.org} and port @code{22}, you should use one of the following
+filenames.
+
+@table @file
+@item gnu.org.gpg
+No username or port in the filename means that any username and port
+will match.
+
+@item gnu.org/rms.gpg
+The username to match can be expressed as filename inside a directory
+whose name matches the host.  This is useful if the store has
+passwords for several users on the same host.
+
+@item rms@@gnu.org.gpg
+The username can also be expressed as a prefix, separated from the
+host with an at-sign (@code{@@}).
+
+@item gnu.org:22.gpg
+The port (aka. service) to match can only be expressed after the host and separated with a colon (@code{:}).  The separator can be changed through the @code{auth-source-pass-port-separator} variable.
+
+@item gnu.org:22/rms.gpg
+
+@item rms@@gnu.org:22.gpg
+
+@item a/b/gnu.org.gpg
+Entries can be stored in arbitrary directories.
+
+@item a/b/gnu.org/rms.gpg
+
+@item a/b/rms@@gnu.org.gpg
+
+@item a/b/gnu.org:22.gpg
+
+@item a/b/gnu.org:22/rms.gpg
+
+@item a/b/rms@@gnu.org:22.gpg
+@end table
+
+If several entries match, the one matching the most items (where an
+``item'' is one of username, port or host) is preferred.  For example,
+while searching for an entry matching the @code{rms} user on host
+@code{gnu.org} and port @code{22}, then the entry
+@file{gnu.org:22/rms.gpg} is preferred over @file{gnu.org.gpg}.
 
 Users of @code{pass} may also be interested in functionality provided
-by other Emacs packages dealing with pass:
+by other Emacs packages:
 
 @itemize
 @item
@@ -468,6 +509,16 @@ by other Emacs packages dealing with pass:
 @uref{https://github.com/jabranham/helm-pass,,helm-pass}: helm interface for pass.
 @end itemize
 
+@defvar auth-source-pass-filename
+Set this variable to a string locating the password store on the disk.
+Defaults to @file{~/.password-store}.
+@end defvar
+
+@defvar auth-source-pass-port-separator
+Set this variable to a string that should separate an host name from a
+port in an entry.  Defaults to @samp{:}.
+@end defvar
+
 @node Help for developers
 @chapter Help for developers