# HG changeset patch # User Katsumi Yamaoka # Date 1252490839 0 # Node ID 2c607b344f3becb462d57480a1f67bb2227fa985 # Parent 2e22af528b767ee318717b40f549f91f028ca003 2009-09-02 Teodor Zlatanov * auth.texi (Help for users): Corrected markup. diff -r 2e22af528b76 -r 2c607b344f3b doc/misc/ChangeLog --- a/doc/misc/ChangeLog Wed Sep 09 09:29:29 2009 +0000 +++ b/doc/misc/ChangeLog Wed Sep 09 10:07:19 2009 +0000 @@ -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 -r 2e22af528b76 -r 2c607b344f3b doc/misc/auth.texi --- a/doc/misc/auth.texi Wed Sep 09 09:29:29 2009 +0000 +++ b/doc/misc/auth.texi Wed Sep 09 10:07:19 2009 +0000 @@ -67,16 +67,9 @@ @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 @@ ``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. + +The login and password are simply your login credentials to the server. -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. +``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 customize the variable @var{auth-sources}. The following may +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 @@ @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 @@ 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 @@ @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 @@ @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.