bug#37334: 26.3; doc string of `backward-word'

bug#37334: 26.3; doc string of `backward-word'

[Drew Adams]

This paragraph does not belong in the doc string of `backward-word':

 The word boundaries are normally determined by the buffer's
 syntax table and character script (according to
 'char-script-table'), but 'find-word-boundary-function-table',
 such as set up by 'subword-mode', can change that.  If a Lisp
 program needs to move by words determined strictly by the syntax
 table, it should use 'backward-word-strictly' instead.  See Info
 node '(elisp) Word Motion' for details.

At most, it should just say "See Info node '(elisp) Word Motion' for
information about word syntax and word boundaries" - or just "See Info
node '(elisp) Word Motion'".


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#37334: 26.3; doc string of `backward-word'

[Eli Zaretskii]

tags 37334 notabug
thanks

> Date: Sat, 7 Sep 2019 11:58:08 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This paragraph does not belong in the doc string of `backward-word':
> 
>  The word boundaries are normally determined by the buffer's
>  syntax table and character script (according to
>  'char-script-table'), but 'find-word-boundary-function-table',
>  such as set up by 'subword-mode', can change that.  If a Lisp
>  program needs to move by words determined strictly by the syntax
>  table, it should use 'backward-word-strictly' instead.  See Info
>  node '(elisp) Word Motion' for details.

I see no reason to claim this "doesn't belong", as it clearly _is_
relevant to word movement.  See also bug#22560 for some additional
background.

bug#37334: 26.3; doc string of `backward-word'

[Drew Adams]

> I see no reason to claim this "doesn't belong", as it
> clearly _is_ relevant to word movement.

Lots of things are "relevant to word movement" in some
way.  That doesn't mean all such things belong in the
doc string of `(for|back)ward-word'.  And I see no
reason why this particular text belongs there.  What's
a particular reason?

> See also bug#22560 for some additional background.

I'm aware of that bug.  And since you bring it up here...

IMHO, it is wrong to suppose, claim, or proclaim in a
blanket way that `(for|back)ward-word' should not be
used in Lisp code - that they are now only for
interactive use.  Doing that is a mistake - it goes
overboard.

AFAICT, the only reason given in that thread for why
Emacs should outlaw/prevent non-interactive use of
`(for|back)ward-word' was this "because", from Daniel:

> Because lots of packages invoke word movement commands
> on the user's behalf, expecting that movement happens
> by words.

That doesn't address code that invokes these commands
commands WITHOUT expecting that the movement
necessarily happens by "words".

That's exactly the case for thing-at-point code.  It
doesn't care whether `(for|back)ward-word' _actually_
moves by words, subwords, paragraphs, pages, elephants
or thermometers.

It relies on those functions for their opposite
cursor movement, whatever it in fact might be.  I see
no reason why it shouldn't use them in its Lisp code.

Functions `forward-*' and `backward-*' are used in a
general, conventional way by thingatpt.el.  The correct
behavior of its use of such functions does NOT rely on
any particular meaning or behavior of "word".  IOW, it
is _not_ covered by Daniel's "because".

The prohibition of non-interactive use is too strong.
All that should be said, IIUC, is that code that uses
these functions should not count on them moving across
what one might think of as "words" (in spite of their
names!).  IOW, make clear just what the problem is,
rather than raling against all non-interactive use.

bug#37334: 26.3; doc string of `backward-word'

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

> The prohibition of non-interactive use is too strong.

There isn't any prohibition in the current docstring, so I don't
understand why you feel the need to subject the bug list to this
lecture.