GNU bug report logs - #31135
26.1; documentation of left-word and right-word are unclear

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 31135 in the body.
You can then email your comments to 31135 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #3 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; documentation of left-word and right-word are unclear
Date: Thu, 12 Apr 2018 18:21:37 +0200

The documentation strings for left-word and right-word both say:

  Value is normally t.
  If an edge of the buffer or a field boundary is reached, point is left there
  there and the function returns nil.  Field boundaries are not noticed


1. Which value is normally t?
2. 'there' is repeated in the second sentence.

Robert

In GNU Emacs 26.1 (build 2, x86_64-pc-linux-gnu, GTK+ Version 3.18.9)
 of 2018-04-12 built on rpluim-ubuntu
Repository revision: c267421647510319d2a70554e42f0d1c394dba0a
Windowing system distributor 'The X.Org Foundation', version 11.0.11804000
System Description:	KDE neon LTS User Edition 5.12

Message #6 received at 31135 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 31135 <at> debbugs.gnu.org
Subject: Re: bug#31135: 26.1;
 documentation of left-word and right-word are unclear
Date: Thu, 12 Apr 2018 19:51:10 +0300

> From: Robert Pluim <rpluim <at> gmail.com>
> Date: Thu, 12 Apr 2018 18:21:37 +0200
> 
> The documentation strings for left-word and right-word both say:
> 
>   Value is normally t.
>   If an edge of the buffer or a field boundary is reached, point is left there
>   there and the function returns nil.  Field boundaries are not noticed
> 
> 
> 1. Which value is normally t?

This is standard Emacs parlance: left-word is a function, and
functions generally return values in Lisp.  So when we say "value is"
in the doc string of a function, we mean the value returned by that
function.

> 2. 'there' is repeated in the second sentence.

This kind of stuff needs to be fixed, no need to report it.

Thanks.

Message #9 received at 31135 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31135 <at> debbugs.gnu.org
Subject: Re: bug#31135: 26.1;
 documentation of left-word and right-word are unclear
Date: Fri, 13 Apr 2018 12:13:25 +0200

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

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Robert Pluim <rpluim <at> gmail.com>
>> Date: Thu, 12 Apr 2018 18:21:37 +0200
>> 
>> The documentation strings for left-word and right-word both say:
>> 
>>   Value is normally t.
>>   If an edge of the buffer or a field boundary is reached, point is left there
>>   there and the function returns nil.  Field boundaries are not noticed
>> 
>> 
>> 1. Which value is normally t?
>
> This is standard Emacs parlance: left-word is a function, and
> functions generally return values in Lisp.  So when we say "value is"
> in the doc string of a function, we mean the value returned by that
> function.
>

OK. Iʼve seen 'return value is' used elsewhere, now itʼs clear.

>> 2. 'there' is repeated in the second sentence.
>
> This kind of stuff needs to be fixed, no need to report it.

I found a few more repetitions like this [1], all in lisp
docstrings. emacs-26 branch, I imagine?

[0001-Remove-repetitions-in-documentation-strings.patch (text/x-diff, inline)]

From 60e10c503131f3088e901c7bbaaa53da816cf1e1 Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim <at> gmail.com>
Date: Fri, 13 Apr 2018 12:09:35 +0200
Subject: [PATCH] Remove repetitions in documentation strings
To: emacs-devel <at> gnu.org

* lisp/bindings.el (right-word): Remove repetition
(left-word): Likewise.

* lisp/image-mode.el (image-mode-as-hex): Likewise.

* lisp/cedet/semantic/tag-ls.el (semantic-tag-similar-p): Likewise.

* lisp/textmodes/reftex-vars.el (reftex-view-crossref-extra): Likewise
---
 lisp/bindings.el              | 4 ++--
 lisp/cedet/semantic/tag-ls.el | 2 +-
 lisp/image-mode.el            | 2 +-
 lisp/textmodes/reftex-vars.el | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/lisp/bindings.el b/lisp/bindings.el
index e03b9e9a0c..3e202b9b78 100644
--- a/lisp/bindings.el
+++ b/lisp/bindings.el
@@ -807,7 +807,7 @@ right-word
 
 Value is normally t.
 If an edge of the buffer or a field boundary is reached, point is left there
