Improve 'compilation-transform-file-match-alist' documentation

* doc/emacs/building.texi (Compilation Mode): Document
'compilation-transform-file-match-alist'.
* lisp/progmodes/compile.el
(compilation-transform-file-match-alist):
Expand docstring and add some examples.

(cherry picked from commit 7c50e4cc8cc19ad1ab10121ece894409a72a8af9)

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index a135991c74974ad9c1233a718ffb672f08bfeaf8..d25213ad7931058d3275299a0e47540ae85632c6 100644 (file)
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -310,6 +310,14 @@ error message formats and tells Emacs how to extract the locus from
 each.  A similar variable, @code{grep-regexp-alist}, tells Emacs how
 to parse output from a @code{grep} command (@pxref{Grep Searching}).
 
+@vindex compilation-transform-file-match-alist
+@cindex compilation transform file
+@cindex compilation find file
+  Sometimes @code{compilation-error-regexp-alist} doesn't correctly
+determine the filename that is the source of the error.  Use user option
+@code{compilation-transform-file-match-alist} to make any necessary
+adjustments, such as adding or changing a directory component.
+
 @findex compilation-next-error
 @findex compilation-previous-error
 @findex compilation-next-file

diff --git a/lisp/progmodes/compile.el b/lisp/progmodes/compile.el
index 659b89971bbf2327aafe6d043638edb897465161..7a11cfd453bf1c0e2efc796b2c8317a9368db887 100644 (file)
--- a/lisp/progmodes/compile.el
+++ b/lisp/progmodes/compile.el
@@ -62,9 +62,21 @@ If nil, use Emacs default."
 (defcustom compilation-transform-file-match-alist
   '(("/bin/[a-z]*sh\\'" nil))
   "Alist of regexp/replacements to alter file names in compilation errors.
-If the replacement is nil, the file will not be considered an
-error after all.  If not nil, it should be a regexp replacement
-string."
+If the replacement is nil, the file will not be considered an error
+after all.  If not nil, it should be a regexp replacement string.
+
+When a replacement regexp is specified, the value of the file name used
+to locate the error is changed, but the compilation buffer still
+displays the original value.
+
+For example, to prepend a subdirectory \"bar/\" to all file names, add
+an entry matching \"\\\\=`\" and a replacement regexp of \"bar/\", i.e.:
+
+    (\"\\\\=`\" \"bar/\")
+
+Similarly, to remove a prefix \"bar/\", use:
+
+    (\"\\\\=`bar/\" \"\")"
   :type '(repeat (list regexp (choice (const :tag "No replacement" nil)
                                       string)))
   :version "27.1")