[Emacs-diffs] scratch/flymake-refactor 3b6c736 12/12: Start rewriting flymake manual

[João Távora]

branch: scratch/flymake-refactor
commit 3b6c7360c0f98c0b5728534d6bc361c321d1c953
Author: João Távora <address@hidden>
Commit: João Távora <address@hidden>

    Start rewriting flymake manual
    
    * doc/misc/flymake.texi (Overview of Flymake): Rewrite a bit.
    (Installing Flymake): Delete most of this.
    (Running the syntax check): Mention flymake-start.
    (Navigating to error lines): Rewrite.
    (Viewing error messages): Commente out.
    (Syntax check statuses, Troubleshooting): Rewrite a bit.
    (Customizable variables): New section under "Using
    Flymake".  Don't mention any proc variables here.
    (Configuring Flymake): Delete
    (Proc backend): New chapter
    (Proc customization variables): New chapter.
---
 doc/misc/flymake.texi | 268 +++++++++++++++++++++++++-------------------------
 1 file changed, 132 insertions(+), 136 deletions(-)

diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 1bc416f..a1abf04 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -4,7 +4,7 @@
 @set VERSION 0.3
 @set UPDATED April 2004
 @settitle GNU Flymake @value{VERSION}
address@hidden docstyle.texi
address@hidden ../emacs/docstyle.texi
 @syncodeindex pg cp
 @comment %**end of header
 
@@ -53,7 +53,8 @@ modify this GNU manual.''
 * Overview of Flymake::
 * Installing Flymake::
 * Using Flymake::
-* Configuring Flymake::
+* Extending Flymake::
+* Proc backend::
 * Flymake Implementation::
 * GNU Free Documentation License::
 * Index::
@@ -63,29 +64,28 @@ modify this GNU manual.''
 @chapter Overview
 @cindex Overview of Flymake
 
-Flymake is a universal on-the-fly syntax checker implemented as an
-Emacs minor mode.  Flymake runs the pre-configured syntax check tool
-(compiler for C++ files, @code{perl} for perl files, etc.)@: in the
-background, passing it a temporary copy of the current buffer, and
-parses the output for known error/warning message patterns.  Flymake
-then highlights erroneous lines (i.e., lines for which at least one
-error or warning has been reported by the syntax check tool), and
-displays an overall buffer status in the mode line.  Status information
-displayed by Flymake contains total number of errors and warnings
-reported for the buffer during the last syntax check.
+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 @emph{backend}.
+
+Historically, Flymake used to accept a diagnostics from a single
+backend (albeit a very flexible one) which selected a syntax check
+tool from a preconfigured list (compiler for C++ files, @code{perl}
+for perl files, etc.)@: and executed it in the background, passing it
+a temporary copy of the current buffer, and parses the output for
+known error/warning message patterns. This backend is still available
+as a fallback and a default(@pxref{Proc backend}).
+
+Flymake annotates the buffer by highlighting erroneous lines or
+regions and displays an overall buffer status in the mode line.
+Status information displayed by Flymake contains totals for different
+types of diagnostics.
 
 @code{flymake-goto-next-error} and @code{flymake-goto-prev-error}
 functions allow for easy navigation to the next/previous erroneous
-line, respectively.
-
-Calling @code{flymake-display-err-menu-for-current-line} will popup a
-menu containing error messages reported by the syntax check tool for
-the current line.  Errors/warnings belonging to another file, such as a
address@hidden header file included by a @code{.c} file, are shown in the
-current buffer as belonging to the first line.  Menu items for such
-messages also contain a filename and a line number.  Selecting such a
-menu item will automatically open the file and jump to the line with
-error.
+line, respectively. When @code{flymake-mode} is active, they are
+mapped to @kbd{M-n} and @kbd{M-p}, respectively, and by default.
 
 Syntax check is done ``on-the-fly''.  It is started whenever
 
@@ -97,33 +97,15 @@ delay is configurable).
 @end itemize
 
 Flymake is a universal syntax checker in the sense that it's easily
-extended to support new syntax check tools and error message
-patterns.  @xref{Configuring Flymake}.
+extended to support new backends.  @xref{Customizable variables}.
 
 @node Installing Flymake
 @chapter Installing
 @cindex Installing Flymake
 
