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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#24979: closed (24.5; Doc string of `current-word')
Date: Fri, 25 Nov 2016 09:53:01 +0000

[Message part 1 (text/plain, inline)]

Your message dated Fri, 25 Nov 2016 11:52:24 +0200
with message-id <83fumf51k7.fsf <at> gnu.org>
and subject line Re: bug#24979: 24.5; Doc string of `current-word'
has caused the debbugs.gnu.org bug report #24979,
regarding 24.5; Doc string of `current-word'
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
24979: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=24979
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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 part 3 (message/rfc822, inline)]

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.

Previous Next

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