Merge from origin/emacs-26

8fbe462 (origin/emacs-26) ; * doc/lispref/positions.texi (List Motion...
1d9efc0 Add index for "\( in strings" (Bug#25195)
304e96f Fix doc-string of 'fit-window-to-buffer' (Bug#36848)
d4c4987 Update view-mode docstring
d6ca1fc ; * lisp/term.el: Add missing / to esc seq commentary.
b3e2073 Fix subproc listening when setting filter to non-t (Bug#36591)
f671950 * etc/NEWS.25: Belatedly announce rcirc-reconnect-delay.
7f42277 Mention term.el's \032 dir tracking in commentary (Bug#19524)
16a529e Remove upload functionality of package-x from the elisp manual
78e6c2a * etc/AUTHORS: Update.
086a56e Clarify Gravatar docs
0592467 * doc/lispref/display.texi (Defining Faces): Say a face can't...

# Conflicts:
#	doc/emacs/programs.texi
#	etc/AUTHORS
#	lisp/term.el

6 files changed, 96 insertions, 92 deletions

diff --git a/lisp/emacs-lisp/package-x.el b/lisp/emacs-lisp/package-x.el
index a84c63d8711..e26b6b99c17 100644
--- a/lisp/emacs-lisp/package-x.el
+++ b/lisp/emacs-lisp/package-x.el
@@ -47,6 +47,8 @@
 
 (defcustom package-archive-upload-base "/path/to/archive"
   "The base location of the archive to which packages are uploaded.
+The commands in the package-x library will use this as base
+location.
 This should be an absolute directory name.  If the archive is on
 another machine, you may specify a remote name in the usual way,
 e.g. \"/ssh:foo@example.com:/var/www/packages/\".
@@ -273,7 +275,9 @@ if it exists."
 (defun package-upload-buffer ()
   "Upload the current buffer as a single-file Emacs Lisp package.
 If `package-archive-upload-base' does not specify a valid upload
-destination, prompt for one."
+destination, prompt for one.
+Signal an error if the current buffer is not visiting a simple
+package (a \".el\" file)."
   (interactive)
   (save-excursion
     (save-restriction
@@ -287,8 +291,13 @@ destination, prompt for one."
 Interactively, prompt for FILE.  The package is considered a
 single-file package if FILE ends in \".el\", and a multi-file
 package if FILE ends in \".tar\".
+Automatically extract package attributes and update the archive's
+contents list with this information.
 If `package-archive-upload-base' does not specify a valid upload
-destination, prompt for one."
+destination, prompt for one.  If the directory does not exist, it
+is created.  The directory need not have any initial contents
+\(i.e., you can use this command to populate an initially empty
+archive)."
   (interactive "fPackage file name: ")
   (with-temp-buffer
     (insert-file-contents file)
diff --git a/lisp/gnus/gnus-gravatar.el b/lisp/gnus/gnus-gravatar.el
index d271a52f908..19cbf529c65 100644
--- a/lisp/gnus/gnus-gravatar.el
+++ b/lisp/gnus/gnus-gravatar.el
@@ -46,7 +46,8 @@ If nil, default to `gravatar-size'."
   :group 'gnus-gravatar)
 
 (defcustom gnus-gravatar-too-ugly gnus-article-x-face-too-ugly
-  "Regexp matching posters whose avatar shouldn't be shown automatically."
+  "Regexp matching posters whose avatar shouldn't be shown automatically.
+If nil, show all avatars."
   :type '(choice regexp (const nil))
   :version "24.1"
   :group 'gnus-gravatar)
diff --git a/lisp/image/gravatar.el b/lisp/image/gravatar.el
index 91da840e3a4..9a1ec3b556b 100644
--- a/lisp/image/gravatar.el
+++ b/lisp/image/gravatar.el
@@ -40,18 +40,35 @@
 
 ;; FIXME a time value is not the nicest format for a custom variable.
 (defcustom gravatar-cache-ttl (days-to-time 30)
-  "Time to live for gravatar cache entries."
+  "Time to live for gravatar cache entries.
+If a requested gravatar has been cached for longer than this, it
+is retrieved anew."
   :type '(repeat integer)
   :group 'gravatar)
 
-;; FIXME Doc is tautological.  What are the options?
 (defcustom gravatar-rating "g"
-  "Default rating for gravatar."
+  "Most explicit Gravatar rating level to allow.
+Some gravatars are rated according to how suitable they are for
+different audiences.  The supported rating levels are, in order
+of increasing explicitness, the following:
+
+\"g\"  - Suitable for any audience.
+\"pg\" - May contain rude gestures, provocatively dressed
+       individuals, mild profanity, or mild violence.
+\"r\"  - May contain harsh profanity, intense violence, nudity,
+       or hard drug use.
+\"x\"  - May contain hardcore sexual imagery or extremely
+       disturbing violence.
+
+Each level covers itself as well as all less explicit levels.
+For example, setting this variable to \"pg\" will allow gravatars
+rated either \"g\" or \"pg\"."
   :type 'string
   :group 'gravatar)
 
 (defcustom gravatar-size 32
-  "Default size in pixels for gravatars."
+  "Gravatar size in pixels to request.
+Valid sizes range from 1 to 2048 inclusive."
   :type 'integer
   :group 'gravatar)
 
@@ -100,8 +117,10 @@ If no image available, return 'error."
 
 ;;;###autoload
 (defun gravatar-retrieve (mail-address cb &optional cbargs)
-  "Retrieve MAIL-ADDRESS gravatar and call CB on retrieval.
-You can provide a list of argument to pass to CB in CBARGS."
+  "Asynchronously retrieve a gravatar for MAIL-ADDRESS.
+When finished, call CB as (apply CB GRAVATAR CBARGS),
+where GRAVATAR is either an image descriptor, or the symbol
+`error' if the retrieval failed."
   (let ((url (gravatar-build-url mail-address)))
     (if (gravatar-cache-expired url)
 	(let ((args (list url
@@ -120,7 +139,9 @@ You can provide a list of argument to pass to CB in CBARGS."
 
 ;;;###autoload
 (defun gravatar-retrieve-synchronously (mail-address)
-  "Retrieve MAIL-ADDRESS gravatar and returns it."
+  "Synchronously retrieve a gravatar for MAIL-ADDRESS.
+Value is either an image descriptor, or the symbol `error' if the
+retrieval failed."
   (let ((url (gravatar-build-url mail-address)))
     (if (gravatar-cache-expired url)
         (with-current-buffer (url-retrieve-synchronously url)
diff --git a/lisp/term.el b/lisp/term.el
index b5f4c6225b5..77fbb1d0915 100644
--- a/lisp/term.el
+++ b/lisp/term.el
@@ -33,6 +33,21 @@
 
 ;;; Commentary:
 
+;; This file defines a general command-interpreter-in-a-buffer package
+;; (term mode).  The idea is that you can build specific process-in-a-buffer
+;; modes on top of term mode -- e.g., lisp, shell, scheme, T, soar, ....
+;; This way, all these specific packages share a common base functionality,
+;; and a common set of bindings, which makes them easier to use (and
+;; saves code, implementation time, etc., etc.).
+
+;; If, instead of `term', you call `ansi-term', you get multiple term
+;; buffers, after every new call ansi-term opens a new
+;; "*ansi-term*<xx>" window, where <xx> is, as usual, a number...
+
+;; For hints on converting existing process modes (e.g., tex-mode,
+;; background, dbx, gdb, kermit, prolog, telnet) to use term-mode
+;; instead of shell-mode, see the notes at the end of this file.
+
 ;; Speed considerations and a few caveats
 ;; --------------------------------------
 ;;
@@ -85,13 +100,6 @@
 ;; # By default nobody can't do anything
 ;; deny	root		*
 ;;
-;;
-;;             ----------------------------------------
-;;
-;;  If, instead of 'term', you call 'ansi-term', you get multiple term
-;; buffers, after every new call ansi-term opens a new *ansi-term*<xx> window,
-;; where <xx> is, as usual, a number...
-;;
 ;;             ----------------------------------------
 ;;
 ;;  With the term-buffer-maximum-size you can finally decide how many
@@ -111,38 +119,6 @@
 ;;  - Add hooks to allow raw-mode keys to be configurable
 ;;  - Which keys are better ? \eOA or \e[A ?
 ;;
-;;
-;;  Changes:
-;;
-;; V4.0 January 1997
-;;
-;;   - Huge reworking of the faces code: now we only have roughly 20-30
-;;     faces for everything so we're even faster than the old md-term.el !
-;;   - Finished removing all the J-Shell code.
-;;
-;;  V3.0 January 1997
-;;
-;;  - Now all the supportable ANSI commands work well.
-;;  - Reworked a little the code: much less jsh-inspired stuff
-;;
-;;  V2.3 November
-;;
-;;  - Now all the faces are accessed through an array: much cleaner code.
-;;
-;;  V2.2 November 4 1996
-;;
-;;  - Implemented ANSI output colorization ( a bit rough but enough for
-;;    color_ls )
-;;
-;;  - Implemented a maximum limit for the scroll buffer (stolen from
-;;    comint.el)
-;;
-;;  v2.1 October 28 1996, first public release
-;;
-;;  - Some new keybindings for term-char mode ( notably home/end/...)
-;;  - Directory, hostname and username tracking via ange-ftp
-;;  - Multi-term capability via the ansi-term call
-;;
 ;;  ----------------------------------------------------------------
 ;;  You should/could have something like this in your .emacs to take
 ;;  full advantage of this package
@@ -156,7 +132,6 @@
 ;;  	             (auto-fill-mode -1)
 ;;  	             (setq tab-width 8 ))))
 ;;
-;;
 ;;             ----------------------------------------
 ;;
 ;;  If you want to use color ls the best setup is to have a different file
@@ -167,7 +142,6 @@
 ;;
 ;;             ----------------------------------------
 ;;
-;;
 ;;  # Configuration file for the color ls utility
 ;;  # This file goes in the /etc directory, and must be world readable.
 ;;  # You can copy this file to .dir_colors in your $HOME directory to
@@ -224,17 +198,23 @@
 ;;  .xbm 01;35
 ;;  .xpm 01;35
 ;;
-;;
 ;;             ----------------------------------------
 ;;
-;;  Notice: for directory/host/user tracking you need to have something
-;; like this in your shell startup script (this is for a POSIXish shell
-;; like Bash but should be quite easy to port to other shells).
+;; There are actually two methods for directory tracking, one
+;; implemented in `term-command-hook' which sets the directory
+;; according to an escape sequence of the form "\032/<directory>\n".
+;; Some shells like bash will already send this escape sequence when
+;; they detect they are running in Emacs.  This can be configured or
+;; disabled on the Emacs side by setting `term-command-hook' to
+;; a different function.
 ;;
-;; For troubleshooting in Bash, you can check the definition of the
-;; custom functions with the "type" command.  e.g. "type cd".  If you
-;; do not see the expected definition from the config below, then the
-;; directory tracking will not work.
+;; The second method is in `term-handle-ansi-terminal-messages' which
+;; sets user, host, and directory according to escape sequences of the
+;; form "\033AnSiTc <directory>\n" (replace the "c" with "u" and "h"
+;; for user and host, respectively).  If the user and host don't
+;; match, it will set directory to a remote one, so it is important to
+;; set user and host correctly first.  See the example bash
+;; configuration below.
 ;;
 ;;             ----------------------------------------
 ;;
@@ -258,31 +238,24 @@
 ;;
 ;;		# The \033 stands for ESC.
 ;;		# There is a space between "AnSiT?" and $whatever.
+;;		printf '\033AnSiTh %s\n' "$HOSTNAME"
+;;		printf '\033AnSiTu %s\n' "$USER"
+;;		printf '\033AnSiTc %s\n' "$PWD"
 ;;
 ;;		cd()    { command cd    "$@"; printf '\033AnSiTc %s\n' "$PWD"; }
 ;;		pushd() { command pushd "$@"; printf '\033AnSiTc %s\n' "$PWD"; }
 ;;		popd()  { command popd  "$@"; printf '\033AnSiTc %s\n' "$PWD"; }
 ;;
-;;		printf '\033AnSiTc %s\n' "$PWD"
-;;		printf '\033AnSiTh %s\n' "$HOSTNAME"
-;;		printf '\033AnSiTu %s\n' "$USER"
-;;
 ;;		# Use custom dircolors in term buffers.
 ;;		# eval $(dircolors $HOME/.emacs_dircolors)
 ;;	esac
 ;;
 ;;	# ...
 ;;
-;;
-
-;;; Original Commentary:
-;; ---------------------
-
-;; The changelog is at the end of this file.
-
-;; Please send me bug reports, bug fixes, and extensions, so that I can
-;; merge them into the master source.
-;;     - Per Bothner (bothner@cygnus.com)
+;; For troubleshooting in Bash, you can check the definition of the
+;; custom functions with the "type" command.  e.g. "type cd".  If you
+;; do not see the expected definition from the config below, then the
+;; directory tracking will not work.
 
 
 ;; Brief Command Documentation:
@@ -290,21 +263,21 @@
 ;; Term Mode Commands: (common to all derived modes, like cmushell & cmulisp
 ;; mode)
 ;;
-;; m-p	    term-previous-input    	  Cycle backwards in input history
-;; m-n	    term-next-input  	    	  Cycle forwards
-;; m-r     term-previous-matching-input  Previous input matching a regexp
-;; m-s     comint-next-matching-input      Next input that matches
+;; M-p     term-previous-input           Cycle backwards in input history
+;; M-n     term-next-input               Cycle forwards
+;; M-r     term-previous-matching-input  Previous input matching a regexp
+;; M-s     comint-next-matching-input    Next input that matches
 ;; return  term-send-input
-;; c-c c-a term-bol                      Beginning of line; skip prompt.
-;; c-d	    term-delchar-or-maybe-eof     Delete char unless at end of buff.
-;; c-c c-u term-kill-input	    	    ^u
-;; c-c c-w backward-kill-word    	    ^w
-;; c-c c-c term-interrupt-subjob 	    ^c
-;; c-c c-z term-stop-subjob	    	    ^z
-;; c-c c-\ term-quit-subjob	    	    ^\
-;; c-c c-o term-kill-output		    Delete last batch of process output
-;; c-c c-r term-show-output		    Show last batch of process output
-;; c-c c-h term-dynamic-list-input-ring  List input history
+;; C-c C-a term-bol                      Beginning of line; skip prompt.
+;; C-d     term-delchar-or-maybe-eof     Delete char unless at end of buff.
+;; C-c C-u term-kill-input               ^u
+;; C-c C-w backward-kill-word            ^w
+;; C-c C-c term-interrupt-subjob         ^c
+;; C-c C-z term-stop-subjob              ^z
+;; C-c C-\ term-quit-subjob              ^\
+;; C-c C-o term-kill-output              Delete last batch of process output
+;; C-c C-r term-show-output              Show last batch of process output
+;; C-c C-h term-dynamic-list-input-ring  List input history
 ;;
 ;; Not bound by default in term-mode
 ;; term-send-invisible			Read a line w/o echo, and send to proc
@@ -314,8 +287,8 @@
 ;; term-replace-by-expanded-filename	Expand and complete filename at point;
 ;;					replace with expanded/completed name.
 ;; term-kill-subjob			No mercy.
-;; term-show-maximum-output            Show as much output as possible.
-;; term-continue-subjob		Send CONT signal to buffer's process
+;; term-show-maximum-output             Show as much output as possible.
+;; term-continue-subjob                 Send CONT signal to buffer's process
 ;;					group.  Useful if you accidentally
 ;;					suspend your process (with C-c C-z).
 
diff --git a/lisp/view.el b/lisp/view.el
index e4489b391a9..deda061cd39 100644
--- a/lisp/view.el
+++ b/lisp/view.el
@@ -383,8 +383,8 @@ own View-like bindings."
   "Toggle View mode, a minor mode for viewing text but not editing it.
 
 When View mode is enabled, commands that do not change the buffer
-contents are available as usual.  Kill commands insert text in
-kill buffers but do not delete.  Most other commands beep and
+contents are available as usual.  Kill commands save text but
+do not delete it from the buffer.  Most other commands beep and
 tell the user that the buffer is read-only.
 
 \\<view-mode-map>
diff --git a/lisp/window.el b/lisp/window.el
index 8597f870a5b..8b12c4381f4 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -8685,7 +8685,7 @@ and defaults to `window-min-width'.  Both MAX-WIDTH and MIN-WIDTH
 are specified in columns and include fringes, margins, a
 scrollbar and a vertical divider, if any.
 
-If the optional argument `preserve-size' is non-nil, preserve the
+Optional argument PRESERVE-SIZE non-nil means to preserve the
 size of WINDOW (see `window-preserve-size').
 
 Fit pixelwise if the option `window-resize-pixelwise' is non-nil.