[Emacs-diffs] emacs-26 4139787: Simplify Flymake user documentation

[João Távora]

branch: emacs-26
commit 413978727c9fb1d26b64e81412434064d99ec568
Author: João Távora <address@hidden>
Commit: João Távora <address@hidden>

    Simplify Flymake user documentation
    
    Fix some confusing parts of Flymake user documentation, like a
    repeated listing of situations leading to a syntax check.
    Documentation is now divided into three chapters only: "Using
    Flymake", "Extending Flymake", and a chapter for the legacy backend.
    
    Obsolete mention of "errors" and "lines" is replaced by
    "diagnostics/problems" and "regions" where appropriate.
    
    * doc/misc/flymake.texi (Overview of Flymake): Delete chapter.
    (Using Flymake): Merge with chapter "Overview of Flymake".
    (Installing Flymake): Delete chapter.
    (Flymake mode, Running the syntax check)
    (Navigating to error lines): Delete sections.
    (Syntax check statuses): Review and augment with x-references.
    (Backend exceptions): Mention shortcut in menu.
    
    * lisp/progmodes/flymake.el (flymake-menu): Tweak minor mode
    menu to not speak of "errors".
    (flymake-goto-next-error, flymake-goto-prev-error): Fix
    wording.
---
 doc/misc/flymake.texi     | 166 ++++++++++++++++------------------------------
 lisp/progmodes/flymake.el |  31 ++++-----
 2 files changed, 73 insertions(+), 124 deletions(-)

diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index d89a555..05d879d 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -52,8 +52,6 @@ modify this GNU manual.''
 @end ifnottex
 
 @menu
-* Overview of Flymake::
-* Installing Flymake::
 * Using Flymake::
 * Extending Flymake::
 * The legacy Proc backend::
@@ -61,50 +59,57 @@ modify this GNU manual.''
 * Index::
 @end menu
 
address@hidden Overview of Flymake
address@hidden Overview
address@hidden Using Flymake
address@hidden Using Flymake
 @cindex overview of flymake
address@hidden using flymake
 
 Flymake is a universal on-the-fly buffer checker implemented as an
-Emacs minor mode.  When enabled, Flymake visually annotates the buffer
-with diagnostic information coming from one or more different sources,
-or @dfn{backends}.
+Emacs minor minor.  To use Flymake, you must first activate
address@hidden by using the command @kbd{flymake-mode}.
 
-Flymake annotates the buffer by highlighting problematic buffer
-regions with a special space.  It displays an overall buffer status in
-the mode line containing totals for different types of diagnostics.
-
address@hidden and @code{flymake-goto-prev-error} are
-commands that allow easy navigation to the next/previous erroneous
-line, respectively.  If might be a good idea to map them to @kbd{M-n}
-and @kbd{M-p} in @code{flymake-mode}, by adding to your init file:
+When enabled, Flymake collects information about problems in the
+buffer, called @dfn{diagnostics}, from one or more different sources,
+or @dfn{backends}, and then visually annotates the buffer by
+highlighting problematic buffer regions with a special face.
 
address@hidden
-(define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error)
-(define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error)
address@hidden lisp
+It also displays an overall buffer status in the mode line containing
+totals for different types of diagnostics.
 
 Syntax check is done ``on-the-fly''.  It is started whenever
 
 @itemize @bullet
 @item
 @code{flymake-mode} is started, unless
address@hidden is nil.
address@hidden is nil;
 
 @item
 a newline character is added to the buffer, unless
address@hidden is nil.
address@hidden is nil;
 
 @item
 some changes were made to the buffer more than @code{0.5} seconds ago
 (the delay is configurable in @code{flymake-no-changes-timeout}).
 @end itemize
 
+Syntax check can also be started manually by typing the @kbd{M-x
+flymake-start @key{RET}} command.
+
address@hidden and @code{flymake-goto-prev-error} are
+commands that allow easy navigation to the next/previous erroneous
+line, respectively.  If might be a good idea to map them to @kbd{M-n}
+and @kbd{M-p} in @code{flymake-mode}, by adding to your init file:
+
address@hidden
+(define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error)
+(define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error)
address@hidden lisp
+
 Flymake is a universal syntax checker in the sense that it's easily
 extended to support new backends (@pxref{Extending Flymake}).
 
