bug#12655: 24.2; Cannot discover automatic-all or other multi-buffer replacement commands

bug#12655: 24.2; Cannot discover automatic-all or other multi-buffer replacement commands

[Reuben Thomas]

While investigating a problem, I happened to notice a ChangeLog entry
referring to multi-query-replace-map, which led me to the automatic-all
function, which happens to be something I had regularly felt the lack
of.

I was able to find a reference to it in the NEWS for Emacs 23.1, but
that again was at the Lisp level; nowhere can I find user documentation
for this handy feature. In particular, C-h m does not mention the extra
multi-query-replace-map keystrokes when one is running, for example,
tags-query-replace.

I bet I'm not the only user who would love this feature but has never
come across it; ideally it would also be documented in the manual, but
making its documentation appear when describe-mode is run would at least
make it discoverable.


In GNU Emacs 24.2.1 (x86_64-pc-linux-gnu, GTK+ Version 2.24.10)
 of 2012-10-07 on americium, modified by Debian
Windowing system distributor `The X.Org Foundation', version 11.0.11103000
Configured using:
 `configure '--build' 'x86_64-linux-gnu' '--build' 'x86_64-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var/lib' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 '--enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.2/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.2/site-lisp:/usr/share/emacs/site-lisp'
 '--with-crt-dir=/usr/lib/x86_64-linux-gnu' '--with-x=yes'
 '--with-x-toolkit=gtk' '--with-toolkit-scroll-bars'
 'build_alias=x86_64-linux-gnu' 'CFLAGS=-g -O2 -fstack-protector
 --param=ssp-buffer-size=4 -Wformat -Wformat-security
 -Werror=format-security -Wall' 'LDFLAGS=-Wl,-Bsymbolic-functions
 -Wl,-z,relro' 'CPPFLAGS=-D_FORTIFY_SOURCE=2''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: en_GB.UTF-8
  value of $LC_NUMERIC: en_GB.UTF-8
  value of $LC_TIME: en_GB.UTF-8
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  diff-auto-refine-mode: t
  TeX-PDF-mode: t
  recentf-mode: t
  show-paren-mode: t
  server-mode: t
  savehist-mode: t
  minibuffer-electric-default-mode: t
  iswitchb-mode: t
  icomplete-mode: t
  global-auto-revert-mode: t
  desktop-save-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
_ b u f f e r <return> C-h m C-n C-n C-SPC C-n C-n 
C-n C-n C-n C-n C-n C-n C-n M-w C-x b C-g q C-h m C-x 
b <return> C-] C-] C-] C-] C-] C-_ C-g C-_ M-x <up> 
<return> <return> Y M-x <up> <return> e o l p <return> 
e n d _ o f _ l i n e <return> <help-echo> <help-echo> 
<help-echo> <help-echo> <down-mouse-3> <down-mouse-1> 
<mouse-1> <help-echo> y C-_ M-x <up> <return> <return> 
Y C-x s ! C-a C-h f q u e r y - r e p l a c e <return> 
C-n C-f C-f C-f <return> C-x 1 <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
C-s m o d e C-x C-f ~ / . e m a c s . d / <tab> c u 
<tab> <return> C-s q u e r y C-s C-s C-a C-s m o d 
l e <backspace> <backspace> e l i n e C-s C-s C-s C-s 
C-s C-a C-x k <return> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down-mouse-1> <mouse-1> 
M-x r e p o r t b <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> e m a c s - r e p o r t - <M-backspace> 
<M-backspace> r e p o r t - b <backspace> e m a c s 
- b u g <return>

Recent messages:
Wrote /home/rrt/Software/zile-zee/src/move.lua
Saving file /home/rrt/Software/zile-zee/src/line.lua...
Wrote /home/rrt/Software/zile-zee/src/line.lua
Saving file /home/rrt/Software/zile-zee/src/editfns.lua...
Wrote /home/rrt/Software/zile-zee/src/editfns.lua
Saving file /home/rrt/Software/zile-zee/src/buffer.lua...
Wrote /home/rrt/Software/zile-zee/src/buffer.lua
Type "q" to restore previous buffer.
Mark saved where search started [3 times]
delete-backward-char: Text is read-only [3 times]

