[Emacs-diffs] /srv/bzr/emacs/trunk r107758: Several miscellaneous doc changes.

[Chong Yidong]

------------------------------------------------------------
revno: 107758
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-04-04 15:54:02 +0800
message:
  Several miscellaneous doc changes.
  
  * doc/lispref/display.texi (Delayed Warnings): New node.
  
  * doc/misc/gnus-faq.texi (FAQ 8-2): Mention EasyPG.
  
  * doc/misc/gnus.texi: Reduce references to obsolete pgg library.
  (Security): Note that epg is now the default.
  
  * doc/misc/message.texi (Using PGP/MIME): Note that epg is now the default.
  
  * doc/misc/nxml-mode.texi (Completion): C-RET is no longer bound to
  nxml-complete.
  
  * lisp/subr.el (delayed-warnings-hook): Doc fix.
  
  * src/keyboard.c (Vdelayed_warnings_list): Doc fix.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  doc/lispref/elisp.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  doc/misc/ChangeLog
  doc/misc/gnus-faq.texi
  doc/misc/gnus.texi
  doc/misc/message.texi
  doc/misc/nxml-mode.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/subr.el
  src/ChangeLog
  src/keyboard.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-04 07:38:30 +0000
+++ b/doc/lispref/ChangeLog     2012-04-04 07:54:02 +0000
@@ -1,3 +1,7 @@
+2012-04-04  Chong Yidong  <address@hidden>
+
+       * display.texi (Delayed Warnings): New node.
+
 2012-04-04  Glenn Morris  <address@hidden>
 
        * os.texi (Notifications): Copyedits.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-03-30 16:31:24 +0000
+++ b/doc/lispref/display.texi  2012-04-04 07:54:02 +0000
@@ -572,6 +572,7 @@
 * Warning Basics::      Warnings concepts and functions to report them.
 * Warning Variables::   Variables programs bind to customize their warnings.
 * Warning Options::     Variables users set to control display of warnings.
+* Delayed Warnings::    Deferring a warning until the end of a command.
 @end menu
 
 @node Warning Basics
@@ -750,6 +751,53 @@
 that warning is not logged.
 @end defopt
 
address@hidden Delayed Warnings
address@hidden Delayed Warnings
+
+Sometimes, you may wish to avoid showing a warning while a command is
+running, and only show it only after the end of the command.  You can
+use the variable @code{delayed-warnings-list} for this.
+
address@hidden delayed-warnings-list
+The value of this variable is a list of warnings to be displayed after
+the current command has finished.  Each element must be a list
+
address@hidden
+(@var{type} @var{message} address@hidden address@hidden)
address@hidden smallexample
+
address@hidden
+with the same form, and the same meanings, as the argument list of
address@hidden (@pxref{Warning Basics}).  Immediately after
+running @code{post-command-hook} (@pxref{Command Overview}), the Emacs
+command loop displays all the warnings specified by this variable,
+then resets it to @code{nil}.
address@hidden defvar
+
+  Programs which need to further customize the delayed warnings
+mechanism can change the variable @code{delayed-warnings-hook}:
+
address@hidden delayed-warnings-hook
+This is a normal hook which is run by the Emacs command loop, after
address@hidden, in order to to process and display delayed
+warnings.
+
+Its default value is a list of two functions:
+
address@hidden
+(collapse-delayed-warnings display-delayed-warnings)
address@hidden smallexample
+
address@hidden collapse-delayed-warnings
address@hidden display-delayed-warnings
address@hidden
+The function @code{collapse-delayed-warnings} iterates through
address@hidden, removing repeated entries.  The function
address@hidden calls @code{display-warning} on each
+of the entries in @code{delayed-warnings-list}, in turn, and then sets
address@hidden to @code{nil}.
address@hidden defvar
+
 @node Invisible Text
 @section Invisible Text
 

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-04-03 08:10:17 +0000
+++ b/doc/lispref/elisp.texi    2012-04-04 07:54:02 +0000
@@ -1284,6 +1284,7 @@
 * Warning Variables::       Variables programs bind to customize
                               their warnings.
 * Warning Options::         Variables users set to control display of warnings.
