Merge from gnus--devo--0

Revision: emacs@sv.gnu.org/emacs--devo--0--patch-1629

5 files changed, 137 insertions, 32 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 87efed613e5..dc39384e346 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,19 @@
+2009-08-29  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * auth.texi: Rewritten for coverage and clarity.
+
+2009-08-29  Katsumi Yamaoka  <yamaoka@jpl.org>
+
+        * gnus.texi (Expiring Mail): Mention
+        gnus-mark-copied-or-moved-articles-as-expirable.
+        (Various Various): Mention gnus-safe-html-newsgroups.
+
+        * gnus-news.texi: Mention
+        gnus-mark-copied-or-moved-articles-as-expirable.
+
+        * emacs-mime.texi (Display Customization): Add xref to
+        gnus-safe-html-newsgroups.
+
 2009-08-28  Michael Albinus  <michael.albinus@gmx.de>
 
         * tramp.texi (Version Control): Remove.
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index e4eaedbbc75..0cdb0df21d9 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -2,7 +2,7 @@
 @setfilename ../../info/auth
 @settitle Emacs auth-source Library @value{VERSION}
 
-@set VERSION 0.1
+@set VERSION 0.2
 
 @copying
 This file describes the Emacs auth-source library.
@@ -67,19 +67,53 @@ It is a way for multiple applications to share a single configuration
 @node Overview
 @chapter Overview
 
-To be done.
+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 actually supports more than just the user name
+(known as the login) or the password, but only those two are in use
+today in Emacs or Gnus.  Similarly, the auth-source library can in
+theory support multiple storage formats, but currently it only
+understands the classic ``netrc'' format, examples of which you can
+see later in this document.
 
 @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.
+``Netrc'' files are a de facto standard.  They look like this:
+@example
+machine mymachine login myloginname password mypassword port myport
+@end example
 
-Setup:
+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.
+
+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.
+
+You can customize the variable @var{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.
 
 @lisp
-(require 'auth-source)
+(require 'auth-source)             ;; probably not necessary
 (customize-variable 'auth-sources) ;; optional, do it once
 @end lisp
 
@@ -93,21 +127,18 @@ can get fancy, the default and simplest configuration is:
 (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
+This says ``for any host and any protocol, use just that one file.''
+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
+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
+have unusual setups and the remaining 10% are @emph{really} unusual).
 
-``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.
+@end defvar
 
 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
@@ -117,9 +148,26 @@ 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
+;;; VERY important if you want symmetric encryption
+;;; irrelevant if you don't
+(setq epa-file-cache-passphrase-for-symmetric-encryption t)
 @end lisp
 
+The simplest working netrc line example is one without a port.
+
+@example
+machine YOURMACHINE login YOU password YOURPASSWORD
+@end example
+
+This will match any authentication port.  Simple, right?  But what if
+there's a SMTP server on port 433 of that machine that needs a
+different password from the IMAP server?
+
+@example
+machine YOURMACHINE login YOU password SMTPPASSWORD port 433
+machine YOURMACHINE login YOU password GENERALPASSWORD
+@end example
+
 For url-auth authentication (HTTP/HTTPS), you need to put this in your
 netrc file:
 
@@ -127,9 +175,9 @@ netrc file:
 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.
+This will match any realm and authentication method (basic or digest)
+over HTTP.  HTTPS is set up similarly.  If you want finer controls,
+explore the url-auth source code and variables.
 
 For Tramp authentication, use:
 
@@ -139,7 +187,8 @@ machine yourmachine.com port scp login testuser password testpass
 
 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.
+earlier.  Since Tramp has about 88 connection methods, this may be
+necessary if you have an unusual (see earlier comment on those) setup.
 
 @node Help for developers
 @chapter Help for developers
@@ -149,14 +198,17 @@ 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.
+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
+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.
 
 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.
+strings or @code{nil} objects (thus you can avoid parsing the netrc
+file more than once).  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.
 
diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index e9a03595502..a49ccf62cd7 100644
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -418,7 +418,9 @@ or @kbd{I} instead.}
 A regular expression that matches safe URL names, i.e. URLs that are
 unlikely to leak personal information when rendering @acronym{HTML}
 email (the default value is @samp{\\`cid:}).  If @code{nil} consider
-all URLs safe.
+all URLs safe.  In Gnus, this will be overridden according to the value
+of the variable @code{gnus-safe-html-newsgroups}, @xref{Various
+Various, ,Various Various, gnus, Gnus Manual}.
 
 @item mm-inline-text-html-with-w3m-keymap
 @vindex mm-inline-text-html-with-w3m-keymap
diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi
index 09d7be56a7a..cf6d80862d2 100644
--- a/doc/misc/gnus-news.texi
+++ b/doc/misc/gnus-news.texi
@@ -311,6 +311,15 @@ intermediate host @samp{bar.example.com} from next time.
 @item The @file{all.SCORE} file can be edited from the group buffer
 using @kbd{W e}.
 
+@item You can set @code{gnus-mark-copied-or-moved-articles-as-expirable}
+to a non-@code{nil} value so that articles that have been read may be
+marked as expirable automatically when copying or moving them to a group
+that has auto-expire turned on.  The default is @code{nil} and copying
+and moving of articles behave as before; i.e., the expirable marks will
+be unchanged except that the marks will be removed when copying or
+moving articles to a group that has not turned auto-expire on.
+@xref{Expiring Mail}.
+
 @end itemize
 
 @end itemize
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index a7eb08101a2..91ce3228231 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -16299,6 +16299,23 @@ If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking
 commands will not mark an article as expirable, even if the group has
 auto-expire turned on.
 
+@vindex gnus-mark-copied-or-moved-articles-as-expirable
+The expirable marks of articles will be removed when copying or moving
+them to a group in which auto-expire is not turned on.  This is for
+preventing articles from being expired unintentionally.  On the other
+hand, to a group that has turned auto-expire on, the expirable marks of
+articles that are copied or moved will not be changed by default.  I.e.,
+when copying or moving to such a group, articles that were expirable
+will be left expirable and ones that were not expirable will not be
+marked as expirable.  So, even though in auto-expire groups, some
+articles will never get expired (unless you read them again).  If you
+don't side with that behavior that unexpirable articles may be mixed
+into auto-expire groups, you can set
+@code{gnus-mark-copied-or-moved-articles-as-expirable} to a
+non-@code{nil} value.  In that case, articles that have been read will
+be marked as expirable automatically when being copied or moved to a
+group that has auto-expire turned on.  The default value is @code{nil}.
+
 
 @node Washing Mail
 @subsection Washing Mail
@@ -26926,6 +26943,15 @@ group).
 
 @acronym{IMAP} users might want to allow @samp{/} in group names though.
 
+@item gnus-safe-html-newsgroups
+@vindex gnus-safe-html-newsgroups
+Groups in which links in html articles are considered all safe.  The
+value may be a regexp matching those groups, a list of group names, or
+@code{nil}.  This overrides @code{mm-w3m-safe-url-regexp}.  The default
+value is @code{"\\`nnrss[+:]"}.  This is effective only when emacs-w3m
+renders html articles, i.e., in the case @code{mm-text-html-renderer} is
+set to @code{w3m}.  @xref{Display Customization, ,Display Customization,
+emacs-mime, The Emacs MIME Manual}.
 
 @end table