Merge from origin/emacs-26

6415b2d Allow read-passwd to hide characters inserted by C-y.  (Secur...
8cb4ffb * etc/PROBLEMS: Document issues with double-buffering.  (Bug#...
fd10070 * lisp/window.el (window-largest-empty-rectangle): Fix grammar.
e1a4403 Minor changes in the Emacs manual
372fda6 Improve the "Files" chapter of the Emacs manual
9afc86d Improve the "Search" chapter of the Emacs manual
22f98b3 * src/indent.c (Findent_to): Doc fix.  (Bug#30260)
085ee43 Improve documentation of 'edebug-defun'
4dd1b33 Mention crashes due to Noto Serif Kannada fonts

3 files changed, 54 insertions, 42 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 881210aab9a..083f64704ae 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -738,7 +738,7 @@ survive a crash even if @code{fsync} works properly.
   The @code{write-region-inhibit-fsync} variable controls whether
 Emacs invokes @code{fsync} after saving a file.  The variable's
 default value is @code{nil} when Emacs is interactive, and @code{t}
-when Emacs runs in batch mode.
+when Emacs runs in batch mode (@pxref{Initial Options, batch mode}).
 
   Emacs never uses @code{fsync} when writing auto-save files, as these
 files might lose data anyway.
@@ -824,6 +824,25 @@ diff-buffer-with-file} command.  @xref{Comparing Files}.
 @cindex file shadows
 @findex shadow-initialize
 
+  You can arrange to keep identical @dfn{shadow} copies of certain
+files in more than one place---possibly on different machines.  To do
+this, first you must set up a @dfn{shadow file group}, which is a set
+of identically-named files shared between a list of sites.  The file
+group is permanent and applies to further Emacs sessions as well as
+the current one.  Once the group is set up, every time you exit Emacs,
+it will copy the file you edited to the other files in its group.  You
+can also do the copying without exiting Emacs, by typing @w{@kbd{M-x
+shadow-copy-files}}.
+
+@cindex shadow cluster
+A @dfn{shadow cluster} is a group of hosts that share directories, so
+that copying to or from one of them is sufficient to update the file
+on all of them.  Each shadow cluster has a name, and specifies the
+network address of a primary host (the one we copy files to), and a
+regular expression that matches the host names of all the other hosts
+in the cluster.  You can define a shadow cluster with @w{@kbd{M-x
+shadow-define-cluster}}.
+
 @table @kbd
 @item M-x shadow-initialize
 Set up file shadowing.
@@ -839,32 +858,15 @@ Copy all pending shadow files.
 Cancel the instruction to shadow some files.
 @end table
 
-You can arrange to keep identical @dfn{shadow} copies of certain files
-in more than one place---possibly on different machines.  To do this,
-first you must set up a @dfn{shadow file group}, which is a set of
-identically-named files shared between a list of sites.  The file
-group is permanent and applies to further Emacs sessions as well as
-the current one.  Once the group is set up, every time you exit Emacs,
-it will copy the file you edited to the other files in its group.  You
-can also do the copying without exiting Emacs, by typing @kbd{M-x
-shadow-copy-files}.
-
-To set up a shadow file group, use @kbd{M-x
-shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
-See their documentation strings for further information.
+To set up a shadow file group, use @w{@kbd{M-x
+shadow-define-literal-group}} or @w{@kbd{M-x
+shadow-define-regexp-group}}.  See their documentation strings for
+further information.
 
 Before copying a file to its shadows, Emacs asks for confirmation.
 You can answer ``no'' to bypass copying of this file, this time.  If
 you want to cancel the shadowing permanently for a certain file, use
-@kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
-
-A @dfn{shadow cluster} is a group of hosts that share directories, so
-that copying to or from one of them is sufficient to update the file
-on all of them.  Each shadow cluster has a name, and specifies the
-network address of a primary host (the one we copy files to), and a
-regular expression that matches the host names of all the other hosts
-in the cluster.  You can define a shadow cluster with @kbd{M-x
-shadow-define-cluster}.
+@w{@kbd{M-x shadow-cancel}} to eliminate or change the shadow file group.
 
 @node Time Stamps
 @subsection Updating Time Stamps Automatically
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index b351a741aa5..bb01f10d2cb 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -776,16 +776,16 @@ Search}.
 @cindex regular expression
 @cindex regexp
 
-  This manual describes regular expression features that users
-typically use.  @xref{Regular Expressions,,, elisp, The Emacs Lisp
-Reference Manual}, for additional features used mainly in Lisp
-programs.
+  This section (and this manual in general) describes regular
+expression features that users typically use.  @xref{Regular
+Expressions,,, elisp, The Emacs Lisp Reference Manual}, for additional
+features used mainly in Lisp programs.
 
   Regular expressions have a syntax in which a few characters are
 special constructs and the rest are @dfn{ordinary}.  An ordinary
 character matches that same character and nothing else.  The special
 characters are @samp{$^.*+?[\}.  The character @samp{]} is special if
-it ends a character alternative (see later).  The character @samp{-}
+it ends a character alternative (see below).  The character @samp{-}
 is special inside a character alternative.  Any other character
 appearing in a regular expression is ordinary, unless a @samp{\}
 precedes it.  (When you use regular expressions in a Lisp program,
@@ -803,11 +803,11 @@ of ``the same string'', rather than an exception.)
   Any two regular expressions @var{a} and @var{b} can be concatenated.
 The result is a regular expression which matches a string if @var{a}
 matches some amount of the beginning of that string and @var{b}
-matches the rest of the string.  For example, concatenating the
-regular expressions @samp{f} and @samp{o} gives the regular expression
-@samp{fo}, which matches only the string @samp{fo}.  Still trivial.
-To do something nontrivial, you need to use one of the special
-characters.  Here is a list of them.
+matches the rest of the string.  As a trivial example, concatenating
+the regular expressions @samp{f} and @samp{o} gives the regular
+expression @samp{fo}, which matches only the string @samp{fo}.  To do
+something less trivial, you need to use one of the special characters.
+Here is a list of them.
 
 @table @asis
 @item @kbd{.}@: @r{(Period)}
@@ -1025,13 +1025,13 @@ To record a matched substring for future reference.
 
 This last application is not a consequence of the idea of a
 parenthetical grouping; it is a separate feature that is assigned as a
-second meaning to the same @samp{\( @dots{} \)} construct.  In practice
+second meaning to the same @w{@samp{\( @dots{} \)}} construct.  In practice
 there is usually no conflict between the two meanings; when there is
-a conflict, you can use a shy group.
+a conflict, you can use a shy group, described below.
 
 @item \(?: @dots{} \)
 @cindex shy group, in regexp
-specifies a shy group that does not record the matched substring;
+specifies a @dfn{shy group} that does not record the matched substring;
 you can't refer back to it with @samp{\@var{d}} (see below).  This is
 useful in mechanically combining regular expressions, so that you can
 add groups for syntactic purposes without interfering with the
@@ -1908,7 +1908,7 @@ which Emacs will use this display mode.  The variable
 @code{search-slow-window-lines} controls the number of lines in the
 window Emacs pops up for displaying the search results; the default is
 1 line.  Normally, this window will pop up at the bottom of the window
-that displays the buffer where you start searching, bit if the value
+that displays the buffer where you start searching, but if the value
 of @code{search-slow-window-lines} is negative, that means to put the
 window at the top and give it the number of lines that is the absolute
-value of that value.
+value of @code{search-slow-window-lines}.
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 1a883e0f142..0c17e1e72ef 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -209,6 +209,20 @@ session, it runs the hook @code{edebug-setup-hook}, then sets it to
 @code{nil}.  You can use this to load Edebug specifications
 associated with a package you are using, but only when you use Edebug.
 
+@cindex edebug, failure to instrument
+  If Edebug detects a syntax error while instrumenting, it leaves point
+at the erroneous code and signals an @code{invalid-read-syntax} error.
+@c FIXME?  I can't see that it "leaves point at the erroneous code".
+Example:
+
+@example
+@error{} Invalid read syntax: "Expected lambda expression"
+@end example
+
+  One potential reason for such a failure to instrument is that some
+macro definitions are not yet known to Emacs.  To work around this,
+load the file which defines the function you are about to instrument.
+
 @findex eval-expression @r{(Edebug)}
   To remove instrumentation from a definition, simply re-evaluate its
 definition in a way that does not instrument.  There are two ways of
@@ -216,10 +230,6 @@ evaluating forms that never instrument them: from a file with
 @code{load}, and from the minibuffer with @code{eval-expression}
 (@kbd{M-:}).
 
-  If Edebug detects a syntax error while instrumenting, it leaves point
-at the erroneous code and signals an @code{invalid-read-syntax} error.
-@c FIXME?  I can't see that it "leaves point at the erroneous code".
-
   @xref{Edebug Eval}, for other evaluation functions available
 inside of Edebug.