>From 56e544db44c4a98e567e1407f0519483adc4eac7 Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@cassou.me>
Date: Thu, 13 Jun 2019 21:54:21 +0200
Subject: [PATCH 13/13] * doc/misc/auth.texi (The Unix password store):
 Complete rewrite

---
 doc/misc/auth.texi | 71 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 61 insertions(+), 10 deletions(-)

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index a46e3d73fc..bbb66ecab5 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -445,19 +445,60 @@ The Unix password store
 
 @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 @@ The Unix password store
 @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
 
-- 
2.21.0