From db79902e548d8b166d6f3eb3ecd60fa46805e90c Mon Sep 17 00:00:00 2001
From: Gerard Vermeulen <gerard.vermeulen@neel.cnrs.fr>
Date: Sun, 11 Sep 2022 07:37:26 +0200
Subject: [PATCH] Add a section on `regexp-replace'

---
 README.org | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.org b/README.org
index 98dfab8..7d1fd13 100644
--- a/README.org
+++ b/README.org
@@ -1417,6 +1417,36 @@ previous input in the minibuffer. Listing
 :CUSTOM_ID: sec:search-replace
 :END:
 
+** [[info:emacs#Regexp Replace][Regexp Replace (info)]]
+:PROPERTIES:
+:CUSTOM_ID: sec:regexp-replace
+:END:
+
+Executing {{{kbd(M-x replace-regexp)}}} prompts fo a regular expression =REGEXP=
+and a substitution =NEWSTRING= to replace =REGEXP= with =NEWSTRING=.  The tools
+in section [[#sec:narrowing][Narrowing]] allow to limit the scope of {{{kbd(M-x replace-regexp)}}}.
+A list pointing to relevant documentation is:
+1. [[info:emacs#Regexp Replace][Regexp Replace (info)]] explains how the substitution handles references to
+   regular expression groups and lisp expressions.
+2. [[info:emacs#Regexps][Syntax of Regular Expressions (info)]] describes regular expression features
+   for users.
+3. [[info:elisp#Regular Expressions][Emacs Lisp Regular Expressions (info)]] describes regular expression features
+   for programmers.
+4. [[https://www.emacswiki.org/][Emacs Wiki]] has an article on [[https://www.emacswiki.org/emacs/ReplaceRegexpWithLispExpressions][replacing regexp with lisp expressions]].
+Table [[tab:replace-regexp-tranform]] tabulates how to perfom example tasks by means
+of {{{kbd(M-x replace-regexp)}}} using =(regular-expression transform)= pairs.
+
+#+attr_latex: :booktabs yes :float table
+#+caption[Example =replace-regexp= (regular-expression substitution) pairs]:
+#+caption: Example =replace-regexp= (regular-expression substitution) pairs.
+#+name: tab:replace-regexp-tranform
+| task                        | regular expression              | substitution  |
+|-----------------------------+---------------------------------+---------------|
+| move dot two digits forward | =0\.\([[:digit:]][[:digit:]]\)= | =0\1.=        |
+| move dot two digits forward | =0\.\([0-9][0-9]\)=             | =0\1.=        |
+| renumber grep/occur matches | =\(.+:\)=                       | =\,(1+ \#)._= |
+|-----------------------------+---------------------------------+---------------|
+
 ** [[https://github.com/Wilfred/deadgrep#readme][Deadgrep]]
 :PROPERTIES:
 :CUSTOM_ID: sec:deadgrep