From 413978727c9fb1d26b64e81412434064d99ec568 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Thu, 12 Oct 2017 12:11:26 +0100 Subject: [PATCH] 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 d89a555ff73..05d879d8f4b 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 -@node Overview of Flymake -@chapter Overview +@node Using Flymake +@chapter Using Flymake @cindex overview of flymake +@cindex 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 +@code{flymake-mode} 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. - -@code{flymake-goto-next-error} 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. -@lisp -(define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error) -(define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error) -@end 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 -@code{flymake-start-on-flymake-mode} is nil. +@code{flymake-start-on-flymake-mode} is nil; @item a newline character is added to the buffer, unless -@code{flymake-start-syntax-check-on-newline} is nil. +@code{flymake-start-syntax-check-on-newline} 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. + +@code{flymake-goto-next-error} 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: + +@lisp +(define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error) +(define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error) +@end 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. -@node Installing Flymake -@chapter Installing -@cindex installing flymake - -Flymake is included with Emacs and its main commands, like -@code{flymake-mode}, are autoloaded. This means there is usually -nothing to do by way of installation. - -@node Using Flymake -@chapter Using Flymake -@cindex 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 -@node Flymake mode -@section Flymake mode -@cindex flymake-mode -@cindex activating flymake-mode - -Flymake is an Emacs minor mode. To use Flymake, you -must first activate @code{flymake-mode} by using the command -@kbd{flymake-mode}. - -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}: - -@lisp -(add-hook 'find-file-hook 'flymake-find-file-hook) -@end lisp - -@node Running the syntax check -@section Running the syntax check -@cindex manually starting syntax check -@cindex syntax check, start manually - -@findex flymake-start -When @code{flymake-mode} is active, syntax check is started -automatically on any of the three conditions mentioned in -@ref{Overview of Flymake}. Syntax check can also be started manually -by typing the @kbd{M-x flymake-start @key{RET}} command. - -@node Navigating to error lines -@section Navigating to error lines -@cindex 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: - -@table @code -@findex flymake-goto-next-error -@item flymake-goto-next-error -Moves point to the next erroneous line, if any. - -@findex flymake-goto-prev-error -@item flymake-goto-prev-error -Moves point to the previous erroneous line. -@end 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 +@item [@var{nerrors} @var{nwarnings} ...] +@tab 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} -@tab Some flymake backends haven't reported since the last time they -where questioned. +@tab 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{!} -@tab 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. +@tab 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{?} -@tab There are no configured Flymake backends in -@code{flymake-diagnostic-functions}. +@tab 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}). -@item @emph{[nerrors nwarnings]} -@tab 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 e4c6a38a77e..8c9c4b211a2 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))) -- 2.39.5