bug#31135: 26.1; documentation of left-word and right-word are unclear

bug#31135: 26.1; documentation of left-word and right-word are unclear

[Robert Pluim]

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

bug#31135: 26.1; documentation of left-word and right-word are unclear

[Eli Zaretskii]

> From: Robert Pluim <rpluim@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.

bug#31135: 26.1; documentation of left-word and right-word are unclear

[Robert Pluim]

[-- Attachment #1: Type: text/plain, Size: 953 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Pluim <rpluim@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?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Remove-repetitions-in-documentation-strings.patch --]
[-- Type: text/x-diff, Size: 3401 bytes --]

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


[-- Attachment #3: Type: text/plain, Size: 87 bytes --]


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

bug#31135: 26.1; documentation of left-word and right-word are unclear

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: 31135@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.

bug#31135: 26.1; documentation of left-word and right-word are unclear

[Robert Pluim]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Pluim <rpluim@gmail.com>
>> Cc: 31135@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