[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#55175: 27.2; Doc of `isearch-toggle-char-fold', and similar
From: |
Drew Adams |
Subject: |
bug#55175: 27.2; Doc of `isearch-toggle-char-fold', and similar |
Date: |
Thu, 28 Apr 2022 20:39:35 +0000 |
`C-s C-h` tells you that `M-s `' toggles is bound to
`isearch-toggle-char-fold'. `C-h f' for that function tells you this:
isearch-toggle-char-fold is an interactive compiled Lisp function in
'isearch.el'.
(isearch-toggle-char-fold)
Toggle char-fold searching on or off.
Turning on character-folding turns off regexp mode.
If you click the `isearch.el' link, it takes you to that file, where you
expect to find the definition of `isearch-toggle-char-fold'.
Neither `imenu' nor searching for that function name
(`isearch-toggle-char-fold') will take you to any such definition.
Why? Because that function is defined in that file using macro
`isearch-define-mode-toggle'.
How would you know that that is how/where the command is defined? Not
by searching for the function name - not even in a comment near the use
of the macro to define it. There's no way you would find it, other than
by _both_ (1) reading the doc for the macro and (2) searching for
occurrences of the macro and paying attention to the fact that it is
applied to the symbol `char-fold' and the string `"'"' (as well as
knowing that `M-s '' in `isearch-mode' is bound to
`isearch-toggle-char-fold').
This problem is not limited to this Isearch command, and it's likely not
limited to the use of just this function-defining macro. Still, this is
one place to start fixing it.
Various fixes could be dreamed up. A simple, first step, at least, is
to add a comment line just before each use of the macro, naming the
command that it creates. A related second step would be to add a rule
to the Elisp coding conventions (in the Elisp manual), saying that this
should be done wherever a function- or variable-, or face- defining
macro is used (and saying why the rule is needed).
E.g., in `isearch.el':
;; Define command `isearch-toggle-char-fold' (`M-s '' in `isearch-mode-map').
(isearch-define-mode-toggle char-fold "'" char-fold-to-regexp "\
Turning on character-folding turns off regexp mode.")
In GNU Emacs 27.2 (build 1, x86_64-w64-mingw32)
of 2021-03-26 built on CIRROCUMULUS
Repository revision: deef5efafb70f4b171265b896505b92b6eef24e6
Repository branch: HEAD
Windowing system distributor 'Microsoft Corp.', version 10.0.19043
System Description: Microsoft Windows 10 Pro (v10.0.2009.19043.1645)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- bug#55175: 27.2; Doc of `isearch-toggle-char-fold', and similar,
Drew Adams <=