Obsolete Flymake's flymake-diagnostic-types-alist

That varaiable was an association between symbols and properties,
effecively duplicating symbol's property lists.  It is simpler to just
put properties on symbols.  Backward compatibility to the old variable
has been kept.

* doc/misc/flymake.texi (Flymake error types): Don't mention
flymake-diagnostic-types-alist.
(Flymake error types): Rework section.
(Backend functions): Refill a paragraph.
(Flymake utility functions): Don't mention
flymake-diagnostic-types-alist.
(Proc customization variables): Don't mention
flymake-diagnostic-types-alist.

* etc/NEWS: Mention obsoletion of flymake-diagnostic-types-alist.

* lisp/progmodes/flymake-proc.el
(flymake-proc--diagnostics-for-pattern): Don't use
flymake-diagnostic-types-alist.

* lisp/progmodes/flymake.el: Rewrite commentary.
(flymake-make-diagnostic, flymake-mode, flymake-goto-next-error)
(flymake-goto-prev-error): Don't mention
flymake-diagnostic-types-alist in docstring.
(flymake-diagnostic-types-alist): Make obsolete.
(:error, :warning, :note): Put flymake-category in these symbols.
(flymake-error, flymake-warning, flymake-note): Put
`flymake-bitmap', not `bitmap' in these symbols.
(flymake--lookup-type-property, flymake--highlight-line): Rewrite.
Honor flymake-diagnostic-types-alist for backward
compatibility.

* lisp/progmodes/python.el (python-flymake-msg-alist): Don't
mention flymake-diagnostic-types-alist.

1 files changed, 75 insertions, 75 deletions

diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 9260f4f22ba..e7f4da75bb9 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -275,54 +275,61 @@ The following sections discuss each approach in detail.
 @cindex customizing error types
 @cindex error types, customization
 
-@vindex flymake-diagnostic-types-alist
-The variable @code{flymake-diagnostic-types-alist} is looked up by
-Flymake every time an annotation for a diagnostic is created in the
-buffer.  Specifically, this variable holds a table of correspondence
-between symbols designating diagnostic types and an additional
-sub-table of properties pertaining to each diagnostic type.
-
-Both tables are laid out in association list (@pxref{Association
-Lists,,, elisp, The Emacs Lisp Reference Manual}) format, and thus can
-be conveniently accessed with the functions of the @code{assoc}
-family.
-
-You can use any symbol-value association in the properties sub-table,
-but some symbols have special meaning as to where and how Flymake
-presents the diagnostic:
+To customize the appearance of error types, set properties on the
+symbols associated with each diagnostic type.  The standard diagnostic
+symbols are @code{:error}, @code{:warning} and @code{:note} (though
+the backend may define more, @pxref{Backend functions}).
+
+The following properties can be set:
 
 @itemize
 
 @item
 @cindex bitmap of diagnostic
-@code{bitmap}, an image displayed in the fringe according to
+@code{flymake-bitmap}, an image displayed in the fringe according to
 @code{flymake-fringe-indicator-position}.  The value actually follows
 the syntax of @code{flymake-error-bitmap} (@pxref{Customizable
 variables}).  It is overridden by any @code{before-string} overlay
 property.
 
 @item
-@cindex severity of diagnostic
-@code{severity} is a non-negative integer specifying the diagnostic's
-severity.  The higher the value, the more serious is the error.  If
-the overlay property @code{priority} is not specified, @code{severity}
-is used to set it and help sort overlapping overlays.
+@code{flymake-overlay-control}, an alist ((@var{OVPROP} . @var{VALUE})
+@var{...}) of further properties used to affect the appearance of
+Flymake annotations.  With the exception of @code{category} and
+@code{evaporate}, these properties are applied directly to the created
+overlay (@pxref{Overlay Properties,,, elisp, The Emacs Lisp Reference
+Manual}).
 
-@item
-Every property pertaining to overlays (@pxref{Overlay Properties,,,
-elisp, The Emacs Lisp Reference Manual}), except @code{category} and
-@code{evaporate}.  These properties are used to affect the appearance
-of Flymake annotations.
+As an example, here's how to make diagnostics of the type @code{:note}
+stand out more prominently:
 
-As an example, here's how to make errors (diagnostics of the type
-@code{:error}) stand out even more prominently in the buffer, by
-raising the characters using a @code{display} overlay property.
+@example
+(push '(face . highlight) (get :note 'flymake-overlay-control))
+@end example
+
+If you push another alist entry in front, it overrides the previous
+one.  So this effectively removes the face from @code{:note}
+diagnostics:
 
 @example
-(push '(display . (raise 1.2))
-      (cdr (assoc :error flymake-diagnostic-types-alist)))
+(push '(face . nil) (get :note 'flymake-overlay-control))
 @end example
 
+To restore the original look for @code{:note} types, empty or remove
+its @code{flymake-overlay-control} property:
+
+@example
+(put :note 'flymake-overlay-control '())
+@end example
+
+@item
+@cindex severity of diagnostic
+@code{flymake-severity} is a non-negative integer specifying the
+diagnostic's severity.  The higher the value, the more serious is the
+error.  If the overlay property @code{priority} is not specified in
+@code{flymake-overlay-control}, @code{flymake-severity} is used to set
+it and help sort overlapping overlays.
+
 @item
 @vindex flymake-category
 @code{flymake-category} is a symbol whose property list is considered
