GNU bug report logs - #55175
27.2; Doc of `isearch-toggle-char-fold', and similar

Previous Next

To reply to this bug, email your comments to 55175 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 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)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.