Merge from origin/emacs-25

ec4226d * lisp/woman.el (woman): Fix docstring prefix arg description.
2b774fa Mention "editor" in Emacs man page header
ae60d0c Document problems with nerd-fonts
2fdb5a9 ; Details about pinning Emacs to w32 task bar
5c3105e * doc/lispref/modes.texi (Derived Modes): Make example more i...
4c51ef4 Clarify what is the "cursor"
8303c32 ; * etc/NEWS: Copyedits.
3f7493e ; Fix a typo in comment
c54cf8d Improve commentary in lisp.h
8b92f86 ; * admin/make-tarball.txt: Cross-reference admin/release-pro...
0ba9932 Disable native completion for ipython (Bug#25067)
38fc456 Fix a typo in ada-mode manual
00e75ba ; * src/coding.c (Fencode_coding_region): Fix a typo in the d...
a541c21 Clarify documentation of 'bufferpos-to-filepos' and 'filepos-...

# Conflicts:
#	etc/NEWS
#	etc/PROBLEMS

15 files changed, 48 insertions, 29 deletions

diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index d26f397e151..e5c77172c9f 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -55,9 +55,12 @@ General steps (for each step, check for possible errors):
     M-x set-version RET).  For a pretest, start at version .90.  After
     .99, use .990 (so that it sorts).
 
-    The final pretest should be a release candidate.  Set the version
-    number to that of the actual release.  Pick a date about a week
-    from now when you intend to make the release.  Use M-x
+    The final pretest should be a release candidate.
+    Before a release candidate is made, the tasks listed in
+    admin/release-process must be completed.
+
+    Set the version number to that of the actual release.  Pick a date
+    about a week from now when you intend to make the release.  Use M-x
     add-release-logs to add entries to etc/HISTORY and the ChangeLog
     file.  It's best not to commit these files until the release is
     actually made.  Merge the entries from (unversioned) ChangeLog
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 88e8e811a65..2e7d769f93d 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -820,14 +820,15 @@ which in turn may have been changed in a mode hook.
 Here is a hypothetical example:
 
 @example
+(defvar hypertext-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map [down-mouse-3] 'do-hyper-link)
+    map))
+
 (define-derived-mode hypertext-mode
   text-mode "Hypertext"
-  "Major mode for hypertext.
-\\@{hypertext-mode-map@}"
-  (setq case-fold-search nil))
-
-(define-key hypertext-mode-map
-  [down-mouse-3] 'do-hyper-link)
+  "Major mode for hypertext."
+  (setq-local case-fold-search nil))
 @end example
 
 Do not write an @code{interactive} spec in the definition;
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index ee4bef6e498..05c08c6dbe5 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -142,7 +142,7 @@ be one of the following:
 @table @code
 @item exact
 The result must be accurate.  The function may need to encode and
-decode a large part of the buffer.
+decode a large part of the buffer, which is expensive and can be slow.
 @item approximate
 The value can be an approximation.  The function may avoid expensive
 processing and return an inexact result.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index affa28c9202..a4f8400170e 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3532,9 +3532,13 @@ point and the buffer's point always move together; they remain equal.
 @end itemize
 
 @cindex cursor
-   As far as the user is concerned, point is where the cursor is, and
-when the user switches to another buffer, the cursor jumps to the
-position of point in that buffer.
+   Emacs displays the cursor, by default as a rectangular block, in
+each window at the position of that window's point.  When the user
+switches to another buffer in a window, Emacs moves that window's
+cursor to where point is in that buffer.  If the exact position of
+point is hidden behind some display element, such as a display string
+or an image, Emacs displays the cursor immediately before or after
+that display element.
 
 @defun window-point &optional window
 This function returns the current position of point in @var{window}.
diff --git a/doc/man/emacs.1.in b/doc/man/emacs.1.in
index 6807e866526..5d0948f51b3 100644
--- a/doc/man/emacs.1.in
+++ b/doc/man/emacs.1.in
@@ -3,7 +3,7 @@
 .
 .
 .SH NAME
