Subject: bug#36052: 26.2.50; [PATCH] Improve auth-source-pass

From: Eli Zaretskii <[email-masked]>
Date: Fri, 14 Jun 2019 10:47:42 +0300

> From: Damien Cassou <[email-masked]>
> Cc: Noam Postavsky <[email-masked]>, Magnus Henoch <[email-masked]>, Ted Zlatanov <[email-masked]>, Iku Iwasa <[email-masked]>, Keith Amidon <[email-masked]>, galaunay <[email-masked]>, Nicolas Petton <[email-masked]>, Eli Zaretskii <[email-masked]>
> Date: Thu, 13 Jun 2019 21:59:32 +0200
> 
> diff --git a/etc/NEWS b/etc/NEWS
> index 95d7e08074..f5781fb7e5 100644
> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -1512,6 +1512,21 @@ the new variable 'buffer-auto-revert-by-notification' to a non-nil
>  value.  Auto Revert mode can use this information to avoid polling the
>  buffer periodically when 'auto-revert-avoid-polling' is non-nil.
>  
> +** auth-source-pass
> +
> +*** New customizable variable 'auth-source-pass-filename'.
> +Allows setting the path to the password-store, defaults to
> +~/.password-store.
> +
> +*** New customizable variable 'auth-source-pass-port-separator'.
> +Specifies separator between host and port, defaults to colon ":".
> +
> +*** Minimize the number of decryptions during password lookup.
> +This makes the package usable with physical tokens requiring touching
> +a sensor for every decryption.
> +
> +*** 'auth-source-pass-get' is now autoloaded.

These are all described in the patch for the manual, right?  If so,
the entries should be marked with "+++", see the beginning of NEWS for
instructions about that.

> +@itemize
> +@item @code{"gnu.org.gpg"} : No username or port in the filename means that any username and port will match.
> +@item @code{"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 @code{"rms@@gnu.org.gpg"} : The username can also be expressed as a prefix, separated from the host with an at-sign (@code{@@}).
> +@item @code{"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 @code{"gnu.org:22/rms.gpg"}
> +@item @code{"rms@@gnu.org:22.gpg"}
> +@item @code{"a/b/gnu.org.gpg"} : Entries can be stored in arbitrary directories.
> +@item @code{"a/b/gnu.org/rms.gpg"}
> +@item @code{"a/b/rms@@gnu.org.gpg"}
> +@item @code{"a/b/gnu.org:22.gpg"}
> +@item @code{"a/b/gnu.org:22/rms.gpg"}
> +@item @code{"a/b/rms@@gnu.org:22.gpg"}
> +@end itemize

Please make the text describing each @item start on a new line.  Also,
it sounds like you want @table here, not @itemize.  And finally,
quoting in @code is sub-optimal; would @samp (and losing the quotes)
do the job?

> +@defvar auth-source-pass-filename
> +Set this variable to a string locating the password store on the
> +disk. Defaults to @code{"~/.password-store"}.

File names or their parts should have the @file markup, not @code.

Thanks.