[AUCTeX-devel] [elpa] externals/auctex 2888571 52/69: Allow ignoring certain warnings

[Tassilo Horn]

branch: externals/auctex
commit 28885717e4f75ecaab2c9018d4ba7713955778a4
Author: Mosè Giordano <address@hidden>
Commit: Mosè Giordano <address@hidden>

    Allow ignoring certain warnings
    
    * tex.el (TeX-ignore-warnings, TeX-suppress-ignored-warnings): New
      customizable options.
    (TeX-toggle-suppress-ignored-warnings): New function.
    (TeX-mode-map): Add key-binding for `TeX-toggle-suppress-ignored-warnings'.
    * tex-buf.el (TeX-error-list-skip-warning-p): Add new argument and use it.
    (TeX-parse-TeX): Provide additional argument to
    `TeX-error-list-skip-warning-p'.
    (TeX-error-list): Document new information.
    (TeX-find-display-help): Add new (ignored) argument.
    (TeX-error): Add new element to `TeX-error-list' entry.
    (TeX-warning): Set the "ignore" flag for `TeX-error-list'
    (TeX-error-overview-make-entries): Provide additional argument to
    `TeX-error-list-skip-warning-p'.
    (TeX-error-overview-toggle-debug-bad-boxes):
    (TeX-error-overview-toggle-debug-warnings): Determine
    `TeX-master-directory' in `TeX-command-buffer'.
    (TeX-error-overview-toggle-suppress-ignored-warnings): New function.
    (TeX-error-overview-mode-map): Add key-binding for
    `TeX-error-overview-toggle-suppress-ignored-warnings'.
    (TeX-error-overview-menu): Add entry for
    `TeX-error-overview-toggle-suppress-ignored-warnings'.
---
 doc/auctex.texi  |   76 ++++++++++++++++++++++++++++++--------
 doc/changes.texi |    8 ++++
 tex-buf.el       |  108 +++++++++++++++++++++++++++++++++++++++---------------
 tex.el           |   33 ++++++++++++++++
 4 files changed, 179 insertions(+), 46 deletions(-)

diff --git a/doc/auctex.texi b/doc/auctex.texi
index c8e35a3..d0d0673 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -190,6 +190,7 @@ Viewing the Formatted Output
 
 Catching the errors
 
+* Ignoring warnings::           Controlling warnings to be reported
 * Error overview::              List of all errors and warnings
 
 Customization and Extension
@@ -3337,36 +3338,76 @@ not parse the whole output log buffer and 
@code{TeX-previous-error}
 cannot be used.
 @end defopt
 
+As default, @AUCTeX{} will display a special help buffer containing the
+error reported by @TeX{} along with the documentation.  There is however
+an `expert' option, which allows you to display the real @TeX{} output.
+
address@hidden TeX-display-help
+If t @AUCTeX{} will automatically display a help text whenever an error
+is encountered using @code{TeX-next-error} (@kbd{C-c `}).  If nil a
+terse information about the error is displayed in the echo area.  If
address@hidden @AUCTeX{} will display the output buffer with the raw
address@hidden output.
address@hidden defopt
+
address@hidden
+* Ignoring warnings::         Controlling warnings to be reported
+* Error overview::            List of all errors and warnings
address@hidden menu
+
address@hidden Ignoring warnings
address@hidden Controlling warnings to be reported
+
 Normally @AUCTeX{} will only report real errors, but you may as well
 ask it to report `bad boxes' and warnings as well.
 
 @deffn Command TeX-toggle-debug-bad-boxes
 @kindex C-c C-t C-b
address@hidden TeX-debug-bad-boxes
 (@kbd{C-c C-t C-b}) Toggle whether @AUCTeX{} should stop at bad boxes
-(i.e. overfull and underfull boxes) as well as normal errors.
+(i.e. overfull and underfull boxes) as well as normal errors.  The
+boolean option @code{TeX-debug-bad-boxes} is set accordingly.
 @end deffn
 
 @deffn Command TeX-toggle-debug-warnings
 @kindex C-c C-t C-w
address@hidden TeX-debug-warnings
 (@kbd{C-c C-t C-w}) Toggle whether @AUCTeX{} should stop at warnings as
-well as normal errors.
+well as normal errors.  The boolean option @code{TeX-debug-warnings} is
+set accordingly.
 @end deffn
 
-As default, @AUCTeX{} will display a special help buffer containing the
-error reported by @TeX{} along with the documentation.  There is however
-an `expert' option, which allows you to display the real @TeX{} output.
+While many users desire to have warnings reported after compilation,
+there are certain warnings that are considered unimportant and users
+want to ignore them.  For a more fine-grained control of what kinds of
+warnings should be shown after compilation, @AUCTeX{} provides other
+options.
 