-emacs \- GNU project Emacs
+emacs \- GNU project Emacs editor
 .
 .
 .SH SYNOPSIS
diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi
index 127a009417e..2ea4c7f36b2 100644
--- a/doc/misc/ada-mode.texi
+++ b/doc/misc/ada-mode.texi
@@ -540,7 +540,7 @@ Lisp variable: @code{ada-prj-default-bind-opt}.
 @item @code{build_dir}      [default: @code{"."}]
 The compile commands will be issued in this directory.
 
-@item @code{casing}         [default: @code{("~/.emacs_case_exceptions")}
+@item @code{casing}         [default: @code{("~/.emacs_case_exceptions")}]
 List of files containing casing exceptions. See the help on
 @code{ada-case-exception-file} for more info.
 @c FIXME: section on case exceptions
diff --git a/etc/NEWS b/etc/NEWS
index f047aa86f9f..f15635fb884 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -21,12 +21,11 @@ Temporary note:
 --- means no change in the manuals is needed.
 When you add a new item, use the appropriate mark if you are sure it applies,
 
-+++
 ** The version number of CC Mode has been changed from 5.33 to
 5.32.99, although the software itself hasn't changed.  This aims to
 reduce confusion with the standalone CC Mode 5.33 (available from
 http://cc-mode.sourceforge.net), which is a more mature version than
-the one in Emacs 25.2.
+the one included in Emacs 25.2.
 
 
 * Installation Changes in Emacs 26.1
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 15d2b74cc40..cf92db67afc 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -745,6 +745,10 @@ The solution is to install the appropriate fonts on your machine. For
 instance if you are editing a text with a lot of math symbols, then
 installing a font like 'Symbola' should solve this problem.
 
+Another reason for slow display is reportedly the nerd-fonts
+installation, even when Symbola is installed as well.  Uninstalling
+nerd-fonts was reported to solve the problem in that case.
+
 ** Emacs running on GNU/Linux system with the m17n library Ver.1.7.1 or the
 earlier version has a problem with rendering Bengali script.
 
diff --git a/lisp/international/mule-util.el b/lisp/international/mule-util.el
index 92a658655ac..e34b01c3064 100644
--- a/lisp/international/mule-util.el
+++ b/lisp/international/mule-util.el
@@ -342,7 +342,7 @@ QUALITY can be:
   `approximate', in which case we may cut some corners to avoid
     excessive work.
   `exact', in which case we may end up re-(en/de)coding a large
-    part of the file/buffer.
+    part of the file/buffer, this can be expensive and slow.
   nil, in which case we may return nil rather than an approximation."
   (unless coding-system (setq coding-system buffer-file-coding-system))
   (let ((eol (coding-system-eol-type coding-system))
@@ -418,7 +418,7 @@ QUALITY can be:
   `approximate', in which case we may cut some corners to avoid
     excessive work.
   `exact', in which case we may end up re-(en/de)coding a large
-    part of the file/buffer.
+    part of the file/buffer, this can be expensive and slow.
   nil, in which case we may return nil rather than an approximation."
   (unless coding-system (setq coding-system buffer-file-coding-system))
   (let* ((eol (coding-system-eol-type coding-system))
diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index d4ed1392703..58b16794ee0 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -3276,8 +3276,10 @@ the full statement in the case of imports."
   "Completion string code must work for (i)pdb.")
 
 (defcustom python-shell-completion-native-disabled-interpreters
-  ;; PyPy's readline cannot handle some escape sequences yet.
-  (list "pypy")
+  ;; PyPy's readline cannot handle some escape sequences yet.  Native
+  ;; completion was found to be non-functional for IPython (see
+  ;; Bug#25067).
+  (list "pypy" "ipython")
   "List of disabled interpreters.
 When a match is found, native completion is disabled."
   :version "25.1"
diff --git a/lisp/vc/ediff-wind.el b/lisp/vc/ediff-wind.el
index 8516c11d136..9b3d53fca76 100644
--- a/lisp/vc/ediff-wind.el
+++ b/lisp/vc/ediff-wind.el
@@ -579,7 +579,7 @@ into icons, regardless of the window manager."
     (if (and (window-live-p wind-A)
              (null use-same-frame) ; implies wind-A is suitable
              (null use-same-frame-for-AB))
-        (progn ; bug A on its own
+        (progn ; buf A on its own
           ;; buffer buf-A is seen in live wind-A
           (select-window wind-A)
           (delete-other-windows)
diff --git a/lisp/woman.el b/lisp/woman.el
index 2021fb26968..720fe66be86 100644
--- a/lisp/woman.el
+++ b/lisp/woman.el
@@ -1159,7 +1159,7 @@ The major browsing mode used is essentially the standard Man mode.
 Choose the filename for the man page using completion, based on the
 topic selected from the directories specified in `woman-manpath' and
 `woman-path'.  The directory expansions and topics are cached for
-speed, but a non-nil interactive argument forces the caches to be
+speed.  With a prefix argument, force the caches to be
 updated (e.g. to re-interpret the current directory).
 
 Used non-interactively, arguments are optional: if given then TOPIC
diff --git a/nt/README.W32 b/nt/README.W32
index 644e0fe881a..1141e8a1b71 100644
--- a/nt/README.W32
+++ b/nt/README.W32
@@ -105,7 +105,9 @@ See the end of the file for license conditions.
   + runemacs.exe - A wrapper for running Emacs as a GUI application
     without popping up a command prompt window.  If you create a
     desktop shortcut for invoking Emacs, make it point to this
-    executable, not to emacs.exe.
+    executable, not to emacs.exe.  If you pin Emacs to the task bar,
+    edit the properties of the pinned shortcut (with Shift-right mouse
+    click) to point to this executable.
 
   + emacsclient.exe - A command-line client program that can
     communicate with a running Emacs process.  See the `Emacs Server'
diff --git a/src/coding.c b/src/coding.c
index 68ed8629c1c..e341a71f576 100644
--- a/src/coding.c
+++ b/src/coding.c
@@ -9399,8 +9399,8 @@ When called from a program, takes four arguments:
         START, END, CODING-SYSTEM and DESTINATION.
 START and END are buffer positions.
 
-Optional 4th arguments DESTINATION specifies where the encoded text goes.
-If nil, the region between START and END is replace by the encoded text.
+Optional 4th argument DESTINATION specifies where the encoded text goes.
+If nil, the region between START and END is replaced by the encoded text.
 If buffer, the encoded text is inserted in that buffer after point (point
 does not move).
 In those cases, the length of the encoded text is returned.
diff --git a/src/lisp.h b/src/lisp.h
index ab4db4cac02..4b9cd3c4702 100644
--- a/src/lisp.h
+++ b/src/lisp.h
@@ -519,10 +519,14 @@ enum Lisp_Fwd_Type
    to add a new Lisp_Misc, extend the Lisp_Misc_Type enumeration.
 
    For a Lisp_Misc, you will also need to add your entry to union
-   Lisp_Misc (but make sure the first word has the same structure as
+   Lisp_Misc, but make sure the first word has the same structure as
    the others, starting with a 16-bit member of the Lisp_Misc_Type
-   enumeration and a 1-bit GC markbit) and make sure the overall size
-   of the union is not increased by your addition.
+   enumeration and a 1-bit GC markbit.  Also make sure the overall
+   size of the union is not increased by your addition.  The latter
+   requirement is to keep Lisp_Misc objects small enough, so they
+   are handled faster: since all Lisp_Misc types use the same space,
+   enlarging any of them will affect all the rest.  If you really
+   need a larger object, it is best to use Lisp_Vectorlike instead.
 
    For a new pseudovector, it's highly desirable to limit the size
    of your data type by VBLOCK_BYTES_MAX bytes (defined in alloc.c).