+* Delayed Warnings::        Deferring a warning until the end of a command.
 
 Overlays
 

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-04-03 08:10:17 +0000
+++ b/doc/lispref/vol1.texi     2012-04-04 07:54:02 +0000
@@ -1306,6 +1306,7 @@
 * Warning Variables::       Variables programs bind to customize
                               their warnings.
 * Warning Options::         Variables users set to control display of warnings.
+* Delayed Warnings::        Deferring warning display until the end of a 
command.
 
 Overlays
 

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-04-03 08:10:17 +0000
+++ b/doc/lispref/vol2.texi     2012-04-04 07:54:02 +0000
@@ -1305,6 +1305,7 @@
 * Warning Variables::       Variables programs bind to customize
                               their warnings.
 * Warning Options::         Variables users set to control display of warnings.
+* Delayed Warnings::        Deferring a warning until the end of a command.
 
 Overlays
 

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-04-01 09:49:25 +0000
+++ b/doc/misc/ChangeLog        2012-04-04 07:54:02 +0000
@@ -1,3 +1,15 @@
+2012-04-04  Chong Yidong  <address@hidden>
+
+       * message.texi (Using PGP/MIME): Note that epg is now the default.
+
+       * gnus.texi: Reduce references to obsolete pgg library.
+       (Security): Note that epg is now the default.
+
+       * gnus-faq.texi (FAQ 8-2): Mention EasyPG.
+
+       * nxml-mode.texi (Completion): C-RET is no longer bound to
+       nxml-complete.
+
 2012-04-01  Jambunathan K  <address@hidden>
 
        * org.texi (Customizing tables in ODT export): Correct few errors.

=== modified file 'doc/misc/gnus-faq.texi'
--- a/doc/misc/gnus-faq.texi    2012-02-28 08:17:21 +0000
+++ b/doc/misc/gnus-faq.texi    2012-04-04 07:54:02 +0000
@@ -2109,12 +2109,11 @@
 
 @subsubheading Answer
 
-There's not only the Gnus manual but also the manuals
-for message, emacs-mime, sieve and pgg. Those packages
-are distributed with Gnus and used by Gnus but aren't
-really part of core Gnus, so they are documented in
-different info files, you should have a look in those
-manuals, too.
+There's not only the Gnus manual but also the manuals for message,
+emacs-mime, sieve, EasyPG Assistant, and pgg. Those packages are
+distributed with Gnus and used by Gnus but aren't really part of core
+Gnus, so they are documented in different info files, you should have
+a look in those manuals, too.
 
 @node FAQ 8-3
 @subsubheading Question 8.3

=== modified file 'doc/misc/gnus.texi'
--- a/doc/misc/gnus.texi        2012-03-23 11:22:21 +0000
+++ b/doc/misc/gnus.texi        2012-04-04 07:54:02 +0000
@@ -399,7 +399,7 @@
 @item Message manual: Composing messages
 @item Emacs-MIME:     Composing messages; @acronym{MIME}-specific parts.
 @item Sieve:          Managing Sieve scripts in Emacs.
address@hidden PGG:            @acronym{PGP/MIME} with Gnus.
address@hidden EasyPG:         @acronym{PGP/MIME} with Gnus.
 @item SASL:           @acronym{SASL} authentication in Emacs.
 @end itemize
 
@@ -426,7 +426,7 @@
 * Message:(message).         Composing messages.
 * Emacs-MIME:(emacs-mime).   Composing messages; @acronym{MIME}-specific parts.
 * Sieve:(sieve).             Managing Sieve scripts in Emacs.
-* PGG:(pgg).                 @acronym{PGP/MIME} with Gnus.
+* EasyPG:(epa).              @acronym{PGP/MIME} with Gnus.
 * SASL:(sasl).               @acronym{SASL} authentication in Emacs.
 
 @detailmenu