address@hidden TeX-display-help
-If t @AUCTeX{} will automatically display a help text whenever an error
-is encountered using @code{TeX-next-error} (@kbd{C-c `}).  If nil a
-terse information about the error is displayed in the echo area.  If
address@hidden @AUCTeX{} will display the output buffer with the raw
address@hidden output.
address@hidden TeX-ignore-warnings
+Controls which warnings are to be ignored.
+
+It can be a regexp matching the message of the warnings to be ignored.
+
+More advanced users can set also this option to a symbol with the name
+of a custom function taking as arguments all the information of the
+warning listed in @code{TeX-error-list} variable, except the last one
+about whether to ignore the warning.  See the code of @code{TeX-warning}
+function and the documentation of @code{TeX-error-list} for more
+details.
 @end defopt
 
address@hidden
-* Error overview::            List of all errors and warnings
address@hidden menu
address@hidden Command TeX-toggle-suppress-ignored-warnings
address@hidden C-c C-t C-x
address@hidden TeX-suppress-ignored-warnings
+(@kbd{C-c C-t C-x}) Toggle whether @AUCTeX{} should actually hide the
+ignored warnings specified with @code{TeX-ignore-warnings}.  The boolean
+option @code{TeX-suppress-ignored-warnings} is set accordingly.  If this
+is nil, all warnings are shown, even those matched by
address@hidden, otherwise these are hidden.
+
+Note that @code{TeX-debug-warnings} takes the precedence: if it is nil,
+all warnings are hidden in any case.
address@hidden deffn
 
 @node Error overview
 @subsection List of all errors and warnings
@@ -3385,8 +3426,11 @@ In this window you can visit the error on which point is 
on by pressing
 @key{p} respectively.  A prefix argument to these keys specifies how
 many errors to move forward or backward.  You can visit an error also by
 clicking on its message.  Jump to error point in the source code with
address@hidden, and use @key{l} see the error in the log buffer.  Press @key{q}
-to quit the overview.
address@hidden, and use @key{l} see the error in the log buffer.  In addition,
+you can toggle visibility of bad boxes, generic warnings, and ignored
+warnings with @key{b}, @key{w}, and @key{x}, respectively (see
address@hidden warnings} for details).  Press @key{q} to quit the
+overview.
 @end deffn
 
 @defopt TeX-error-overview-open-after-TeX-run
diff --git a/doc/changes.texi b/doc/changes.texi
index 8c5ff97..141f765 100644
--- a/doc/changes.texi
+++ b/doc/changes.texi
@@ -16,6 +16,14 @@ Parsing of the compilation log has been reworked.  You 
should encounter
 fewer mistaken files while navigating through errors and warnings.
 
 @item
+Two new user options, @code{TeX-ignore-warnings} and
address@hidden, allow ignoring certain warnings
+after compilation of the document.
address@hidden rawfile
address@hidden warnings}, for details.
address@hidden ifclear
+
address@hidden
 Added support for Atril viewer.  Forward and inverse search requires
 version 1.9.1 or later to work.
 
diff --git a/tex-buf.el b/tex-buf.el
index 39c35dc..d3c6098 100644
--- a/tex-buf.el
+++ b/tex-buf.el
@@ -2180,18 +2180,22 @@ If optional argument REPARSE is non-nil, reparse the 
output log."
             (process-name (TeX-active-process))
           "this")))
 
-(defun TeX-error-list-skip-warning-p (type)
+(defun TeX-error-list-skip-warning-p (type ignore)
   "Decide if a warning of `TeX-error-list' should be skipped.
 
-TYPE is one of the types listed in `TeX-error-list'."
+TYPE is one of the types listed in `TeX-error-list', IGNORE
+is the flag to choose if the warning should be skipped."
   ;; The warning should be skipped if it...
   (or
    ;; ...is a warning and we want to ignore all warnings, or...
    (and (null TeX-debug-warnings)
        (equal type 'warning))
-   ;; ...is a bad-box and we want to ignore all bad-boxes.
+   ;; ...is a bad-box and we want to ignore all bad-boxes, or...
    (and (null TeX-debug-bad-boxes)
-       (equal type 'bad-box))))
+       (equal type 'bad-box))
+   ;; ...is a warning to be ignored.
+   (and TeX-suppress-ignored-warnings
+       ignore)))
 
 (defun TeX-parse-TeX (arg reparse)
   "Find the next error produced by running TeX.
@@ -2215,7 +2219,9 @@ already in an Emacs buffer) and the cursor is placed at 
the error."
          (progn
            (setq arg (or arg 1)
                  max-index (length TeX-error-list))
-           ;; This loop is needed to skip ignored warnings.
+           ;; This loop is needed to skip ignored warnings, when
+           ;; `TeX-suppress-ignored-warnings' is non-nil and there are ignore
+           ;; warnings.
            (while (null (zerop arg))
              (setq TeX-error-last-visited (1+ TeX-error-last-visited)
                    item (if (natnump TeX-error-last-visited)
@@ -2224,7 +2230,7 @@ already in an Emacs buffer) and the cursor is placed at 
the error."
                           nil))
              ;; Increase or decrease `arg' only if the warning isn't to be
              ;; skipped.
-             (unless (TeX-error-list-skip-warning-p (nth 0 item))
+             (unless (TeX-error-list-skip-warning-p (nth 0 item) (nth 10 item))
                (setq arg (if (> arg 0)
                              (1- arg)
                            (1+ arg)))))
@@ -2251,6 +2257,10 @@ already in an Emacs buffer) and the cursor is placed at 
the error."
 You might want to examine and modify the free variables `file',
 `offset', `line', `string', `error', and `context' from this hook.")
 
+;; `ignore' flag should be the always the last one in the list of information
+;; for each error/warning, because it can be set within `TeX-warning' by a
+;; custom function taking as argument all information present in
+;; `TeX-error-list' but `ignore', see `TeX-ignore-warnings'.
 (defvar TeX-error-list nil
   "List of warnings and errors.
 
@@ -2259,13 +2269,15 @@ error or warning.  This is the structure of each 
element:
  *  0: type (error, warning, bad-box)
  *  1: file
  *  2: line
- *  3: error/warning text
+ *  3: message of the error or warning
  *  4: offset
  *  5: context
  *  6: string
- *  7: line-end
+ *  7: for warnings referring to multiple lines (e.g. bad boxes),
+       the last line mentioned in the warning message
  *  8: bad-box
  *  9: value of `TeX-error-point'
+ * 10: whether the warning should be ignored
 
 This variable is intended to be set only in output buffer so it
 will be shared among all files of the same document.")
@@ -2414,8 +2426,11 @@ Return non-nil if an error or warning is found."
     error-found))
 
 (defun TeX-find-display-help (type file line error offset context string
-                                  line-end bad-box error-point)
-  "Find the error and display the help."
+                                  line-end bad-box error-point _ignore)
+  "Find the error and display the help.
+
+For a description of arguments, see `TeX-error-list'.  IGNORE
+value is not used here."
   ;; Go back to TeX-buffer
   (let ((runbuf (TeX-active-buffer))
        (master (with-current-buffer TeX-command-buffer
@@ -2518,18 +2533,18 @@ information in `TeX-error-list' instead of displaying 
the error."
                                      context-start)))
         ;; We may use these in another buffer.
         (offset (or (car TeX-error-offset) 0))
-        (file (car TeX-error-file)))
+        (file (car TeX-error-file))
+        info-list)
 
     ;; Remember where we was.
-    (setq TeX-error-point (point))
+    (setq TeX-error-point (point)
+         info-list (list 'error file line error offset context string nil nil
+                         TeX-error-point nil))
     (if store
        ;; Store the error information.
-       (add-to-list 'TeX-error-list
-                    (list 'error file line error offset context string nil nil
-                          TeX-error-point) t)
+       (add-to-list 'TeX-error-list info-list t)
       ;; Find the error point and display the help.
-      (TeX-find-display-help
-       'error file line error offset context string nil nil TeX-error-point))))
+      (apply 'TeX-find-display-help info-list))))
 
 (defun TeX-warning (warning &optional store)
   "Display a warning for WARNING.
@@ -2587,7 +2602,8 @@ warning."
 
         ;; We might use these in another file.
         (offset (or (car TeX-error-offset) 0))
-        (file (car TeX-error-file)))
+        (file (car TeX-error-file))
+        info-list ignore)
 
     ;; Second chance to get line number right.  If `line' is nil, check whether
     ;; the reference to the line number is in `context'.  For example, this is
@@ -2604,16 +2620,31 @@ warning."
     (goto-char error-point)
     (setq TeX-error-point (point))
 
+    ;; Explanation of what follows: we add the warning to `TeX-error-list' even
+    ;; if it has to be ignored, with a flag specifying whether it is ignored.
+    ;; We do so in order to be able to change between "ignore" and 
"dont-ignore"
+    ;; behavior by just looking to the flag, without the need to reparse the
+    ;; output log.
+
+    ;; Store the list of information about the warning.
+    (setq info-list (list (if bad-box 'bad-box 'warning) file line warning
+                         offset context string line-end bad-box
+                         TeX-error-point)
+         ;; Decide whether it should be ignored.
+         ignore (and TeX-ignore-warnings
+                     (cond
+                      ((stringp TeX-ignore-warnings)
+                       (string-match TeX-ignore-warnings warning))
+                      ((fboundp TeX-ignore-warnings)
+                       (apply TeX-ignore-warnings info-list))))
+         ;; Update `info-list'.
+         info-list (append info-list (list ignore)))
+
     (if store
        ;; Store the warning information.
-       (add-to-list 'TeX-error-list
-                    (list (if bad-box 'bad-box 'warning) file line warning
-                          offset context string line-end bad-box
-                          TeX-error-point) t)
+       (add-to-list 'TeX-error-list info-list t)
       ;; Find the warning point and display the help.
-      (TeX-find-display-help (if bad-box 'bad-box 'warning) file line warning
-                            offset context string line-end bad-box
-                            TeX-error-point))))
+      (apply 'TeX-find-display-help info-list))))
 
 ;;; - Help
 
@@ -3245,7 +3276,7 @@ Write file names relative to MASTER-DIR when they are not 
absolute."
               line (nth 2 entry)
               msg  (nth 3 entry))
         ;; Add the entry only if it isn't to be skipped.
-        (unless (TeX-error-list-skip-warning-p type)
+        (unless (TeX-error-list-skip-warning-p type (nth 10 entry))
           (add-to-list
            'entries
            (list
@@ -3325,8 +3356,9 @@ forward, if negative)."
   "Run `TeX-toggle-debug-bad-boxes' and update entries list."
   (interactive)
   (TeX-toggle-debug-bad-boxes)
-  (setq tabulated-list-entries (TeX-error-overview-make-entries
-                               (TeX-master-directory)))
+  (setq tabulated-list-entries
+       (TeX-error-overview-make-entries
+        (with-current-buffer TeX-command-buffer (TeX-master-directory))))
   (tabulated-list-init-header)
   (tabulated-list-print))
 
@@ -3334,8 +3366,19 @@ forward, if negative)."
   "Run `TeX-toggle-debug-warnings' and update entries list."
   (interactive)
   (TeX-toggle-debug-warnings)
-  (setq tabulated-list-entries (TeX-error-overview-make-entries
-                               (TeX-master-directory)))
+  (setq tabulated-list-entries
+       (TeX-error-overview-make-entries
+        (with-current-buffer TeX-command-buffer (TeX-master-directory))))
+  (tabulated-list-init-header)
+  (tabulated-list-print))
+
+(defun TeX-error-overview-toggle-suppress-ignored-warnings ()
+  "Toggle visibility of ignored warnings and update entries list."
+  (interactive)
+  (TeX-toggle-suppress-ignored-warnings)
+  (setq tabulated-list-entries
+       (TeX-error-overview-make-entries
+        (with-current-buffer TeX-command-buffer (TeX-master-directory))))
   (tabulated-list-init-header)
   (tabulated-list-print))
 
@@ -3357,6 +3400,7 @@ forward, if negative)."
     (define-key map "p"    'TeX-error-overview-previous-error)
     (define-key map "q"    'TeX-error-overview-quit)
     (define-key map "w"    'TeX-error-overview-toggle-debug-warnings)
+    (define-key map "x"    
'TeX-error-overview-toggle-suppress-ignored-warnings)
     (define-key map "\C-m" 'TeX-error-overview-goto-source)
     map)
   "Local keymap for `TeX-error-overview-mode' buffers.")
@@ -3383,6 +3427,10 @@ forward, if negative)."
      ["Debug Warnings" TeX-error-overview-toggle-debug-warnings
       :style toggle :selected TeX-debug-warnings
       :help "Show warnings"]
+     ["Ignore Unimportant Warnings"
+      TeX-error-overview-toggle-suppress-ignored-warnings
+      :style toggle :selected TeX-suppress-ignored-warnings
+      :help "Hide specified warnings"]
      "-"
      ["Quit" TeX-error-overview-quit
       :help "Quit"])))
diff --git a/tex.el b/tex.el
index 76aaeca..c87e539 100644
--- a/tex.el
+++ b/tex.el
@@ -958,6 +958,28 @@ echo area.  If `expert' display output buffer with raw 
processor output."
   :group 'TeX-output
   :type 'boolean)
 
+(defcustom TeX-ignore-warnings nil
+  "Controls which warnings are to be ignored.
+
+It can be either a regexp matching warnings to be ignored, or a
+symbol with the name of a custom function taking as arguments all
+the information of the warning listed in `TeX-error-list', except
+the last one about whether to ignore the warning.
+
+If you want to use the custom function, see how it is used in the
+code of `TeX-warning'."
+  :group 'TeX-command
+  :type '(choice (const  :tag "Do not ignore anything" nil)
+                (string :tag "Regexp")
+                (symbol :tag "Function name")))
+
+(defcustom TeX-suppress-ignored-warnings nil
+  "Whether to actually show ignored warnings.
+
+Note that `TeX-debug-warnings' always takes the precedence."
+  :group 'TeX-command
+  :type 'boolean)
+
 (defun TeX-toggle-debug-bad-boxes ()
   "Toggle if the debugger should display \"bad boxes\" too."
   (interactive)
@@ -972,6 +994,16 @@ echo area.  If `expert' display output buffer with raw 
processor output."
   (message (concat "TeX-debug-warnings: "
                   (if TeX-debug-warnings "on" "off"))))
 
+(defun TeX-toggle-suppress-ignored-warnings ()
+  "Toggle if the debugger should display ignored warnings too.
+
+See `TeX-suppress-ignored-warnings' and `TeX-ignore-warnings' for
+more details."
+  (interactive)
+  (setq TeX-suppress-ignored-warnings (not TeX-suppress-ignored-warnings))
+  (message (concat "TeX-suppress-ignored-warnings: "
+                  (if TeX-suppress-ignored-warnings "on" "off"))))
+
 ;;; Mode names.
 
 (defvar TeX-base-mode-name nil
@@ -4812,6 +4844,7 @@ Brace insertion is only done if point is in a math 
construct and
     (define-key map "\C-c\C-w"       'TeX-toggle-debug-bad-boxes); to be 
removed
     (define-key map "\C-c\C-t\C-b"   'TeX-toggle-debug-bad-boxes)
     (define-key map "\C-c\C-t\C-w"   'TeX-toggle-debug-warnings)
+    (define-key map "\C-c\C-t\C-x"   'TeX-toggle-suppress-ignored-warnings)
     (define-key map "\C-c\C-v" 'TeX-view)
     ;; From tex-buf.el
     (define-key map "\C-c\C-d" 'TeX-save-document)