-
-Flymake is packaged in a single file, @code{flymake.el}.
-
-To install/update Flymake, place @code{flymake.el} to a directory
-somewhere on Emacs load path.  You might also want to byte-compile
address@hidden to improve performance.
-
-Also, place the following line in the @code{.emacs} file.
-
address@hidden
-(require 'flymake)
address@hidden lisp
-
-You might also map the most frequently used Flymake functions, such as
address@hidden, to some keyboard shortcuts:
-
address@hidden
-(global-set-key [f3] 'flymake-display-err-menu-for-current-line)
-(global-set-key [f4] 'flymake-goto-next-error)
address@hidden lisp
+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.
 
 @node Using Flymake
 @chapter Using Flymake
@@ -132,10 +114,10 @@ You might also map the most frequently used Flymake 
functions, such as
 @menu
 * Flymake mode::
 * Running the syntax check::
-* Navigating to error lines::
-* Viewing error messages::
+* Navigating to error lines::   @c * Viewing error messages::
 * Syntax check statuses::
 * Troubleshooting::
+* Customizable variables::
 @end menu
 
 @node Flymake mode
@@ -161,10 +143,9 @@ line in @code{.emacs}:
 
 When @code{flymake-mode} is active, syntax check is started
 automatically on any of the three conditions mentioned above.  Syntax
-check can also be started manually by using the
address@hidden function.  This
-can be used, for example, when changes were made to some other buffer
-affecting the current buffer.
+check can also be started manually by using the @code{flymake-start}
+function.  This can be used, for example, when changes were made to
+some other buffer affecting the current buffer.
 
 @node Navigating to error lines
 @section Navigating to error lines
@@ -185,21 +166,24 @@ navigate the highlighted lines.
 
 @end multitable
 
-These functions treat erroneous lines as a linked list.  Therefore,
address@hidden will go to the first erroneous line
-when invoked in the end of the buffer.
-
address@hidden Viewing error messages
address@hidden Viewing error messages
address@hidden Viewing error messages
-
-To view error messages belonging to the current line, use the
address@hidden function.  If there's
-at least one error or warning reported for the current line, this
-function will display a popup menu with error/warning texts.
-Selecting the menu item whose error belongs to another file brings
-forward that file with the help of the
address@hidden function.
+If the user options @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.
+
address@hidden address@hidden/09/27: The latest redesign more than likely broke 
this.
address@hidden
address@hidden @node Viewing error messages
address@hidden @section Viewing error messages
address@hidden @cindex Viewing error messages
+
address@hidden To view error messages belonging to the current line, use the
address@hidden @code{flymake-display-err-menu-for-current-line} function.  If 
there's
address@hidden at least one error or warning reported for the current line, this
address@hidden function will display a popup menu with error/warning texts.
address@hidden Selecting the menu item whose error belongs to another file 
brings
address@hidden forward that file with the help of the
address@hidden @code{flymake-goto-file-and-line} function.
 
 @node Syntax check statuses
 @section Syntax check statuses
@@ -209,29 +193,22 @@ After syntax check is finished, its status is displayed 
in the mode line.
 The following statuses are defined.
 
 @multitable @columnfractions 0.25 0.75
address@hidden Flymake* or Flymake:E/W*
address@hidden  Flymake is currently running.  For the second case, E/W 
contains the
-error and warning count for the previous run.
address@hidden Flymake:run
address@hidden  Flymake is currently running at least one backend.
 
 @item Flymake
address@hidden  Syntax check is not running.  Usually this means syntax check 
was
-successfully passed (no errors, no warnings).  Other possibilities are:
-syntax check was killed as a result of executing
address@hidden, or syntax check cannot start as compilation
-is currently in progress.
-
address@hidden Flymake:E/W
address@hidden  Number of errors/warnings found by the syntax check process.
address@hidden Flymake was unable to successfully execute any backend.
 
address@hidden Flymake:!
address@hidden  Flymake was unable to find master file for the current buffer.
address@hidden Flymake [<errors> <warnings> ... ]
address@hidden  Normal operation, number of errors/warnings found by the syntax 
check process.
 @end multitable
 
-The following errors cause a warning message and switch flymake mode
-OFF for the buffer.
+The default backend @code{flymake-proc-legacy-flymake} may encounter
+some situations that cause a warning message to the @code{*Flymake
+log*} buffer.
 
 @multitable @columnfractions 0.25 0.75
address@hidden CFGERR
address@hidden @code{:configuration-error}
 @tab  Syntax check process returned nonzero exit code, but no
 errors/warnings were reported.  This indicates a possible configuration
 error (for example, no suitable error message patterns for the
@@ -243,10 +220,11 @@ syntax check tool).
 @item NOMK
 @tab  Flymake was unable to find a suitable buildfile for the current buffer.
 
address@hidden PROCERR
address@hidden @code{:make-process-error}
 @tab  Flymake was unable to launch a syntax check process.
 @end multitable
 
+These ``panic'' situations cause the backend to be disabled.
 
 @node Troubleshooting
 @section Troubleshooting
@@ -255,97 +233,115 @@ syntax check tool).
 
 Flymake uses a simple logging facility for indicating important points
 in the control flow.  The logging facility sends logging messages to
-the @file{*Messages*} buffer.  The information logged can be used for
+the @file{*Flymake log*} buffer.  The information logged can be used for
 resolving various problems related to Flymake.
 
-Logging output is controlled by the @code{flymake-log-level}
-variable.  @code{3} is the  most verbose level, and @code{-1} switches
-logging off.
+Logging output is controlled by the Emacs @code{warning-minimum-log-level}
+and @code{warning-minimum-level} variables.
+
address@hidden Customizable variables
address@hidden Customizable variables
address@hidden Customizable variables
+
+This section summarizes variables used for the configuration of the
+Flymake user interface.
+
address@hidden @code
address@hidden flymake-no-changes-timeout
+If any changes are made to the buffer, syntax check is automatically
+started after @code{flymake-no-changes-timeout} seconds.
+
address@hidden flymake-start-syntax-check-on-newline
+A boolean flag indicating whether to start syntax check after a
+newline character is added to the buffer.
+
address@hidden flymake-error
+A custom face for highlighting regions for which an error has been
+reported.
+
address@hidden flymake-warning
+A custom face for highlighting regions for which a warning has been
+reported.
+
address@hidden flymake-note
+A custom face for highlighting regions for which a note has been
+reported.
+
address@hidden flymake-error-bitmap
+A bitmap used in the fringe to mark lines for which an error has
+been reported.
+
address@hidden flymake-warning-bitmap
+A bitmap used in the fringe to mark lines for which a warning has
+been reported.
+
address@hidden flymake-fringe-indicator-position
+Which fringe (if any) should show the warning/error bitmaps.
+
address@hidden flymake-wrap-around
+If non-nil, moving to errors with @code{flymake-goto-next-error} and
address@hidden wraps around buffer boundaries.
+
address@hidden table
+
address@hidden Extending Flymake
address@hidden Extending Flymake
address@hidden Extending Flymake
 
address@hidden Configuring Flymake
address@hidden Configuring and Extending Flymake
address@hidden Configuring and Extending Flymake
address@hidden Proc backend
address@hidden The legacy ``Proc'' backend
address@hidden Proc backend
 
 @menu
-* Customizable variables::
+* Proc customization variables::
 * Adding support for a new syntax check tool::
 @end menu
 
-Flymake was designed to be easily extended for supporting new syntax
-check tools and error message patterns.
-
address@hidden Customizable variables
address@hidden Customizable variables
address@hidden Customizable variables
+The backend @code{flymake-proc-legacy-backend} was originally designed
+to be extended for supporting new syntax check tools and error message
+patterns. It is also controlled by its own set of customization variables
 
-This section summarizes variables used for Flymake
-configuration.
address@hidden Proc customization variables
address@hidden Customization variables for the Proc backend
address@hidden Proc customization variables
 
 @table @code
address@hidden flymake-log-level
address@hidden flymake-proc-log-level
 Controls logging output, see @ref{Troubleshooting}.
 
address@hidden flymake-allowed-file-name-masks
address@hidden flymake-proc-allowed-file-name-masks
 A list of @code{(filename-regexp, init-function, cleanup-function
 getfname-function)} for configuring syntax check tools.  @xref{Adding
 support for a new syntax check tool}.
 
 @ignore
address@hidden flymake-buildfile-dirs
address@hidden flymake-proc-buildfile-dirs
 A list of directories (relative paths) for searching a
 buildfile.  @xref{Locating the buildfile}.
 @end ignore
 
address@hidden flymake-master-file-dirs
address@hidden flymake-proc-master-file-dirs
 A list of directories for searching a master file.  @xref{Locating a
 master file}.
 
address@hidden flymake-get-project-include-dirs-function
address@hidden flymake-proc-get-project-include-dirs-function
 A function used for obtaining a list of project include dirs (C/C++
 specific).  @xref{Getting the include directories}.
 
address@hidden flymake-master-file-count-limit
address@hidden flymake-check-file-limit
address@hidden flymake-proc-master-file-count-limit
address@hidden flymake-proc-check-file-limit
 Used when looking for a master file.  @xref{Locating a master file}.
 
address@hidden flymake-err-line-patterns
address@hidden flymake-proc-err-line-patterns
 Patterns for error/warning messages in the form @code{(regexp file-idx
 line-idx col-idx err-text-idx)}.  @xref{Parsing the output}.
 
address@hidden flymake-warning-predicate
address@hidden flymake-proc-warning-predicate
 Predicate to classify error text as warning. @xref{Parsing the output}.
 
address@hidden flymake-compilation-prevents-syntax-check
address@hidden flymake-proc-compilation-prevents-syntax-check
 A flag indicating whether compilation and syntax check of the same
 file cannot be run simultaneously.
-
address@hidden flymake-no-changes-timeout
-If any changes are made to the buffer, syntax check is automatically
-started after @code{flymake-no-changes-timeout} seconds.
-
address@hidden flymake-start-syntax-check-on-newline
-A boolean flag indicating whether to start syntax check after a
-newline character is added to the buffer.
-
address@hidden flymake-errline
-A custom face for highlighting lines for which at least one error has
-been reported.
-
address@hidden flymake-warnline
-A custom face for highlighting lines for which at least one warning
-and no errors have been reported.
-
address@hidden flymake-error-bitmap
-A bitmap used in the fringe to mark lines for which an error has
-been reported.
-
address@hidden flymake-warning-bitmap
-A bitmap used in the fringe to mark lines for which a warning has
-been reported.
-
address@hidden flymake-fringe-indicator-position
-Which fringe (if any) should show the warning/error bitmaps.
-
 @end table
 
 @node Adding support for a new syntax check tool