@@ -22146,8 +22146,8 @@
 @include emacs-mime.texi
 @chapter Sieve
 @include sieve.texi
address@hidden PGG
address@hidden pgg.texi
address@hidden EasyPG
address@hidden epa.texi
 @chapter SASL
 @include sasl.texi
 @end iflatex

=== modified file 'doc/misc/message.texi'
--- a/doc/misc/message.texi     2012-01-19 07:21:25 +0000
+++ b/doc/misc/message.texi     2012-04-04 07:54:02 +0000
@@ -1101,10 +1101,11 @@
 
 @acronym{PGP/MIME} requires an external OpenPGP implementation, such
 as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
-implementations such as PGP 2.x and PGP 5.x are also supported. One
-Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG,
-pgg, PGG Manual}), is included, but Mailcrypt is also supported.
address@hidden Compatibility}.
+implementations such as PGP 2.x and PGP 5.x are also supported.  The
+default Emacs interface to the PGP implementation is EasyPG
+(@pxref{Top,,EasyPG Assistant User's Manual, epa, EasyPG Assistant
+User's Manual}), but PGG (@pxref{Top, ,PGG, pgg, PGG Manual}) and
+Mailcrypt are also supported.  @xref{PGP Compatibility}.
 
 @cindex gpg-agent
 Message internally calls GnuPG (the @command{gpg} command) to perform
@@ -1139,11 +1140,6 @@
 gpg --use-agent --sign < /dev/null > /dev/null
 @end example
 
-The Lisp variable @code{pgg-gpg-use-agent} controls whether to use
address@hidden  See also @xref{Caching passphrase, , , pgg, The
-PGG Manual}.
-
-
 @node PGP Compatibility
 @subsection Compatibility with older implementations
 
@@ -1158,7 +1154,7 @@
 If you have imported your old PGP 2.x key into GnuPG, and want to send
 signed and encrypted messages to your fellow PGP 2.x users, you'll
 discover that the receiver cannot understand what you send. One
-solution is to use PGP 2.x instead (i.e., if you use @code{pgg}, set
+solution is to use PGP 2.x instead (e.g.@: if you use @code{pgg}, set
 @code{pgg-default-scheme} to @code{pgp}). You could also convince your
 fellow PGP 2.x users to convert to GnuPG.
 @vindex mml-signencrypt-style-alist

=== modified file 'doc/misc/nxml-mode.texi'
--- a/doc/misc/nxml-mode.texi   2012-02-28 08:17:21 +0000
+++ b/doc/misc/nxml-mode.texi   2012-04-04 07:54:02 +0000
@@ -5,7 +5,7 @@
 @c %**end of header
 
 @copying
-This manual documents nxml-mode, an Emacs major mode for editing
+This manual documents nXML mode, an Emacs major mode for editing
 XML with RELAX NG support.
 
 Copyright @copyright{} 2007-2012 Free Software Foundation, Inc.
@@ -108,31 +108,25 @@
 @node Completion
 @chapter Completion
 
-Apart from real-time validation, the most important feature that
-nxml-mode provides for assisting in document creation is "completion".
+Apart from real-time validation, the most important feature that nXML
+mode provides for assisting in document creation is "completion".
 Completion assists the user in inserting characters at point, based on
 knowledge of the schema and on the contents of the buffer before
 point.
 
-The traditional GNU Emacs key combination for completion in a
-buffer is @address@hidden However, many window systems
-and window managers use this key combination themselves (typically for
-switching between windows) and do not pass it to applications. It's
-hard to find key combinations in GNU Emacs that are both easy to type
-and not taken by something else.  @address@hidden (i.e.
-pressing the Enter or Return key, while the Ctrl key is held down) is
-available.  It won't be available on a traditional terminal (because
-it is indistinguishable from Return), but it will work with a window
-system.  Therefore we adopt the following solution by default: use
address@hidden@key{RET}} when there's a window system and
address@hidden@key{TAB}} when there's not.  In the following, I
-will assume that a window system is being used and will therefore
-refer to @address@hidden
+nXML mode adapts the standard GNU Emacs command for completion in a
+buffer: @code{completion-at-point}, which is bound to @kbd{C-M-i} and
address@hidden@key{TAB}}.  Note that many window systems and window managers
+use @address@hidden themselves (typically for switching between
+windows) and do not pass it to applications.  In that case, you should
+type @kbd{C-M-i} or @address@hidden @key{TAB}} for completion, or bind
address@hidden to a key that is convenient for you.  In
+the following, I will assume that you type @kbd{C-M-i}.
 