-there and the function returns nil.  Field boundaries are not noticed
+and the function returns nil.  Field boundaries are not noticed
 if `inhibit-field-text-motion' is non-nil."
   (interactive "^p")
   (if (eq (current-bidi-paragraph-direction) 'left-to-right)
@@ -823,7 +823,7 @@ left-word
 
 Value is normally t.
 If an edge of the buffer or a field boundary is reached, point is left there
-there and the function returns nil.  Field boundaries are not noticed
+and the function returns nil.  Field boundaries are not noticed
 if `inhibit-field-text-motion' is non-nil."
   (interactive "^p")
   (if (eq (current-bidi-paragraph-direction) 'left-to-right)
diff --git a/lisp/cedet/semantic/tag-ls.el b/lisp/cedet/semantic/tag-ls.el
index b9cce17669..39a4d9542e 100644
--- a/lisp/cedet/semantic/tag-ls.el
+++ b/lisp/cedet/semantic/tag-ls.el
@@ -134,7 +134,7 @@ semantic-tag-similar-p
 attributes, and IGNORABLE-ATTRIBUTES will augment this list.
 
 Note that even though :name is not an attribute, it can be used to
-to indicate lax comparison of names via `semantic--tag-similar-names-p'")
+indicate lax comparison of names via `semantic--tag-similar-names-p'")
 
 ;; Note: optional thing is because overloadable fcns don't handle this
 ;; quite right.
diff --git a/lisp/image-mode.el b/lisp/image-mode.el
index 1052ed9761..c0186f07a1 100644
--- a/lisp/image-mode.el
+++ b/lisp/image-mode.el
@@ -676,7 +676,7 @@ image-mode-as-hex
 to display an image file as the actual image.
 
 You can use `image-mode-as-hex' in `auto-mode-alist' when you want to
-to display an image file as hex initially.
+display an image file as hex initially.
 
 See commands `image-mode' and `image-minor-mode' for more information
 on these modes."
diff --git a/lisp/textmodes/reftex-vars.el b/lisp/textmodes/reftex-vars.el
index 01ee4f5fa4..11dbb8d570 100644
--- a/lisp/textmodes/reftex-vars.el
+++ b/lisp/textmodes/reftex-vars.el
@@ -1616,7 +1616,7 @@ reftex-view-crossref-extra
 
 MACRO-RE is matched against the macro.  SEARCH-RE is the regexp used
 to search for cross references.  `%s' in this regexp is replaced with
-with the macro argument at point.  HIGHLIGHT is an integer indicating
+the macro argument at point.  HIGHLIGHT is an integer indicating
 which subgroup of the match should be highlighted."
   :group 'reftex-viewing-cross-references
   :type '(repeat (group (regexp  :tag "Macro  Regexp  ")
-- 
2.17.0.rc1.35.g90bbd502d

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

Footnotes: 
[1]  After getting far too distracted by the emacs-lisp reference manual

Message #12 received at 31135 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 31135 <at> debbugs.gnu.org
Subject: Re: bug#31135: 26.1;
 documentation of left-word and right-word are unclear
Date: Fri, 13 Apr 2018 15:38:31 +0300

> From: Robert Pluim <rpluim <at> gmail.com>
> Cc: 31135 <at> debbugs.gnu.org
> Date: Fri, 13 Apr 2018 12:13:25 +0200
> 
> >> 2. 'there' is repeated in the second sentence.
> >
> > This kind of stuff needs to be fixed, no need to report it.
> 
> I found a few more repetitions like this [1], all in lisp
> docstrings. emacs-26 branch, I imagine?

Yes, please.

Message #17 received at 31135-done <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31135-done <at> debbugs.gnu.org
Subject: Re: bug#31135: 26.1;
 documentation of left-word and right-word are unclear
Date: Fri, 13 Apr 2018 14:49:19 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Robert Pluim <rpluim <at> gmail.com>
>> Cc: 31135 <at> debbugs.gnu.org
>> Date: Fri, 13 Apr 2018 12:13:25 +0200
>> 
>> >> 2. 'there' is repeated in the second sentence.
>> >
>> > This kind of stuff needs to be fixed, no need to report it.
>> 
>> I found a few more repetitions like this [1], all in lisp
>> docstrings. emacs-26 branch, I imagine?
>
> Yes, please.

Done as 60e10c5031
Closing.

Robert

Previous Next

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