Merge from origin/emacs-26

e5a2933 (origin/emacs-26) lisp/vc/: documentation fixes
f21f8e6 Document 'desktop-files-not-to-save'
d8917eb Improve documentation of Profiling features
b228839 Improve indexing of "performance" in ELisp manual
ab67b3e Minor change in Emacs manual's VC chapter
c352434 Avoid memory corruption with specpdl overflow + edebug (Bug#3...
593bbda Document comment-fill-column in the manual (Bug#11636)
bd4cc8d * doc/emacs/dired.texi (Marks vs Flags): Copyedits.
69107f3 ; Fix doc typos related to indefinite articles
aaad1e6 Merge branch 'emacs-26' of git.savannah.gnu.org:/srv/git/emac...
5906418 More fixes for the Emacs manual
9ab3df1 ; Fix doc typos related to indefinite articles
66a4e65 ; Fix doc typos related to indefinite articles
35e5c57 ; Fix doc typos related to indefinite articles

6 files changed, 42 insertions, 28 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 7e41eb32cce..3750fa60534 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -667,7 +667,7 @@ reason.
 
 @defun ask-user-about-supersession-threat filename
 This function is used to ask a user how to proceed after an attempt to
-modify an buffer visiting file @var{filename} when the file is newer
+modify a buffer visiting file @var{filename} when the file is newer
 than the buffer text.  Emacs detects this because the modification
 time of the file on disk is newer than the last save-time and its contents
 have changed.
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 09692073bf9..2daa8a5578f 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -918,51 +918,65 @@ be cleaner to combine them.
 @section Profiling
 @cindex profiling
 @cindex profile
+@cindex performance analysis
 @cindex measuring resource usage
 @cindex memory usage
 
-If your program is working correctly, but you want to make it run more
-quickly or efficiently, the first thing to do is @dfn{profile} your
-code so that you know how it is using resources.  If you find that one
-particular function is responsible for a significant portion of the
-runtime, you can start looking for ways to optimize that piece.
+If your program is working correctly, but not fast enough, and you
+want to make it run more quickly or efficiently, the first thing to do
+is @dfn{profile} your code so that you know where it spends most of
+the execution time.  If you find that one particular function is
+responsible for a significant portion of the execution time, you can
+start looking for ways to optimize that piece.
 
 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.  After doing some work, type
-@kbd{M-x profiler-report} to display a summary buffer for each
-resource 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 profiling).
+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
+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
+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, followed by how much resource (processor or memory) it used in
-absolute and percentage times since profiling started.  If a given
+called, followed by how much resources (cpu or memory) it used in
+absolute and percentage terms since profiling started.  If a given
 line has a @samp{+} symbol at the left-hand side, you can expand that
 line by typing @kbd{@key{RET}}, in order to see the function(s) called
 by the higher-level function.  Use a prefix argument (@kbd{C-u
 @key{RET}}) to see the whole call tree below a function.  Pressing
 @kbd{@key{RET}} again will collapse back to the original state.
 
-Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function.
-Press @kbd{d} to view a function's documentation.
-You can save a profile to a file using @kbd{C-x C-w}.
-You can compare two profiles using @kbd{=}.
+Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function
+at point.  Press @kbd{d} to view a function's documentation.  You can
+save a profile to a file using @kbd{C-x C-w}.  You can compare two
+profiles using @kbd{=}.
 
 @c FIXME reversed calltree?
 
 @cindex @file{elp.el}
 @cindex timing programs
-The @file{elp} library offers an alternative approach.  See the file
-@file{elp.el} for instructions.
+The @file{elp} library offers an alternative approach, which is useful
+when you know in advance which Lisp function(s) you want to profile.
+Using that library, you begin by setting @code{elp-function-list} to
+the list of function symbols---those are the functions you want to
+profile.  Then type @w{@kbd{M-x elp-instrument-list @key{RET} nil
+@key{RET}}} to arrange for profiling those functions.  After running
+the code you want to profile, invoke @w{@kbd{M-x elp-results}} to
+display the current results.  See the file @file{elp.el} for more
+detailed instructions.  This approach is limited to profiling
+functions written in Lisp, it cannot profile Emacs primitives.
 
 @cindex @file{benchmark.el}
 @cindex benchmarking
-You can check the speed of individual Emacs Lisp forms using the
-@file{benchmark} library.  See the functions @code{benchmark-run} and
-@code{benchmark-run-compiled} in @file{benchmark.el}.
+You can measure the time it takes to evaluate individual Emacs Lisp
+forms using the @file{benchmark} library.  See the macros
+@code{benchmark-run} and @code{benchmark-run-compiled} in
+@file{benchmark.el}.  You can also use the @code{benchmark} command
+for timing forms interactively.
 
 @c Not worth putting in the printed manual.
 @ifnottex
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 0c17e1e72ef..031fe65266e 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -898,7 +898,7 @@ lines inserted.
 
 @cindex coverage testing (Edebug)
 @cindex frequency counts
-@cindex performance analysis
+@cindex performance analysis (Edebug)
   Edebug provides rudimentary coverage testing and display of execution
 frequency.
 
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 877aaf89a35..d179cf56fd2 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -199,7 +199,7 @@ standard keyword from the @code{finder-known-keywords} list.
 as explained in @ref{Packaging Basics}.  In the above example, a magic
 comment autoloads @code{superfrobnicator-mode}.
 
-  @xref{Package Archives}, for a explanation of how to add a
+  @xref{Package Archives}, for an explanation of how to add a
 single-file package to a package archive.
 
 @node Multi-file Packages
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 299ed0b7d98..51a440cce74 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2981,7 +2981,7 @@ optional argument @var{append} is non-@code{nil}, @var{face} is
 appended to the end of the list instead.  Note that in a face list,
 the first occurring value for each attribute takes precedence.
 
-For example, the following code would assign a italicized green face
+For example, the following code would assign an italicized green face
 to the text between @var{start} and @var{end}:
 
 @example
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 5ab6d6ee6a4..687d5971920 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -862,7 +862,7 @@ If the optional argument @var{pixelwise} is non-@code{nil},
 A positive @var{delta} moves the edge downwards or to the right; a
 negative @var{delta} moves it upwards or to the left.  If the edge
 cannot be moved as far as specified by @var{delta}, this function
-moves it as far as possible but does not signal a error.
+moves it as far as possible but does not signal an error.
 
 This function tries to resize windows adjacent to the edge that is
 moved.  If this is not possible for some reason (e.g., if that adjacent