-Completion works by examining the symbol preceding point.  This
-is the symbol to be completed. The symbol to be completed may be the
-empty. Completion considers what symbols starting with the symbol to
-be completed would be valid replacements for the symbol to be
+nXML mode completion works by examining the symbol preceding point.
+This is the symbol to be completed. The symbol to be completed may be
+the empty. Completion considers what symbols starting with the symbol
+to be completed would be valid replacements for the symbol to be
 completed, given the schema and the contents of the buffer before
 point.  These symbols are the possible completions.  An example may
 make this clearer.  Suppose the buffer looks like this (where @point{}
@@ -168,7 +162,7 @@
 In this case, the symbol to be completed is empty, and the possible
 completions are just @samp{http://www.w3.org/1999/xhtml}.
 
-When you type @address@hidden, what happens depends
+When you type @kbd{C-M-i}, what happens depends
 on what the set of possible completions are.
 
 @itemize @bullet
@@ -186,7 +180,7 @@
 @end example
 
 @noindent
address@hidden@key{RET}} will yield
address@hidden will yield
 
 @example
 <html xmlns="http://www.w3.org/1999/xhtml";>
@@ -202,18 +196,17 @@
 @end example
 
 @noindent
-The symbol to be completed is @samp{x}. The possible completions
-are @samp{xmlns} and @samp{xml:lang}.  These share a
-common prefix of @samp{xml}.  Thus, @address@hidden
-will yield:
+The symbol to be completed is @samp{x}. The possible completions are
address@hidden and @samp{xml:lang}.  These share a common prefix of
address@hidden  Thus, @kbd{C-M-i} will yield:
 
 @example
 <html address@hidden
 @end example
 
 @noindent
-Typically, you would do @address@hidden again, which would
-have the result described in the next item.
+Typically, you would do @kbd{C-M-i} again, which would have the result
+described in the next item.
 @item
 If there is more than one possible completion, but the
 possible completions do not share a non-empty prefix, then Emacs will
@@ -251,19 +244,19 @@
 @end example
 
 @noindent
-(If you do @address@hidden again, the namespace URI will
-be inserted. Should that happen automatically?)
+(If you do @kbd{C-M-i} again, the namespace URI will be
+inserted. Should that happen automatically?)
 @end itemize
 
 @node Inserting end-tags
 @chapter Inserting end-tags
 
-The main redundancy in XML syntax is end-tags.  nxml-mode provides
+The main redundancy in XML syntax is end-tags.  nXML mode provides
 several ways to make it easier to enter end-tags.  You can use all of
 these without a schema.
 
-You can use @address@hidden after @samp{</}
-to complete the rest of the end-tag.
+You can use @kbd{C-M-i} after @samp{</} to complete the rest of the
+end-tag.
 
 @kbd{C-c C-f} inserts an end-tag for the element containing
 point. This command is useful when you want to input the start-tag,
@@ -279,9 +272,9 @@
 indented. The @samp{i} is mnemonic for inline and the
 @samp{b} is mnemonic for block.
 
-Finally, you can customize nxml-mode so that @kbd{/}
-automatically inserts the rest of the end-tag when it occurs after
address@hidden<}, by doing
+Finally, you can customize nXML mode so that @kbd{/} automatically
+inserts the rest of the end-tag when it occurs after @samp{<}, by
+doing
 
 @display
 @kbd{M-x customize-variable @key{RET} nxml-slash-auto-complete-flag @key{RET}}
