master 510458a 2/2: Merge from origin/emacs-27

[Glenn Morris]

branch: master
commit 510458a9f1e7e5a4924e80ceafbaf35e73cfac02
Merge: f8e5871 7722b51
Author: Glenn Morris <rgm@gnu.org>
Commit: Glenn Morris <rgm@gnu.org>

    Merge from origin/emacs-27
    
    7722b510aa (origin/emacs-27) Another improvement in documentation of ...
    8d5c70d73a Improve documentation of profiler
    0ffef0b46b Document 'ispell-program-name'
    7be610f911 Fix documentation of 'face-extend-p'
    
    # Conflicts:
    #   doc/lispref/debugging.texi
---
 doc/emacs/fixit.texi       |  7 +++++++
 doc/lispref/debugging.texi | 13 +++++++------
 doc/lispref/display.texi   |  5 +++--
 lisp/profiler.el           |  8 ++++++--
 4 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index acc0381..b558ebc 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -263,6 +263,13 @@ systems.
 @xref{Top, Aspell,, aspell, The Aspell Manual}.
 @end ifnottex
 
+@vindex ispell-program-name
+  If you have only one of the spelling checker programs installed,
+Emacs will find it when you invoke for the first time one of the
+commands described here.  If you have more than one of them installed,
+you can control which one is used by customizing the variable
+@code{ispell-program-name}.
+
 @table @kbd
 @item M-$
 Check and correct spelling of the word at point (@code{ispell-word}).
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index de98d22..e458d76 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -997,11 +997,12 @@ start looking for ways to optimize that piece.
 @findex profiler-report
 @findex profiler-stop
 Emacs has built-in support for this.  To begin profiling, type
-@kbd{M-x profiler-start}.  You can choose to profile by processor
-usage, memory usage, or both.  Then run the code you'd like to speed
-up.  After that, type @kbd{M-x profiler-report} to display a summary
-buffer for each resource (cpu and memory) that you chose to profile.
-The names of the report buffers include the times at which the reports
+@w{@kbd{M-x profiler-start}}.  You can choose to sample CPU usage
+periodically (@code{cpu}), when memory is allocated (@code{memory}),
+or both.  Then run the code you'd like to speed up.  After that, type
+@kbd{M-x profiler-report} to display a summary buffer for CPU usage
+sampled by each type (cpu and memory) that you chose to profile.  The
+names of the report buffers include the times at which the reports
 were generated, so you can generate another report later on without
 erasing previous results.  When you have finished profiling, type
 @kbd{M-x profiler-stop} (there is a small overhead associated with
@@ -1009,7 +1010,7 @@ profiling, so we don't recommend leaving it active except 
when you are
 actually running the code you want to examine).
 
 The profiler report buffer shows, on each line, a function that was
-called, preceded by how much resources (cpu or memory) it used in
+called, preceded by how much CPU resources it used in
 absolute and percentage terms since profiling started.  If a given
 line has a @samp{+} symbol to the left of the function name, you can
 expand that line by typing @kbd{@key{RET}}, in order to see the
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 2ed03f6..3336338 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3007,9 +3007,10 @@ This function returns non-@code{nil} if face @var{face} 
specifies
 a non-@code{nil} @code{:inverse-video} attribute.
 @end defun
 
-@defun face-extend-p face &optional frame
+@defun face-extend-p face &optional frame inherit
 This function returns non-@code{nil} if face @var{face} specifies
-a non-@code{nil} @code{:extend} attribute.
+a non-@code{nil} @code{:extend} attribute.  The @var{inherit} argument
+is passed to @code{face-attribute}.
 @end defun
 
 
diff --git a/lisp/profiler.el b/lisp/profiler.el
index 64d71f4..8145e51 100644
--- a/lisp/profiler.el
+++ b/lisp/profiler.el
@@ -822,8 +822,12 @@ below entry at point."
 (defun profiler-start (mode)
   "Start/restart profilers.
 MODE can be one of `cpu', `mem', or `cpu+mem'.
-If MODE is `cpu' or `cpu+mem', time-based profiler will be started.
-Also, if MODE is `mem' or `cpu+mem', then memory profiler will be started."
+If MODE is `cpu' or `cpu+mem', start the time-based profiler,
+   whereby CPU is sampled periodically using the SIGPROF signal.
+If MODE is `mem' or `cpu+mem', start profiler that samples CPU
+   whenever memory-allocation functions are called -- this is useful
+   if SIGPROF is not supported, or is unreliable, or is not sampling
+   at a high enough frequency."
   (interactive
    (list (if (not (fboundp 'profiler-cpu-start)) 'mem
            (intern (completing-read (format-prompt "Mode" "cpu")