-Historically, Flymake used to accept diagnostics from a single, albeit
-reasonably flexible, backend.
+Historically, Flymake used to accept diagnostics from a single
+backend, albeit a reasonably flexible one.
 
 This backend isn't (yet) obsolete, and so is still available as a
 fallback and active by default (@pxref{The legacy Proc backend}).  It works by
@@ -114,105 +119,45 @@ background, passing it a temporary file which is a copy 
of the current
 buffer, and parsing the output for known error/warning message
 patterns.
 
address@hidden Installing Flymake
address@hidden Installing
address@hidden installing flymake
-
-Flymake is included with Emacs and its main commands, like
address@hidden, are autoloaded.  This means there is usually
-nothing to do by way of installation.
-
address@hidden Using Flymake
address@hidden Using Flymake
address@hidden using flymake
-
 @menu
-* Flymake mode::
-* Running the syntax check::
-* Navigating to error lines::   @c * Viewing error messages::
 * Syntax check statuses::
 * Backend exceptions::
 * Customizable variables::
 @end menu
 
address@hidden Flymake mode
address@hidden Flymake mode
address@hidden flymake-mode
address@hidden activating flymake-mode
-
-Flymake is an Emacs minor mode.  To use Flymake, you
-must first activate @code{flymake-mode} by using the command
address@hidden
-
-Instead of manually activating @code{flymake-mode}, you can configure
-Emacs to automatically enable @code{flymake-mode} upon opening any
-file for which syntax check is possible.  To do so, place the following
-line in your @file{~/.emacs}:
-
address@hidden
-(add-hook 'find-file-hook 'flymake-find-file-hook)
address@hidden lisp
-
address@hidden Running the syntax check
address@hidden Running the syntax check
address@hidden manually starting syntax check
address@hidden syntax check, start manually
-
address@hidden flymake-start
-When @code{flymake-mode} is active, syntax check is started
-automatically on any of the three conditions mentioned in
address@hidden of Flymake}.  Syntax check can also be started manually
-by typing the @kbd{M-x flymake-start @key{RET}} command.
-
address@hidden Navigating to error lines
address@hidden Navigating to error lines
address@hidden navigating to error lines
-
-After syntax check is completed, lines for which at least one error or
-warning has been reported are highlighted, and the total number of errors
-and warning is shown in the mode line.  Use the following functions to
-navigate the highlighted lines:
-
address@hidden @code
address@hidden flymake-goto-next-error
address@hidden flymake-goto-next-error
-Moves point to the next erroneous line, if any.
-
address@hidden flymake-goto-prev-error
address@hidden flymake-goto-prev-error
-Moves point to the previous erroneous line.
address@hidden table
-
-If the user option @code{flymake-wrap-around} is active
-(@pxref{Customizable variables}), these functions treat diagnostics
-as a linked list.  Therefore, @code{flymake-goto-next-error} will go
-to the first diagnostic when invoked in the end of the buffer.
-
 @node Syntax check statuses
 @section Syntax check statuses
 @cindex Syntax check statuses
 
-While enabled, Flymake displays its status in the mode line.
+When enabled, Flymake displays its status in the mode line, which
+provides a visual summary of diagnostic collection.  It may also hint
+at certain exceptional situations encountered when communicating with
+backends.
+
 The following statuses are defined:
 
 @multitable @columnfractions 0.25 0.75
address@hidden address@hidden @var{nwarnings} ...]
address@hidden Normal operation. @var{nerrors} and @var{nwarnings} are, 
respectively,
+the total number of errors and warnings found during the last buffer
+check, for all backends. They may be followed by other totals for
+other types of diagnostics (@pxref{Flymake error types}).
+
 @item @code{Wait}
address@hidden  Some flymake backends haven't reported since the last time they
-where questioned.
address@hidden  Some Flymake backends haven't reported since the last time they
+where questioned.  It is reasonable to assume that this is a temporary
+delay and Flymake will resume normal operation soon.
 
 @item @code{!}
address@hidden All the configured Flymake backends have disabled themselves.
-Left-clicking Flymake's mode line indicator pops up a menu listing the
-option to visit Flymake's log buffer.  In this buffer these situations
-can be investigated.
address@hidden All the configured Flymake backends have disabled themselves: 
Flymake
+cannot annotate the buffer and action from the user is needed to
+investigate and remedy the situation (@pxref{Backend exceptions}).
 
 @item @code{?}
address@hidden There are no configured Flymake backends in
address@hidden
address@hidden There are no applicable Flymake backends for this buffer, thus 
Flymake
+cannot annotate it.  To fix this, a user may look to extending Flymake
+and add a new backend (@pxref{Extending Flymake}).
 
