--- Begin Message ---
|
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'
--- End Message ---
--- Begin Message ---
|
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 <address@hidden>
>
> 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.
--- End Message ---