bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[Neil Jackson]

The documentation is inconsistent about the order in which auth checks
'~/.authinfo' and '~/.authinfo.gpg' when 'auth-sources' isn't
customised.

In (info "(auth)Help for Users") it says that the unencrypted file is
sought first:

    If you don't customize 'auth-sources', you'll have to live with the
    defaults: the unencrypted netrc file '~/.authinfo' will be used for
    any host and any port.

    If that fails, any host and any port are looked up in the netrc file
    '~/.authinfo.gpg', which is a GnuPG encrypted file (*note GnuPG and
    EasyPG Assistant Configuration::).

But in (info "(auth)GnuPG and EasyPG Assistant Configuration") it says
it says that the encrypted file is sought first:

    If you don't customize 'auth-sources', the auth-source library reads
    '~/.authinfo.gpg', which is a GnuPG encrypted file.  Then it will
    check '~/.authinfo' but it's not recommended to use such an
    unencrypted file.


In GNU Emacs 24.3.1 (x86_64-redhat-linux-gnu, GTK+ Version 3.8.2)
 of 2013-08-14 on buildvm-15.phx2.fedoraproject.org Windowing system
distributor `Fedora Project', version 11.0.11404000 System Description:
Fedora release 19 (Schrödinger’s Cat)

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[Glenn Morris]

Version: 24.4

Thanks, the first one was right.

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[N. Jackson]

The following message is a courtesy copy of an article
that has been posted to gnu.emacs.bug as well.

Glenn Morris <rgm@gnu.org> writes:

> Version: 24.4
>
> Thanks, the first one was right.

Thanks.

(And I aplologise for the duplicate posting (bug#16643) -- I'm in
the midst of a struggle to get email working in Emacs and, thinking I
was misconfigured, I wasn't patient enough for the original report to
appear.)

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[Ted Zlatanov]

On Fri, 07 Feb 2014 21:08:21 -0500 Glenn Morris <rgm@gnu.org> wrote: 

GM> Version: 24.4
GM> Thanks, the first one was right.

I looked at your patch (finally, yeah).  The relevant piece is at the
end.

I am not sure that it's an improvement to remove the explanation, even
though it's certainly easier for the developers not to keep them in
sync.

Maybe instead of talking about order, the docstring should explain what
the .gpg extension means and how to enable it, and what happens to
missing files?

I am not making the change immediately in case this kind of detail is
not appropriate in the docstring.

Thanks
Ted

 (defcustom auth-sources '("~/.authinfo" "~/.authinfo.gpg" "~/.netrc")
   "List of authentication sources.
-
-The default will get login and password information from
-\"~/.authinfo.gpg\", which you should set up with the EPA/EPG
-packages to be encrypted.  If that file doesn't exist, it will
-try the unencrypted version \"~/.authinfo\" and the famous
-\"~/.netrc\" file.
-
-See the auth.info manual for details.
-
 Each entry is the authentication type with optional properties.
+Entries are tried in the order in which they appear.
+See Info node `(auth)Help for users' for details.

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[Ted Zlatanov]

On Sun, 09 Feb 2014 18:41:32 -0500 Ted Zlatanov <tzz@lifelogs.com> wrote: 

TZ> On Fri, 07 Feb 2014 21:08:21 -0500 Glenn Morris <rgm@gnu.org> wrote: 
GM> Version: 24.4
GM> Thanks, the first one was right.

TZ> I looked at your patch (finally, yeah).  The relevant piece is at the
TZ> end.

TZ> I am not sure that it's an improvement to remove the explanation, even
TZ> though it's certainly easier for the developers not to keep them in
TZ> sync.

TZ> Maybe instead of talking about order, the docstring should explain what
TZ> the .gpg extension means and how to enable it, and what happens to
TZ> missing files?

TZ> I am not making the change immediately in case this kind of detail is
TZ> not appropriate in the docstring.

Glenn... ping?  Is it OK to revise the docstring or do you want to keep
it lean?

Thanks
Ted

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[Glenn Morris]

Ted Zlatanov wrote:

> Glenn... ping?  Is it OK to revise the docstring or do you want to keep
> it lean?

It's your doc-string, so please feel free to make it say whatever you like.
(I don't see the point in doc-strings saying things like "the default
tries A, B, then C" is all, since it repeats information that is
available by other means, and is likely to get outdated.)

bug#16642: 24.3; (auth) Minor documentation inconsistency on checking order of un/encrypted .authinfo files

[Ted Zlatanov]

On Wed, 12 Feb 2014 11:44:45 -0500 Glenn Morris <rgm@gnu.org> wrote: 

GM> Ted Zlatanov wrote:
>> Glenn... ping?  Is it OK to revise the docstring or do you want to keep
>> it lean?

GM> (I don't see the point in doc-strings saying things like "the default
GM> tries A, B, then C" is all, since it repeats information that is
GM> available by other means, and is likely to get outdated.)

OK, I'll just mention the extension as I suggested.

Thanks
Ted