@@ -868,7 +861,7 @@
 @node DTDs
 @chapter DTDs
 
-nxml-mode is designed to support the creation of standalone XML
+nXML mode is designed to support the creation of standalone XML
 documents that do not depend on a DTD.  Although it is common practice
 to insert a DOCTYPE declaration referencing an external DTD, this has
 undesirable side-effects.  It means that the document is no longer

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-04-04 07:29:06 +0000
+++ b/etc/NEWS  2012-04-04 07:54:02 +0000
@@ -740,6 +740,7 @@
 ---
 ** mpc.el: Can use pseudo tags of the form tag1|tag2 as a union of two tags.
 
++++
 ** nXML mode no longer binds C-RET to `nxml-complete'.
 Completion is now performed via `completion-at-point', bound to M-TAB.
 If `nxml-bind-meta-tab-to-complete-flag' is non-nil (the default),
@@ -940,6 +941,7 @@
 ---
 *** pc-mode.el is obsolete (CUA mode is much more comprehensive).
 
++++
 *** pgg is obsolete (use EasyPG instead)
 
 ---
@@ -1562,7 +1564,7 @@
 ** New variable `revert-buffer-in-progress-p' is true while a buffer is
 being reverted, even if the buffer has a local `revert-buffer-function'.
 
----
++++
 ** New variables `delayed-warnings-list' and `delayed-warnings-hook'.
 If delayed-warnings-list is non-nil, the command loop calls
 `delayed-warnings-hook' after `post-command-hook'.  At present, this

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-04-04 01:38:37 +0000
+++ b/lisp/ChangeLog    2012-04-04 07:54:02 +0000
@@ -1,3 +1,7 @@
+2012-04-04  Chong Yidong  <address@hidden>
+
+       * subr.el (delayed-warnings-hook): Doc fix.
+
 2012-04-04  Daiki Ueno  <address@hidden>
 
        * epa.el (epa--select-keys): Bind C-c C-c to finish the key

=== modified file 'lisp/subr.el'
--- a/lisp/subr.el      2012-03-16 01:27:23 +0000
+++ b/lisp/subr.el      2012-04-04 07:54:02 +0000
@@ -1893,9 +1893,10 @@
 ;; Ref http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00085.html
 (defvar delayed-warnings-hook '(collapse-delayed-warnings
                                 display-delayed-warnings)
-  "Normal hook run to process delayed warnings.
-Functions in this hook should access the `delayed-warnings-list'
-variable (which see) and remove from it the warnings they process.")
+  "Normal hook run to process and display delayed warnings.
+By default, this hook contains functions to consolidate the
+warnings listed in `delayed-warnings-list', display them, and set
+`delayed-warnings-list' back to nil.")
 
 
 ;;;; Process stuff.

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-04-01 16:55:30 +0000
+++ b/src/ChangeLog     2012-04-04 07:54:02 +0000
@@ -1,3 +1,7 @@
+2012-04-04  Chong Yidong  <address@hidden>
+
+       * keyboard.c (Vdelayed_warnings_list): Doc fix.
+
 2012-04-01  Eli Zaretskii  <address@hidden>
 
        * w32menu.c (simple_dialog_show, add_menu_item): Use SAFE_ALLOCA

=== modified file 'src/keyboard.c'
--- a/src/keyboard.c    2012-03-28 15:54:54 +0000
+++ b/src/keyboard.c    2012-04-04 07:54:02 +0000
@@ -12168,7 +12168,7 @@
   Vdeferred_action_function = Qnil;
 
   DEFVAR_LISP ("delayed-warnings-list", Vdelayed_warnings_list,
-               doc: /* List of warnings to be displayed as soon as possible.
+               doc: /* List of warnings to be displayed after this command.
 Each element must be a list (TYPE MESSAGE [LEVEL [BUFFER-NAME]]),
 as per the args of `display-warning' (which see).
 If this variable is non-nil, `delayed-warnings-hook' will be run