Load-path shadows:
/home/rrt/local/share/emacs/site-lisp/browse-kill-ring hides /usr/share/emacs24/site-lisp/emacs-goodies-el/browse-kill-ring
/home/rrt/local/share/emacs/site-lisp/dict hides /usr/share/emacs24/site-lisp/emacs-goodies-el/dict
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/dictionary-init hides /usr/share/emacs24/site-lisp/dictionary-el/dictionary-init
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/dictionary hides /usr/share/emacs24/site-lisp/dictionary-el/dictionary
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/link hides /usr/share/emacs24/site-lisp/dictionary-el/link
/home/rrt/.emacs.d/elpa/dictionary-1.8.7/connection hides /usr/share/emacs24/site-lisp/dictionary-el/connection
/usr/share/emacs/site-lisp/golang-mode/go-mode-load hides /usr/share/emacs/24.2/site-lisp/golang-mode/go-mode-load
/usr/share/emacs/site-lisp/golang-mode/go-mode hides /usr/share/emacs/24.2/site-lisp/golang-mode/go-mode
/usr/share/emacs/24.2/site-lisp/debian-startup hides /usr/share/emacs/site-lisp/debian-startup
/usr/share/emacs/24.2/site-lisp/cmake-data/cmake-mode hides /usr/share/emacs/site-lisp/cmake-mode
/usr/share/emacs/24.2/site-lisp/cdargs hides /usr/share/emacs/site-lisp/cdargs
/usr/share/emacs/site-lisp/rst hides /usr/share/emacs/24.2/lisp/textmodes/rst
/usr/share/emacs24/site-lisp/dictionaries-common/ispell hides /usr/share/emacs/24.2/lisp/textmodes/ispell
/usr/share/emacs24/site-lisp/dictionaries-common/flyspell hides /usr/share/emacs/24.2/lisp/textmodes/flyspell

Features:
(shadow sort gnus-util mail-extr emacsbug time-stamp misearch
multi-isearch find-func pp message sendmail format-spec rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045
ietf-drums mm-util mail-prsvr mailabbrev mail-utils gmm-utils mailheader
latexenc markdown-mode thingatpt cperl-mode m4-mode diff-git diff-mode
tex-info texinfo preview prv-emacs reporter tex-buf noutline outline
font-latex latex tex-style tex autoconf autoconf-mode sh-script
executable inform-mode vc-hg cc-mode cc-fonts cc-guess cc-menus cc-cmds
cc-styles cc-align cc-engine cc-vars cc-defs help-mode view etags
make-mode info jka-compr flymake compile vc-git face-remap flyspell
smart-quotes lua-mode comint ansi-color ring auto-dictionary-autoloads
c-eldoc-autoloads dictionary-autoloads diff-git-autoloads
dired-isearch-autoloads full-ack-autoloads guess-style-autoloads
kill-ring-search-autoloads magit-autoloads mv-shell-autoloads
tumble-autoloads http-post-simple-autoloads package tabulated-list
completing-help recentf tree-widget wid-edit uniquify regexp-opt paren
server savehist minibuf-eldef iswitchb icomplete autorevert desktop
cus-start cus-load ropemacs pymacs ispell user-site-loaddefs advice
advice-preload yasnippet help-fns derived edmacro kmacro easymenu assoc
cl muse-autoloads go-mode-load emacs-goodies-el emacs-goodies-custom
emacs-goodies-loaddefs easy-mmode preview-latex tex-site auto-loads
time-date tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd
tool-bar dnd fontset image fringe lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces
cus-face files text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget hashtable-print-readable backquote
make-network-process dbusbind dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)

-- 
http://rrt.sc3d.org/

bug#12655: 24.2; Cannot discover automatic-all or other multi-buffer replacement commands

[Juri Linkov]

> I was able to find a reference to it in the NEWS for Emacs 23.1, but
> that again was at the Lisp level; nowhere can I find user documentation
> for this handy feature. In particular, C-h m does not mention the extra
> multi-query-replace-map keystrokes when one is running, for example,
> tags-query-replace.

In http://debbugs.gnu.org/267#15   I proposed to document this feature
in the help message displayed by `C-h'.

But you mentioned `C-h m' (`describe-mode').
Do you mean to describe this feature in the docstrings of
`tags-query-replace', `dired-do-query-replace-regexp',
`vc-dir-query-replace-regexp' and `reftex-query-replace-document' ?

> I bet I'm not the only user who would love this feature but has never
> come across it; ideally it would also be documented in the manual, but
> making its documentation appear when describe-mode is run would at least
> make it discoverable.

