emacs-30 7c50e4cc8cc 2/2: Improve 'compilation-transform-file-match-alist' documentation

[Robert Pluim]

branch: emacs-30
commit 7c50e4cc8cc19ad1ab10121ece894409a72a8af9
Author: Robert Pluim <rpluim@gmail.com>
Commit: Robert Pluim <rpluim@gmail.com>

    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.
---
 doc/emacs/building.texi   |  8 ++++++++
 lisp/progmodes/compile.el | 18 +++++++++++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index bb03d8cf325..3a3dd1d4461 100644
--- 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 95dce7a430f..ee7fc6aaecb 100644
--- 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")