@@ -333,32 +340,29 @@ the default for missing values of any other properties.
 @vindex flymake-error
 @vindex flymake-warning
 @vindex flymake-note
-Three default diagnostic types, @code{:error}, @code{:warning} and
-@code{:note} are predefined in
-@code{flymake-diagnostic-types-alist}.  By default each lists a single
+Three default diagnostic types are predefined: @code{:error},
+@code{:warning}, and @code{:note}.  By default, each one of them has a
 @code{flymake-category} property whose value is, respectively, the
-symbols @code{flymake-error}, @code{flymake-warning} and
+category symbol @code{flymake-error}, @code{flymake-warning} and
 @code{flymake-note}.
 
-These category symbols' plists is where the values of customizable
-variables and faces such as @code{flymake-error-bitmap} are found.
-Thus, if you change their plists, Flymake may stop honoring these
-user customizations.
+These category symbols' plist is where the values of customizable
+variables and faces (such as @code{flymake-error-bitmap}) are found.
+Thus, if you change their plists, Flymake may stop honoring these user
+customizations.
 
-The @code{flymake-category} special property is also especially useful
-for backends which create diagnostics objects with non-default
-types that differ from an existing type by only a few properties
-(@pxref{Flymake utility functions}).
+The @code{flymake-category} special property is especially useful for
+backends which create diagnostics objects with non-default types that
+differ from an existing type by only a few properties (@pxref{Flymake
+utility functions}).
 
 As an example, consider configuring a new diagnostic type
-@code{:low-priority-note} that behaves much like the @code{:note}
-priority but without an overlay face.
+@code{:low-priority-note} that behaves much like @code{:note}, but
+without an overlay face.
 
 @example
-(add-to-list
- 'flymake-diagnostic-types-alist
- `(:low-priority-note . ((face . nil)
-                         (flymake-category . flymake-note))))
+(put :low-priority-note 'flymake-overlay-control '((face . nil)))
+(put :low-priority-note 'flymake-category 'flymake-note)
 @end example
 
 @vindex flymake-diagnostics
@@ -389,20 +393,17 @@ Internet search for the text of a @code{:warning} or @code{:error}.
     (eww-browse-url
        (concat
         "https://duckduckgo.com/?q="
-        (replace-regexp-in-string " "
-                                  "+"
-                                  (flymake-diagnostic-text topmost-diag)))
+        (replace-regexp-in-string
+          " " "+" (flymake-diagnostic-text topmost-diag)))
        t)))
 
 (dolist (type '(:warning :error))
-  (let ((a (assoc type flymake-diagnostic-types-alist)))
-    (setf (cdr a)
-          (append `((mouse-face . highlight)
-                    (keymap . ,(let ((map (make-sparse-keymap)))
-                                 (define-key map [mouse-2]
-                                   'my-search-for-message)
-                                 map)))
-                  (cdr a)))))
+  (push '(mouse-face . highlight) (get type 'flymake-overlay-control))
+  (push `(keymap . ,(let ((map (make-sparse-keymap)))
+                      (define-key map [mouse-2]
+                        'my-search-for-message)
+                      map))
+        (get type 'flymake-overlay-control)))
 @end example
 
 @node Backend functions
@@ -436,10 +437,10 @@ the first argument is always @var{report-fn}, a callback function
 detailed below;
 
 @item
-the remaining arguments are keyword-value pairs of the
-form @w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}.  Currently,
-Flymake provides no such arguments, but backend functions must be
-prepared to accept (and possibly ignore) any number of them.
+the remaining arguments are keyword-value pairs of the form
+@w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}.
+Currently, Flymake provides no such arguments, but backend functions
+must be prepared to accept (and possibly ignore) any number of them.
 @end itemize
 
 Whenever Flymake or the user decide to re-check the buffer, backend
@@ -512,9 +513,9 @@ by calling the function @code{flymake-make-diagnostic}.
 
 @deffn Function flymake-make-diagnostic buffer beg end type text
 Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to
-@var{end}.  @var{type} is a key to
-@code{flymake-diagnostic-types-alist} and @var{text} is a description
-of the problem detected in this region.
+@var{end}.  @var{type} is a diagnostic symbol (@pxref{Flymake error
+types}), and @var{text} is a description of the problem detected in
+this region.
 @end deffn
 
 @cindex access diagnostic object
@@ -715,14 +716,13 @@ Patterns for error/warning messages in the form @code{(regexp file-idx
 line-idx col-idx err-text-idx)}.  @xref{Parsing the output}.
 
 @item flymake-proc-diagnostic-type-pred
-A function to classify a diagnostic text as particular type of
-error.  Should be a function taking an error text and returning one of
-the symbols indexing @code{flymake-diagnostic-types-alist}.  If non-nil
-is returned but there is no such symbol in that table, a warning is
-assumed.  If nil is returned, an error is assumed.  Can also be a
-regular expression that should match only warnings.  This variable
-replaces the old @code{flymake-warning-re} and
-@code{flymake-warning-predicate}.
+A function to classify a diagnostic text as particular type of error.
+Should be a function taking an error text and returning a diagnostic
+symbol (@pxref{Flymake error types}).  If non-nil is returned but
+there is no such symbol in that table, a warning is assumed.  If nil
+is returned, an error is assumed.  Can also be a regular expression
+that should match only warnings.  This variable replaces the old
+@code{flymake-warning-re} and @code{flymake-warning-predicate}.
 
 @item flymake-proc-compilation-prevents-syntax-check
 A flag indicating whether compilation and syntax check of the same