address@hidden @emph{[nerrors nwarnings]}
address@hidden Normal operation, number of errors/warnings found by the syntax
-check process.
 @end multitable
 
 @node Backend exceptions
@@ -223,8 +168,9 @@ check process.
 @cindex backends, disabled
 Some backends may take longer than others to respond or complete, and
 some may decide to @emph{disable} themselves if they are not suitable
-for the current buffer.  A disabled backend is not tried again for
-future checks of the current buffer.
+for the current buffer or encounter some unavoidable problem.  A
+disabled backend is not tried again for future checks of the current
+buffer.
 
 @findex flymake-reporting-backends
 @findex flymake-running-backends
@@ -240,10 +186,12 @@ disabled backend list, so that they will be tried again 
in the next check.
 
 @cindex logging
 @cindex flymake logging
-Flymake also uses a simple logging facility for indicating important points
-in the control flow.  The logging facility sends logging messages to
-the @file{*Flymake log*} buffer.  The information logged can be used for
-resolving various problems related to Flymake.
+Flymake also uses a simple logging facility for indicating important
+points in the control flow.  The logging facility sends logging
+messages to the @file{*Flymake log*} buffer.  The information logged
+can be used for resolving various problems related to Flymake.  For
+convenience, a shortcut to this buffer can be found in Flymake's menu,
+accessible from the top menu bar or just left of the status indicator.
 
 @vindex warning-minimum-log-level
 @vindex warning-minimum-level
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index e4c6a38..8c9c4b2 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -878,11 +878,11 @@ Do it only if `flymake-no-changes-timeout' is non-nil."
     (flymake-log :warning "Turned on in `flymake-find-file-hook'")))
 
 (defun flymake-goto-next-error (&optional n filter interactive)
-  "Go to Nth next Flymake error in buffer matching FILTER.
-Interactively, always move to the next error.  With a prefix arg,
-skip any diagnostics with a severity less than `:warning'.
+  "Go to Nth next Flymake diagnostic that matches FILTER.
+Interactively, always move to the next diagnostic.  With a prefix
+arg, skip any diagnostics with a severity less than `:warning'.
 
-If `flymake-wrap-around' is non-nil and no more next errors,
+If `flymake-wrap-around' is non-nil and no more next diagnostics,
 resumes search from top.
 
 FILTER is a list of diagnostic types found in
@@ -933,12 +933,13 @@ applied."
                          ""))))))
 
 (defun flymake-goto-prev-error (&optional n filter interactive)
-  "Go to Nth previous Flymake error in buffer matching FILTER.
-Interactively, always move to the previous error.  With a prefix
-arg, skip any diagnostics with a severity less than `:warning'.
+  "Go to Nth previous Flymake diagnostic that matches FILTER.
+Interactively, always move to the previous diagnostic.  With a
+prefix arg, skip any diagnostics with a severity less than
+`:warning'.
 
-If `flymake-wrap-around' is non-nil and no more previous errors,
-resumes search from bottom.
+If `flymake-wrap-around' is non-nil and no more previous
+diagnostics, resumes search from bottom.
 
 FILTER is a list of diagnostic types found in
 `flymake-diagnostic-types-alist', or nil, if no filter is to be
@@ -953,13 +954,13 @@ applied."
 ;;;
 (easy-menu-define flymake-menu flymake-mode-map "Flymake"
   `("Flymake"
-    [ "Go to next error"      flymake-goto-next-error t ]
-    [ "Go to previous error"  flymake-goto-prev-error t ]
-    [ "Check now"             flymake-start t ]
-    [ "Go to log buffer"      flymake-switch-to-log-buffer t ]
-    [ "Show error buffer"     flymake-show-diagnostics-buffer t ]
+    [ "Go to next problem"      flymake-goto-next-error t ]
+    [ "Go to previous problem"  flymake-goto-prev-error t ]
+    [ "Check now"               flymake-start t ]
+    [ "List all problems"       flymake-show-diagnostics-buffer t ]
     "--"
-    [ "Turn off Flymake"      flymake-mode t ]))
+    [ "Go to log buffer"        flymake-switch-to-log-buffer t ]
+    [ "Turn off Flymake"        flymake-mode t ]))
 
 (defvar flymake--mode-line-format `(:eval (flymake--mode-line-format)))