From 38dc51ba9b5372a8035445fa3a230115def726bd Mon Sep 17 00:00:00 2001 From: Katsumi Yamaoka Date: Wed, 9 Sep 2009 10:07:19 +0000 Subject: [PATCH] 2009-09-02 Teodor Zlatanov * auth.texi (Help for users): Corrected markup. --- doc/misc/ChangeLog | 4 ++++ doc/misc/auth.texi | 56 +++++++++++++++++++++++----------------------- 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index f70c8751e47..450788c5c1e 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -12,6 +12,10 @@ (Feedback): Document the new bug report command. (Structure editing): Added an index entry for the sorting of subtrees. +2009-09-02 Teodor Zlatanov + + * auth.texi (Help for users): Corrected markup. + 2009-09-02 Glenn Morris * emacs-mime.texi (time-date): Mention float-time. diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index 0cdb0df21d9..fc69d0241a9 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -67,16 +67,9 @@ It is a way for multiple applications to share a single configuration @node Overview @chapter Overview -The auth-source library is a modern, extensible, enterprise-class -authentication library. It uses the latest design patterns, has 1800 -unit tests, and has been featured in 21 industry conference keynote -talks. It's future-proof, mathematically proven to be bug-free, and -has 6 internal XML parsers just in case you ever need to eat up some -memory. - -Just kidding. The auth-source library is simply a way for Emacs and -Gnus, among others, to find the answer to the old burning question ``I -have a server name and a port, what are my user name and password?'' +The auth-source library is simply a way for Emacs and Gnus, among +others, to find the answer to the old burning question ``I have a +server name and a port, what are my user name and password?'' The auth-source library actually supports more than just the user name (known as the login) or the password, but only those two are in use @@ -90,25 +83,32 @@ see later in this document. ``Netrc'' files are a de facto standard. They look like this: @example -machine mymachine login myloginname password mypassword port myport +machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} @end example +The machine is the server (either a DNS name or an IP address). + The port is optional. If it's missing, auth-source will assume any port is OK. Actually the port is a protocol name or a port number so -you can have separate entries for port 143 and for protocol ``imap'' -if you fancy that. Anyway, you can just omit the port if you don't -need it. ``Netrc'' files are usually called @code{.authinfo} or -@code{.netrc}; nowadays @code{.authinfo} seems to be more popular and -the auth-source library encourages this confusion by making it the -default, as you'll see later. +you can have separate entries for port @var{143} and for protocol +@var{imap} if you fancy that. Anyway, you can just omit the port if +you don't need it. -If you have problems with the port, set @var{auth-source-debug} to t -and see what port the library is checking in the @code{*Messages*} -buffer. Ditto for any other problems, your first step is always to -see what's being checked. The second step, of course, is to write a -blog entry about it and wait for the answer in the comments. +The login and password are simply your login credentials to the server. -You can customize the variable @var{auth-sources}. The following may +``Netrc'' files are usually called @code{.authinfo} or @code{.netrc}; +nowadays @code{.authinfo} seems to be more popular and the auth-source +library encourages this confusion by making it the default, as you'll +see later. + +If you have problems with the port, set @code{auth-source-debug} to +@code{t} and see what port the library is checking in the +@code{*Messages*} buffer. Ditto for any other problems, your first +step is always to see what's being checked. The second step, of +course, is to write a blog entry about it and wait for the answer in +the comments. + +You can customize the variable @code{auth-sources}. The following may be needed if you are using an older version of Emacs or if the auth-source library is not loaded for some other reason. @@ -119,7 +119,7 @@ auth-source library is not loaded for some other reason. @defvar auth-sources -The @var{auth-sources} variable tells the auth-source library where +The @code{auth-sources} variable tells the auth-source library where your netrc files live for a particular host and protocol. While you can get fancy, the default and simplest configuration is: @@ -132,7 +132,7 @@ Sweet simplicity. In fact, this is already the default, so unless you want to move your netrc file, it will just work if you have that file. You may not, though, so make sure it exists. -By adding multiple entries to @var{auth-sources} with a particular +By adding multiple entries to @code{auth-sources} with a particular host or protocol, you can have specific netrc files for that host or protocol. Usually this is unnecessary but may make sense if you have shared netrc files or some other unusual setup (90% of Emacs users @@ -140,7 +140,7 @@ have unusual setups and the remaining 10% are @emph{really} unusual). @end defvar -If you don't customize @var{auth-sources}, you'll have to live with +If you don't customize @code{auth-sources}, you'll have to live with the defaults: any host and any port are looked up in the netrc file @code{~/.authinfo.gpg}. This is an encrypted file if and only if you set up EPA, which is strongly recommended. @@ -198,8 +198,8 @@ The auth-source library only has one function for external use. @defun auth-source-user-or-password mode host port Retrieve appropriate authentication tokens, determined by @var{mode}, -for host @var{host} and @var{port}. If @var{auth-source-debug} is t, -debugging messages will be printed. Set @var{auth-source-debug} to a +for host @var{host} and @var{port}. If @code{auth-source-debug} is t, +debugging messages will be printed. Set @code{auth-source-debug} to a function to use that function for logging. The parameters passed will be the same that the @code{message} function takes, that is, a string formatting spec and optional parameters.