GNU bug report logs - #10507
24.0.92; Doc of `search-forward' (and backward)

Previous Next

Full log

View this message in rfc822 format

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 10507 <at> debbugs.gnu.org
Subject: bug#10507: 24.0.92; Doc of `search-forward' (and backward)
Date: Mon, 16 Jan 2012 06:51:16 -0800

> > Furthermore, the doc says explicitly that the 4th arg MUST 
> > BE POSITIVE.  That is no only NOT the case, it is even the
> > case that the Emacs lisp code uses a negative value as the
> > 4th arg.  See, e.g., `zap-to-char'.
> 
> "MUST BE POSITIVE" doesn't mean that a negative argument will
> be rejected.  So the doc is perfectly allowed to say "MUST BE 
> POSITIVE" even if the code handles negative values (it just
> means that negative values are "NOT SUPPORTED").  And if some
> core code uses negative values, that's a naughty breach of
> abstraction, but that's about it.

Words, even words like "must", can always be somewhat ambiguous.  But "must"
generally implies some sort of enforcement or negative consequences if not
respected.

"Should" is typically used when something is recommended but not prohibited or
enforced.  And if you say nothing at all about positive/non-positive then, as
you are wont to say, "all bets are off" - no statement about support, the user
knows nothing.

I think that most readers would expect in this case ("must") that an error is
raised if the arg is not positive - or at least that the function becomes a
no-op.

Compare the doc for `/': "The arguments must be numbers or markers."

> So I see no bug here.  If you want a change, please say which and why.

A negative arg is supported by the code; it is used by Emacs source code; and it
is useful.  Knowing about it will mean simpler code by users.  Please document
(and support) it.  Thx.

Previous Next

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