Merge from origin/emacs-25

a094732 * etc/PROBLEMS: Say that HP-UX cc doesn't work.
1925dd9 Fix duplicate wording in Emacs manual
6de8429 * lisp/paren.el (show-paren--default, show-paren-function): A...
2d671fd Fix wording in Emacs manual
a8766a2 Document how to customize input methods
6eb8995 * lisp/net/eww.el (eww-reload): Doc fix.  (Bug#25981)
aceac95 Fix warning message about native completion (Bug#25984)
a314c1f Clarify documentation of 'raise' and 'height' display specs
f366f6e Mention problems with GPaste in PROBLEMS
6e788ef ; etc/PROBLEMS: Explain about the python+libedit problem (Bug...
6406618 Fix doc strings in info.el
c1ed152 ; * src/keyboard.c (Fposn_at_point): Fix last change.
eed9677 Fix doc string of 'posn-at-point'
0d5957e Documentation fix in elisp reference manual

11 files changed, 71 insertions, 27 deletions

diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index 76bc945fb27..13407f6f07b 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -553,6 +553,15 @@ most input methods---some disable this feature).  If
 possible characters to type next is displayed in the echo area (but
 not when you are in the minibuffer).
 
+@vindex quail-activate-hook
+@findex quail-translation-keymap
+  You can modify how an input method works by making your changes in a
+function that you add to the hook variable @code{quail-activate-hook}.
+@xref{Hooks}.  For example, you can redefine some of the input
+method's keys by defining key bindings in the keymap returned by the
+function @code{quail-translation-keymap}, using @code{define-key}.
+@xref{Init Rebinding}.
+
   Another facility for typing characters not on your keyboard is by
 using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single
 character based on its Unicode name or code-point; see @ref{Inserting
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 97751aa2fac..1533c7ee8bb 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -327,7 +327,7 @@ as you move around in a buffer.
 @vindex which-func-modes
   To either enable or disable Which Function mode, use the command
 @kbd{M-x which-function-mode}.  Which Function mode is a global minor
-mode.  By default, it takes effect in all major modes major modes that
+mode.  By default, it takes effect in all major modes that
 know how to support it (i.e., all the major modes that support
 Imenu).  You can restrict it to a specific list of major modes by
 changing the value of the variable @code{which-func-modes} from
diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 3c46049b225..5f02d0b6920 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -296,7 +296,7 @@ mark by one paragraph.
 
   The definition of a paragraph depends on the major mode.  In
 Fundamental mode, as well as Text mode and related modes, a paragraph
-is separated each neighboring paragraph another by one or more
+is separated from neighboring paragraphs by one or more
 @dfn{blank lines}---lines that are either empty, or consist solely of
 space, tab and/or formfeed characters.  In programming language modes,
 paragraphs are usually defined in a similar way, so that you can use
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index aa10c1f07f4..57dd16decaf 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4666,16 +4666,21 @@ a form.  Emacs evaluates it to get the new height, with the symbol
 
 @item (raise @var{factor})
 This kind of display specification raises or lowers the text
-it applies to, relative to the baseline of the line.
-
-@var{factor} must be a number, which is interpreted as a multiple of the
-height of the affected text.  If it is positive, that means to display
-the characters raised.  If it is negative, that means to display them
-lower down.
-
-If the text also has a @code{height} display specification, that does
-not affect the amount of raising or lowering, which is based on the
-faces used for the text.
+it applies to, relative to the baseline of the line.  It is mainly
+meant to support display of subscripts and superscripts.
+
+The @var{factor} must be a number, which is interpreted as a multiple
+of the height of the affected text.  If it is positive, that means to
+display the characters raised.  If it is negative, that means to
+display them lower down.
+
+Note that if the text also has a @code{height} display specification,
+which was specified before (i.e.@: to the left of) @code{raise}, the
+latter will affect the amount of raising or lowering in pixels,
+because that is based on the height of the text being raised.
+Therefore, if you want to display a sub- or superscript that is
+smaller than the normal text height, consider specifying @code{raise}
+before @code{height}.
 @end table
 
 @c We put all the '@code{(when ...)}' on one line to encourage
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 5638dfaecf8..63a65a81304 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -255,10 +255,6 @@ of constants and nonconstant parts.  To make this easier, use the
 @end example
 @end example
 
-  The body of a macro definition can include a @code{declare} form,
-which specifies additional properties about the macro.  @xref{Declare
-Form}.
-
 @node Problems with Macros
 @section Common Problems Using Macros
 @cindex macro caveats
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index cf92db67afc..145dd140093 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -469,6 +469,23 @@ problem by adding this to your .cshrc file:
         stty -icrnl -onlcr -echo susp ^Z
     endif
 
+*** In Inferior Python mode, input is echoed and native completion doesn't work.
+<https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25753>
+
+This happens when python uses a libedit based readline module, which
+is the default on macOS.  This can be worked around by installing a
+GNU readline based module instead, for example, using setuptools
+
+    sudo easy_install gnureadline
+
+And then rename the system's readline so that it won't be loaded:
+
+    cd /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload
+    mv readline.so readline.so.bak
+
+See <https://pypi.python.org/pypi/gnureadline> for more details on
+installation.
+
 *** Emacs startup on GNU/Linux systems (and possibly other systems) is slow.
 
 This can happen if the system is misconfigured and Emacs can't get the
@@ -1044,6 +1061,13 @@ incompatibility of the Gnome terminal with Xterm, which also affects
 other programs using the Xterm mouse interface.  A problem report has
 been filed.
 
+*** Gnome: GPaste clipboard manager causes erratic behavior of 'yank'
+
+The symptom is that 'kill-line' followed by 'yank' often (but not
+always) doesn't insert the whitespace of the killed and yanked line.
+
+The solution is to set the GPaste "trim items" option to OFF.
+
 *** KDE: When running on KDE, colors or fonts are not as specified for Emacs,
 or messed up.
 
@@ -1935,6 +1959,13 @@ EOF
 
 This is a bug in HPUX; HPUX patch PHKL_16260 is said to fix it.
 
+*** HP-UX 11.31 cc: Emacs does not build.
+
+HP-UX 11.31 cc has bugs in its implementation of flexible array
+members, a C99 feature that Emacs relies on.  To work around the
+problem, install GCC and use it to build Emacs.  For details, see:
+http://lists.gnu.org/archive/html/bug-gnulib/2017-03/msg00066.html
+
 ** AIX
 
 *** AIX: Trouble using ptys.
diff --git a/lisp/info.el b/lisp/info.el
index a023080c8da..8dc85f48a43 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -358,17 +358,17 @@ with wrapping around the current Info node."
   ;; Try to obey obsolete Info-fontify settings.
   (unless (and (boundp 'Info-fontify) (null Info-fontify))
     '(turn-on-font-lock))
-  "Hooks run when `Info-mode' is called."
+  "Hook run when activating Info Mode."
   :type 'hook
   :group 'info)
 
 (defcustom Info-selection-hook nil
-  "Hooks run when `Info-select-node' is called."
+  "Hook run when an Info node is selected as the current node."
   :type 'hook
   :group 'info)
 
 (defvar Info-edit-mode-hook nil
-  "Hooks run when `Info-edit-mode' is called.")
+  "Hook run when `Info-edit-mode' is activated.")
 
 (make-obsolete-variable 'Info-edit-mode-hook
 			"editing Info nodes by hand is not recommended." "24.4")
diff --git a/lisp/net/eww.el b/lisp/net/eww.el
index 617c7835021..619c703e01c 100644
--- a/lisp/net/eww.el
+++ b/lisp/net/eww.el
@@ -900,8 +900,9 @@ appears in a <link> or <a> tag."
 
 (defun eww-reload (&optional local encode)
   "Reload the current page.
-If LOCAL (the command prefix), don't reload the page from the
-network, but just re-display the HTML already fetched."
+If LOCAL is non-nil (interactively, the command was invoked with
+a prefix argument), don't reload the page from the network, but
+just re-display the HTML already fetched."
   (interactive "P")
   (let ((url (plist-get eww-data :url)))
     (if local
diff --git a/lisp/paren.el b/lisp/paren.el
index a8ac09cf916..a4d9200c42f 100644
--- a/lisp/paren.el
+++ b/lisp/paren.el
@@ -176,6 +176,9 @@ if there's no opener/closer near point, or a list of the form
 Where HERE-BEG..HERE-END is expected to be near point.")
 
 (defun show-paren--default ()
+  "Finds the opener/closer near point and its match.
+
+It is the default value of `show-paren-data-function'."
   (let* ((temp (show-paren--locate-near-paren))
 	 (dir (car temp))
 	 (outside (cdr temp))
@@ -228,9 +231,8 @@ Where HERE-BEG..HERE-END is expected to be near point.")
 		  (if (= dir 1) pos (1+ pos))
 		  mismatch)))))))
 
-;; Find the place to show, if there is one,
-;; and show it until input arrives.
 (defun show-paren-function ()
+  "Highlight the parentheses until the next input arrives."
   (let ((data (and show-paren-mode (funcall show-paren-data-function))))
     (if (not data)
         (progn
diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index 58b16794ee0..228a4484616 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -3473,7 +3473,7 @@ With argument MSG show activation/deactivation message."
            :warning
            (concat
             "Your `python-shell-interpreter' doesn't seem to "
-            "support readline, yet `python-shell-completion-native' "
+            "support readline, yet `python-shell-completion-native-enable' "
             (format "was t and %S is not part of the "
                     (file-name-nondirectory python-shell-interpreter))
             "`python-shell-completion-native-disabled-interpreters' "
diff --git a/src/keyboard.c b/src/keyboard.c
index ec4dee01720..2e0a813bb08 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -10758,13 +10758,13 @@ The `posn-' functions access elements of such lists.  */)
 }
 
 DEFUN ("posn-at-point", Fposn_at_point, Sposn_at_point, 0, 2, 0,
-       doc: /* Return position information for buffer POS in WINDOW.
+       doc: /* Return position information for buffer position POS in WINDOW.
 POS defaults to point in WINDOW; WINDOW defaults to the selected window.
 
-Return nil if position is not visible in window.  Otherwise,
+Return nil if POS is not visible in WINDOW.  Otherwise,
 the return value is similar to that returned by `event-start' for
 a mouse click at the upper left corner of the glyph corresponding
-to the given buffer position:
+to POS:
    (WINDOW AREA-OR-POS (X . Y) TIMESTAMP OBJECT POS (COL . ROW)
     IMAGE (DX . DY) (WIDTH . HEIGHT))
 The `posn-' functions access elements of such lists.  */)