bug#46088: 26.3; doc string of `read-regexp'

bug#46088: 26.3; doc string of `read-regexp'

[Drew Adams]

A. This is unclear, to me:

 If DEFAULTS is a non-nil symbol, then if `read-regexp-defaults-function'
 is non-nil, we use that in place of DEFAULTS in the following:
   If DEFAULTS is the symbol `regexp-history-last', we use the first
   element of HISTORY (if specified) or `regexp-history'.
   If DEFAULTS is a function, we call it with no arguments and use
   what it returns, which should be either nil, a string, or a list of strings.

1. If DEFAULTS is not a non-nil symbol, or if
`read-regexp-defaults-function' is nil, then how to interpret that
"the following" text?  What's it for, in that case?  And if it's not
used in that case, then what if only one of those conditions holds?

2. Assume that `read-regexp-defaults-function' is non-nil - say
`foobar', and DEFAULTS is also a non-nil symbol, say `toto'.

Then DEFAULTS isn't `regexp-history-list', so the first sentence
("If DEFAULTS is the symbol `regexp-history-list') doesn't apply.
Now what if `toto' isn't a function?  What's the behavior?

3. Same thing, exactly, if both `read-regexp-defaults-function' and
DEFAULTS are the same symbol, `foobar'.

4. Assume that DEFAULTS is `regexp-history-last', and
`read-regexp-defaults-function' is a function.  Then the first sentence
applies, so we use the first element of HISTORY or `regexp-history' as
default.  OK.  This particular case is understandable, if hidden in the
jungle.

5. Assume that DEFAULTS is a function and
`read-regexp-defaults-function' is non-nil.  Then the first sentence
doesn't apply, but the second one does: "we call it with no
arguments..."  What's "it"?  DEFAULTS or
`read-regexp-defaults-function'?  (Nowhere does it say that the non-nil
value of the latter should be a function, but let's assume that's the
case, to be generous.)

This doc is impenetrable, to me at least.  There are 4 IFs, 2 of which
seem to be conditioned on the conjunction of the other two:

IF (a AND b) THEN:

 IF...
 IF...

The relations between the two nested IFs aren't clear.  Presumably
there's an ELSE between them, but the overall meaning of this DEFAULTS
description is unclear.

B. And then we get to:

  We append the standard values from `read-regexp-suggestions' to
  DEFAULTS before using it.

  If the first element of DEFAULTS is non-nil (and if PROMPT does not
  end in ":", followed by optional whitespace), we add it to the prompt.

How do you append that to a DEFAULTS value that's a string?  Or a
non-nil symbol?  Or a function?  How can we talk about the elements of a
string, symbol, or function?


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#46088: 26.3; doc string of `read-regexp'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> A. This is unclear, to me:
>
>  If DEFAULTS is a non-nil symbol, then if `read-regexp-defaults-function'
>  is non-nil, we use that in place of DEFAULTS in the following:
>    If DEFAULTS is the symbol `regexp-history-last', we use the first
>    element of HISTORY (if specified) or `regexp-history'.
>    If DEFAULTS is a function, we call it with no arguments and use
>    what it returns, which should be either nil, a string, or a list of strings.

That is pretty hard to parse, but the semantics are pretty convoluted,
too.  It's saying that if DEFAULTS is a symbol, then the actual value
used comes from `read-regexp-defaults-function' in the two cases
described.  That is, if `read-regexp-defaults-function' is non-nil.

I've now tried to reformulate this in Emacs 28, but it's a case of the
code being easier to read than trying to actually describe the semantics.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#46088: [External] : Re: bug#46088: 26.3; doc string of `read-regexp'

[Drew Adams]

> I've now tried to reformulate this in Emacs 28, but it's a case of the
> code being easier to read than trying to actually describe the
> semantics.

Thanks for trying.

FWIW, the doc in the Elisp manual is nearly as bad.
Also pretty comprehensible.  Beyond my pay grade, at least.

If the behavior is too complicated to explain, what's the point?  That suggests a behavior/design bug, not just a doc bug.  Clearly I can't judge that, because I don't understand what the behavior is.

bug#46088: [External] : Re: bug#46088: 26.3; doc string of `read-regexp'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > If the behavior is too complicated to explain, what's the point?
  > That suggests a behavior/design bug, not just a doc bug.  Clearly
  > I can't judge that, because I don't understand what the behavior
  > is.

It wouldn't be bad to look for a possible cleaner design and document
it, but a redesign sometimes causes problems of its own.

Another option is to say that some aspects of its behavior are
unspecified.  That will be a lot less work, and can't break anything.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)