GNU bug report logs - #24979
24.5; Doc string of `current-word'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24979 in the body.
You can then email your comments to 24979 AT debbugs.gnu.org in the normal way.

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
Subject: 24.5; Doc string of `current-word'
Date: Mon, 21 Nov 2016 10:24:56 -0800 (PST)

This part of the doc string is wrong:

 The function, belying its name, normally finds a symbol.


1. There is no "normally".  Do you mean often?  Usually?  Sometimes?
   (When?)

2. It always returns a string, never a symbol.  A symbol is a Lisp
   object.  If you mean that it often returns a string that has symbol,
   not word, syntax, then say so.  That does not mean that it returns a
   symbol.  Yes, the first line of the doc now says that it returns a
   string.  This means that the doc as a whole is currently confusing
   and inconsistent.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

Message #10 received at 24979-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24979-done <at> debbugs.gnu.org
Subject: Re: bug#24979: 24.5; Doc string of `current-word'
Date: Fri, 25 Nov 2016 11:52:24 +0200

> Date: Mon, 21 Nov 2016 10:24:56 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> This part of the doc string is wrong:
> 
>  The function, belying its name, normally finds a symbol.
> 
> 
> 1. There is no "normally".  Do you mean often?  Usually?  Sometimes?
>    (When?)

"Normally" is GNU and Emacs parlance for "by default", and is usually
(as in this case) followed by the description of the non-default use
case.  You will find gazillions of this in the documentation.

> 2. It always returns a string, never a symbol.  A symbol is a Lisp
>    object.  If you mean that it often returns a string that has symbol,
>    not word, syntax, then say so.  That does not mean that it returns a
>    symbol.  Yes, the first line of the doc now says that it returns a
>    string.  This means that the doc as a whole is currently confusing
>    and inconsistent.

I think this is splitting hair, probably because "symbol" is ambiguous
due to its being a Lisp object.  E.g., if the doc string said

  Return the word at or near point, as a string.

you wouldn't object, because "word" is not a Lisp object.

Anyway, I modified the doc string to say

    "Return the word at or near point, as a string.
  The return value includes no text properties.

  If optional arg STRICT is non-nil, return nil unless point is
  within or adjacent to a word, otherwise look for a word within
  point's line.  If there is no word anywhere on point's line, the
  value is nil regardless of STRICT.

  By default, this function treats as a single word any sequence of
  characters that have either word or symbol syntax.  If optional
  arg REALLY-WORD is non-nil, only characters of word syntax can
  constitute a word."

Thanks.

Message #13 received at 24979-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 24979-done <at> debbugs.gnu.org
Subject: RE: bug#24979: 24.5; Doc string of `current-word'
Date: Fri, 25 Nov 2016 07:36:27 -0800 (PST)

> > This part of the doc string is wrong:
> >
> >  The function, belying its name, normally finds a symbol.
> >
> >
> > 1. There is no "normally".  Do you mean often?  Usually?
> >    Sometimes? (When?)
> 
> "Normally" is GNU and Emacs parlance for "by default", and is
> usually (as in this case) followed by the description of the
> non-default use case.  You will find gazillions of this in
> the documentation.

If there are other cases where "normally" is used to convey
"by default" then I hope they get fixed too.  If the
surrounding text makes clear, e.g. by explicitly contrasting,
that what is meant by "normally" is the default case, then
it could be OK (but should never be _preferred_ to stating
clearly and explicitly what the default behavior is).

In this case, "normally" might have been able to be understood
the way you say if the last two sentences were in their own
paragraph, so that the last more clearly qualified the
statement of the next-to-last, instead of appearing to stand
on its own.

> I think this is splitting hair, probably because "symbol" is
> ambiguous due to its being a Lisp object.  E.g., if the doc
> string said
>   Return the word at or near point, as a string.
> you wouldn't object, because "word" is not a Lisp object.

Correct.  I wouldn't have objected about calling it a word.

But I would have objected about "near", which is not the
same as on-the-same-line-and-adjacent-to - it is quite
different, in fact.

> Anyway, I modified the doc string to say
> 
>     "Return the word at or near point, as a string.

  Return the word at point or adjacent to it, as a string.

(or a bit less clear:

  Return the word at or adjacent to point, as a string.)

See above.

The rest looks good.  Thx.

Previous Next

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