bug#24979: 24.5; Doc string of `current-word'

bug#24979: 24.5; Doc string of `current-word'

[Drew Adams]

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'

bug#24979: 24.5; Doc string of `current-word'

[Eli Zaretskii]

> Date: Mon, 21 Nov 2016 10:24:56 -0800 (PST)
> From: Drew Adams <drew.adams@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.

bug#24979: 24.5; Doc string of `current-word'

[Drew Adams]

> > 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.