auth-source-pass: Add documentation; fix tests and indentation.feature/auth-source-pass

* doc/misc/auth.texi: Document new integration with Pass. Use @itemize
  instead of @enumerate.
* lisp/auth-source-pass.el: Fix indentation.
  (auth-source-pass--remove-directory-name): Remove.
* test/lisp/auth-source-pass-tests.el: Adjust test macros.

1 files changed, 39 insertions, 7 deletions

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 29e55eda52c..94229e69f79 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -85,8 +85,9 @@ password (known as the secret).
 
 Similarly, the auth-source library supports multiple storage backend,
 currently either the classic ``netrc'' backend, examples of which you
-can see later in this document, or the Secret Service API@.  This is
-done with EIEIO-based backends and you can write your own if you want.
+can see later in this document, the Secret Service API, and pass, the
+standard unix password manager.  This is done with EIEIO-based
+backends and you can write your own if you want.
 
 @node Help for users
 @chapter Help for users
@@ -150,9 +151,9 @@ auth-source library is not loaded for some other reason.
 @defvar auth-sources
 
 The @code{auth-sources} variable tells the auth-source library where
-your netrc files or Secret Service API collection items live for a
-particular host and protocol.  While you can get fancy, the default
-and simplest configuration is:
+your netrc files, Secret Service API collection items, or your
+password store live for a particular host and protocol.  While you can
+get fancy, the default and simplest configuration is:
 
 @lisp
 ;;; old default: required :host and :port, not needed anymore
@@ -164,6 +165,9 @@ and simplest configuration is:
 ;;; use the Secrets API @var{Login} collection
 ;;; (@pxref{Secret Service API})
 (setq auth-sources '("secrets:Login"))
+;;; use pass (@file{~/.password-store})
+;;; (@pxref{Pass, the Unix password store})
+(setq auth-sources '(password-store))
 @end lisp
 
 By adding multiple entries to @code{auth-sources} with a particular
@@ -402,6 +406,34 @@ then fall back to @file{~/.authinfo.gpg}.
                      "~/.authinfo.gpg"))
 @end example
 
+@node Pass, the Unix password store
+@chapter Pass, 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.
+
+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.
+
+Users of @code{pass} may also be interested in functionality provided
+by other Emacs packages dealing with pass:
+
+@itemize
+@item
+@uref{https://git.zx2c4.com/password-store/tree/contrib/emacs/password-store.el,,password-store}: library wrapping @code{pass};
+@item
+@uref{https://github.com/NicolasPetton/pass,,pass}: major mode to manipulate the store and edit entries;
+@item
+@uref{https://github.com/jabranham/helm-pass,,helm-pass}: helm interface for pass.
+@end itemize
+
 @node Help for developers
 @chapter Help for developers
 
@@ -517,14 +549,14 @@ or EasyPG Assistant
 
 To quick start, here are some questions:
 
-@enumerate
+@itemize
 @item
 Do you use GnuPG version 2 instead of GnuPG version 1?
 @item
 Do you use symmetric encryption rather than public key encryption?
 @item
 Do you want to use gpg-agent?
-@end enumerate
+@end itemize
 
 Here are configurations depending on your answers: