--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename auth.info
+
+@set VERSION 0.1
+
+@dircategory Emacs
+@direntry
+* auth-source: (auth). The Emacs auth-source library.
+@end direntry
+
+@settitle Emacs auth-source Library @value{VERSION}
+
+@copying
+This file describes the Emacs auth-source library.
+
+Copyright @copyright{} 2008, 2009
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@tex
+
+@titlepage
+@title Emacs auth-source Library
+
+@author by Ted Zlatanov
+@page
+
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@page
+
+@end tex
+
+@node Top
+@top Emacs auth-source
+This manual describes the Emacs auth-source library.
+
+It is a way for multiple applications to share a single configuration
+(in Emacs and in files) for user convenience.
+
+@menu
+* Overview:: Overview of the auth-source library.
+* Help for users::
+* Help for developers::
+* Index::
+* Function Index::
+* Variable Index::
+@end menu
+
+@node Overview
+@chapter Overview
+
+To be done.
+
+@node Help for users
+@chapter Help for users
+
+If you have problems with the port, turn up @code{gnus-verbose} and
+see what port the library is checking. Ditto for any other
+problems, your first step is to see what's being checked.
+
+Setup:
+
+@lisp
+(require 'auth-source)
+(customize-variable 'auth-sources) ;; optional, do it once
+@end lisp
+
+@defvar auth-sources
+
+The @var{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:
+
+@lisp
+(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
+@end lisp
+
+By adding multiple entries to that list with a particular host or
+protocol, you can have specific netrc files for that host or protocol.
+
+@end defvar
+
+
+``Netrc'' files are a de facto standard. They look like this:
+@example
+machine mymachine login myloginname password mypassword port myport
+@end example
+
+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.
+
+If you don't customize @var{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.
+
+@lisp
+(require 'epa-file)
+(epa-file-enable)
+(setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important
+@end lisp
+
+For url-auth authentication (HTTP/HTTPS), you need to put this in your
+netrc file:
+
+@example
+machine yourmachine.com:80 port http login testuser password testpass
+@end example
+
+This will match any realm and authentication method (basic or
+digest). If you want finer controls, explore the url-auth source
+code and variables.
+
+For Tramp authentication, use:
+
+@example
+machine yourmachine.com port scp login testuser password testpass
+@end example
+
+Note that the port denotes the Tramp connection method. When you
+don't use a port entry, you match any Tramp method, as explained
+earlier.
+
+@node Help for developers
+@chapter Help for developers
+
+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 @code{gnus-verbose} is 9 or
+higher, debugging messages will be printed.
+
+If @var{mode} is a list of strings, the function will return a list of
+strings or @code{nil} objects. If it's a string, the function will
+return a string or a @code{nil} object. Currently only the modes
+``login'' and ``password'' are recognized but more may be added in the
+future.
+
+@var{host} is a string containing the host name.
+
+@var{port} contains the protocol name (e.g. ``imap'') or
+a port number. It must be a string, corresponding to the port in the
+users' netrc files.
+
+@example
+;; IMAP example
+(setq auth (auth-source-user-or-password
+ '("login" "password")
+ "anyhostnamehere"
+ "imap"))
+(nth 0 auth) ; the login name
+(nth 1 auth) ; the password
+@end example
+
+@end defun
+
+@node Index
+@chapter Index
+@printindex cp
+
+@node Function Index
+@chapter Function Index
+@printindex fn
+
+@node Variable Index
+@chapter Variable Index
+@printindex vr
+
+@summarycontents
+@contents
+@bye
+
+@c End:
+
+@ignore
+ arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
+@end ignore