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

Previous Next

Full log

View this message in rfc822 format

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