`automatic-all' is already documented in (info "(elisp) Search and Replace")

Do you think it should be also documented in (info "(emacs) Tags Search") ?

Then (info "(emacs) VC Directory Commands") should link to the node
(info "(emacs) Tags Search") like (info "(emacs) Operating on Files") already does.
With these links, this feature could be documented just in one Info node.

bug#12655: 24.2; Cannot discover automatic-all or other multi-buffer replacement commands

[Reuben Thomas]

On 15 October 2012 16:14, Juri Linkov <juri@jurta.org> wrote:
>
> But you mentioned `C-h m' (`describe-mode').
> Do you mean to describe this feature in the docstrings of
> `tags-query-replace', `dired-do-query-replace-regexp',
> `vc-dir-query-replace-regexp' and `reftex-query-replace-document' ?

No. That would seem a bad place, as it would duplicate information
manually. It should be somewhere that is controlled by the multifile
map being hooked into the keymap. The place that documents the current
keymap, i.e. the mode help, seems to be a logical place for this.

> `automatic-all' is already documented in (info "(elisp) Search and Replace")

That is elisp coding documentation, not Emacs user documentation.

> Do you think it should be also documented in (info "(emacs) Tags Search") ?
>
> Then (info "(emacs) VC Directory Commands") should link to the node
> (info "(emacs) Tags Search") like (info "(emacs) Operating on Files") already does.
> With these links, this feature could be documented just in one Info node.

Might it be more logical to mention it in the documentation "(emacs)
Query Replace", where all the other keystrokes are documented?

-- 
http://rrt.sc3d.org

bug#12655: 24.2; Cannot discover automatic-all or other multi-buffer replacement commands

[Juri Linkov]

> It should be somewhere that is controlled by the multifile
> map being hooked into the keymap. The place that documents the current
> keymap, i.e. the mode help, seems to be a logical place for this.

Then the right place to document it is in `query-replace-help':

=== modified file 'lisp/replace.el'
--- lisp/replace.el	2012-10-05 21:27:50 +0000
+++ lisp/replace.el	2012-10-15 21:52:54 +0000
@@ -1604,9 +1604,12 @@ (defconst query-replace-help
 C-r to enter recursive edit (\\[exit-recursive-edit] to get out again),
 C-w to delete match and recursive edit,
 C-l to clear the screen, redisplay, and offer same replacement again,
-! to replace all remaining matches with no more questions,
+! to replace all remaining matches in this buffer with no more questions,
 ^ to move point back to previous match,
-E to edit the replacement string"
+E to edit the replacement string.
+In multi-buffer replacements type `Y' to replace all remaining
+matches in all remaining buffers with no more questions,
+`N' to skip to the next buffer without replacing remaining matches
+in the current buffer."
   "Help message while in `query-replace'.")
 

> Might it be more logical to mention it in the documentation "(emacs)
> Query Replace", where all the other keystrokes are documented?

Right, with a link from (info "(emacs) Tags Search") to
(info "(emacs) Query Replace") (this link is fixed below)
this can be documented in (info "(emacs) Query Replace"):

=== modified file 'doc/emacs/search.texi'
--- doc/emacs/search.texi	2012-09-30 09:18:38 +0000
+++ doc/emacs/search.texi	2012-10-15 21:57:19 +0000
@@ -1239,6 +1239,19 @@ @node Query Replace
 @item !
 to replace all remaining occurrences without asking again.
 
+@item Y @r{(Upper-case)}
+to replace all remaining occurrences in all remaining buffers in
+multi-buffer replacements (like the Dired `Q' command which performs
+query replace on selected files).  It answers this question and all
+subsequent questions in the series with "yes", without further
+user interaction.
+
+@item N @r{(Upper-case)}
+to skip to the next buffer in multi-buffer replacements without
+replacing remaining occurrences in the current buffer.  It answers
+this question "no", gives up on the questions for the current buffer,
+and continues to the next buffer in the sequence.
+
 @item ^
 to go back to the position of the previous occurrence (or what used to
 be an occurrence), in case you changed it by mistake or want to

=== modified file 'doc/emacs/maintaining.texi'
--- doc/emacs/maintaining.texi	2012-10-02 06:44:30 +0000
+++ doc/emacs/maintaining.texi	2012-10-15 21:59:41 +0000
@@ -2221,7 +2221,7 @@ @node Tags Search
 reads a regexp to search for and a string to replace with, just like
 ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
 tags-search}, but repeatedly, processing matches according to your
-input.  @xref{Replace}, for more information on query replace.
+input.  @xref{Query Replace}, for more information on query replace.
 
 @vindex tags-case-fold-search
 @cindex case-sensitivity and tags search

bug#12655: 24.2; Cannot discover automatic-all or other multi-buffer replacement commands

[Reuben Thomas]

Thanks very much for your help with this, Juri!