unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#28609: simple.el
@ 2017-09-26 14:51 Devon Sean McCullough
  2017-09-26 16:28 ` John Wiegley
                   ` (3 more replies)
  0 siblings, 4 replies; 13+ messages in thread
From: Devon Sean McCullough @ 2017-09-26 14:51 UTC (permalink / raw)
  To: 28609

Correct grammar; also, call a pair a pair.

--- a/simple.el	2017-09-26 05:31:16.000000000 -0400
+++ b/simple.el	2017-09-26 10:45:41.000000000 -0400
@@ -39,11 +39,11 @@
 
 (defcustom shell-command-dont-erase-buffer nil
   "If non-nil, output buffer is not erased between shell commands.
-Also, a non-nil value set the point in the output buffer
-once the command complete.
-The value `beg-last-out' set point at the beginning of the output,
-`end-last-out' set point at the end of the buffer, `save-point'
-restore the buffer position before the command."
+Also, a non-nil value sets the point in the output buffer
+once the command completes.
+The value `beg-last-out' sets point at the beginning of the output,
+`end-last-out' sets point at the end of the buffer, `save-point'
+restores the buffer position before the command."
   :type '(choice
           (const :tag "Erase buffer" nil)
           (const :tag "Set point to beginning of last output" beg-last-out)
@@ -53,9 +53,9 @@
   :version "26.1")
 
 (defvar shell-command-saved-pos nil
-  "Point position in the output buffer after command complete.
-It is an alist (BUFFER . POS), where BUFFER is the output
-buffer, and POS is the point position in BUFFER once the command finish.
+  "Point position in the output buffer after command completes.
+It is an alist of (BUFFER . POS), where BUFFER is the output
+buffer, and POS is the point position in BUFFER once the command finishes.
 This variable is used when `shell-command-dont-erase-buffer' is non-nil.")
 
 (defcustom idle-update-delay 0.5
@@ -1003,7 +1003,7 @@
 If METHOD is `delete-only', then delete the region; the return value
 is undefined.  If METHOD is nil, then return the content as a string.
 If METHOD is `bounds', then return the boundaries of the region
-as a list of the form (START . END).
+as a pair of (START . END) positions.
 If METHOD is anything else, delete the region and return its content
 as a string, after filtering it with `filter-buffer-substring', which
 is called with METHOD as its 3rd argument.")
@@ -5473,7 +5473,7 @@
        (progn (cl-assert (mark)) t)))
 
 (defun region-bounds ()
-  "Return the boundaries of the region as a list of (START . END) positions."
+  "Return the boundaries of the region as a pair of (START . END) positions."
   (funcall region-extract-function 'bounds))
 
 (defun region-noncontiguous-p ()






^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-26 14:51 bug#28609: simple.el Devon Sean McCullough
@ 2017-09-26 16:28 ` John Wiegley
  2017-09-26 16:33 ` John Wiegley
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 13+ messages in thread
From: John Wiegley @ 2017-09-26 16:28 UTC (permalink / raw)
  To: Devon Sean McCullough; +Cc: 28609

>>>>> "DSM" == Devon Sean McCullough <Emacs-Hacker2017@jovi.net> writes:

DSM> Correct grammar; also, call a pair a pair.

Thank you! Even minor corrections like these are quite helpful.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-26 14:51 bug#28609: simple.el Devon Sean McCullough
  2017-09-26 16:28 ` John Wiegley
@ 2017-09-26 16:33 ` John Wiegley
  2017-09-26 19:09 ` Johan Bockgård
  2017-09-29 13:02 ` Eli Zaretskii
  3 siblings, 0 replies; 13+ messages in thread
From: John Wiegley @ 2017-09-26 16:33 UTC (permalink / raw)
  To: Devon Sean McCullough; +Cc: 28609

fixed 28609
thanks

This has been applied to the emacs-26 as a documentation correction, thank
you.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-26 14:51 bug#28609: simple.el Devon Sean McCullough
  2017-09-26 16:28 ` John Wiegley
  2017-09-26 16:33 ` John Wiegley
@ 2017-09-26 19:09 ` Johan Bockgård
  2017-09-26 19:37   ` John Wiegley
  2017-09-29 13:28   ` Eli Zaretskii
  2017-09-29 13:02 ` Eli Zaretskii
  3 siblings, 2 replies; 13+ messages in thread
From: Johan Bockgård @ 2017-09-26 19:09 UTC (permalink / raw)
  To: Devon Sean McCullough; +Cc: John Wiegley, 28609

Devon Sean McCullough <Emacs-Hacker2017@jovi.net> writes:

> @@ -1003,7 +1003,7 @@
>  If METHOD is `delete-only', then delete the region; the return value
>  is undefined.  If METHOD is nil, then return the content as a string.
>  If METHOD is `bounds', then return the boundaries of the region
> -as a list of the form (START . END).
> +as a pair of (START . END) positions.

It's a list of pairs.

> @@ -5473,7 +5473,7 @@
>         (progn (cl-assert (mark)) t)))
>  
>  (defun region-bounds ()
> -  "Return the boundaries of the region as a list of (START . END) positions."
> +  "Return the boundaries of the region as a pair of (START . END) positions."
>    (funcall region-extract-function 'bounds))

Ditto.





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-26 19:09 ` Johan Bockgård
@ 2017-09-26 19:37   ` John Wiegley
  2017-09-29 13:28   ` Eli Zaretskii
  1 sibling, 0 replies; 13+ messages in thread
From: John Wiegley @ 2017-09-26 19:37 UTC (permalink / raw)
  To: Johan Bockgård; +Cc: Devon Sean McCullough, 28609

>>>>> Johan Bockgård <bojohan@gnu.org> writes:

> It's a list of pairs.

Thanks, change applied in 98a37e60142340b9c2b4e6b17c373f4ae6a2d8b4 on emacs-26
branch, and 52a1da03b226b8686856259ac5d9474a8462322a on master.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-26 14:51 bug#28609: simple.el Devon Sean McCullough
                   ` (2 preceding siblings ...)
  2017-09-26 19:09 ` Johan Bockgård
@ 2017-09-29 13:02 ` Eli Zaretskii
  3 siblings, 0 replies; 13+ messages in thread
From: Eli Zaretskii @ 2017-09-29 13:02 UTC (permalink / raw)
  To: Devon Sean McCullough; +Cc: 28609

> From: Devon Sean McCullough <Emacs-Hacker2017@jovi.net>
> Date: Tue, 26 Sep 2017 10:51:04 -0400
> 
> Correct grammar; also, call a pair a pair.

Thanks for the fixes.

As for "pair", it's actually a cons cell, right?  Also, we do tend to
use the phrase "of the form ..." in our documentation, so there's no
need to remove that.

Finally, a nit: "Point position" is inherently ambiguous, so it's
better to use "Position of point" to disambiguate.  I made that change
in a followup commit.





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-26 19:09 ` Johan Bockgård
  2017-09-26 19:37   ` John Wiegley
@ 2017-09-29 13:28   ` Eli Zaretskii
  2017-09-30 11:09     ` Johan Bockgård
  2017-10-04 20:24     ` Johan Bockgård
  1 sibling, 2 replies; 13+ messages in thread
From: Eli Zaretskii @ 2017-09-29 13:28 UTC (permalink / raw)
  To: Johan Bockgård; +Cc: jwiegley, Emacs-Hacker2017, 28609

> From: Johan Bockgård <bojohan@gnu.org>
> Date: Tue, 26 Sep 2017 21:09:59 +0200
> Cc: John Wiegley <jwiegley@gmail.com>, 28609@debbugs.gnu.org
> 
> Devon Sean McCullough <Emacs-Hacker2017@jovi.net> writes:
> 
> > @@ -1003,7 +1003,7 @@
> >  If METHOD is `delete-only', then delete the region; the return value
> >  is undefined.  If METHOD is nil, then return the content as a string.
> >  If METHOD is `bounds', then return the boundaries of the region
> > -as a list of the form (START . END).
> > +as a pair of (START . END) positions.
> 
> It's a list of pairs.

Actually, a cons cell, right?

> > @@ -5473,7 +5473,7 @@
> >         (progn (cl-assert (mark)) t)))
> >  
> >  (defun region-bounds ()
> > -  "Return the boundaries of the region as a list of (START . END) positions."
> > +  "Return the boundaries of the region as a pair of (START . END) positions."
> >    (funcall region-extract-function 'bounds))
> 
> Ditto.

Ditto, right?





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
       [not found] ` <<838tgx8xpa.fsf@gnu.org>
@ 2017-09-30  2:30   ` Drew Adams
  2017-09-30  8:12     ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Drew Adams @ 2017-09-30  2:30 UTC (permalink / raw)
  To: Eli Zaretskii, Devon Sean McCullough; +Cc: 28609

> Finally, a nit: "Point position" is inherently ambiguous, so it's
> better to use "Position of point" to disambiguate.  I made that change
> in a followup commit.

Apologies for not reading the thread.  Going only by what is written
here, which might not be fair/appropriate, "position of point" is
also ill-advised.  "Point" is the buffer position of the cursor
(text-insertion position).  "Position of point" would then mean
"position of position of the cursor".

Again, please ignore if interpreting this out of context is mistaken.





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-30  2:30   ` Drew Adams
@ 2017-09-30  8:12     ` Eli Zaretskii
  0 siblings, 0 replies; 13+ messages in thread
From: Eli Zaretskii @ 2017-09-30  8:12 UTC (permalink / raw)
  To: Drew Adams; +Cc: Emacs-Hacker2017, 28609

> Date: Fri, 29 Sep 2017 19:30:40 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 28609@debbugs.gnu.org
> 
> > Finally, a nit: "Point position" is inherently ambiguous, so it's
> > better to use "Position of point" to disambiguate.  I made that change
> > in a followup commit.
> 
> Apologies for not reading the thread.  Going only by what is written
> here, which might not be fair/appropriate, "position of point" is
> also ill-advised.  "Point" is the buffer position of the cursor
> (text-insertion position).  "Position of point" would then mean
> "position of position of the cursor".

"Point" is Emacs terminology (and its definition in Glossary is not
"position of the cursor").  Since it's a widely-used term, I see no
need to replace "point" with its definition to judge that sentence's
grammar or style.  We use "position of point" in our manuals, and I
see no problem with that usage.





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-29 13:28   ` Eli Zaretskii
@ 2017-09-30 11:09     ` Johan Bockgård
  2017-10-04 20:24     ` Johan Bockgård
  1 sibling, 0 replies; 13+ messages in thread
From: Johan Bockgård @ 2017-09-30 11:09 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: jwiegley, Emacs-Hacker2017, 28609

Eli Zaretskii <eliz@gnu.org> writes:

> Actually, a cons cell, right?

A list of cons cells (see region-noncontiguous-p).






^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-09-29 13:28   ` Eli Zaretskii
  2017-09-30 11:09     ` Johan Bockgård
@ 2017-10-04 20:24     ` Johan Bockgård
  2017-10-05  8:33       ` Eli Zaretskii
  2020-08-22 19:23       ` Stefan Kangas
  1 sibling, 2 replies; 13+ messages in thread
From: Johan Bockgård @ 2017-10-04 20:24 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: jwiegley, Emacs-Hacker2017, 28609

Eli Zaretskii <eliz@gnu.org> writes:

> Actually, a cons cell, right?

No. Your latest doc fix is wrong; in all three cases
(shell-command-saved-pos, region-extract-function, region-bounds) the
value is a list of cons cells, not a single cons cell. (In the first
case it's an actual alist.)






^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-10-04 20:24     ` Johan Bockgård
@ 2017-10-05  8:33       ` Eli Zaretskii
  2020-08-22 19:23       ` Stefan Kangas
  1 sibling, 0 replies; 13+ messages in thread
From: Eli Zaretskii @ 2017-10-05  8:33 UTC (permalink / raw)
  To: Johan Bockgård; +Cc: jwiegley, Emacs-Hacker2017, 28609

> From: Johan Bockgård <bojohan@gnu.org>
> Cc: jwiegley@gmail.com,  Emacs-Hacker2017@jovi.net,  28609@debbugs.gnu.org
> Date: Wed, 04 Oct 2017 22:24:27 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Actually, a cons cell, right?
> 
> No. Your latest doc fix is wrong; in all three cases
> (shell-command-saved-pos, region-extract-function, region-bounds) the
> value is a list of cons cells, not a single cons cell. (In the first
> case it's an actual alist.)

Thanks.  Can you propose a patch to fix these discrepancies?





^ permalink raw reply	[flat|nested] 13+ messages in thread

* bug#28609: simple.el
  2017-10-04 20:24     ` Johan Bockgård
  2017-10-05  8:33       ` Eli Zaretskii
@ 2020-08-22 19:23       ` Stefan Kangas
  1 sibling, 0 replies; 13+ messages in thread
From: Stefan Kangas @ 2020-08-22 19:23 UTC (permalink / raw)
  To: Johan Bockgård; +Cc: jwiegley, Emacs-Hacker2017, 28609

close 28609 26.1
thanks

Johan Bockgård <bojohan@gnu.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> Actually, a cons cell, right?
>
> No. Your latest doc fix is wrong; in all three cases
> (shell-command-saved-pos, region-extract-function, region-bounds) the
> value is a list of cons cells, not a single cons cell. (In the first
> case it's an actual alist.)

This was fixed here:

commit c9d71b31bf1144c3f11a82612f07a7bd649c25d4
Author: Eli Zaretskii <eliz@gnu.org>
Date:   Sat Oct 21 11:36:37 2017 +0300

    Fix doc strings in simple.el

    * lisp/simple.el (shell-command-saved-pos)
    (region-extract-function, region-bounds): Doc fixes.  (Bug#28609)

But the bug was left open, so I'm closing it now.

Best regards,
Stefan Kangas





^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2020-08-22 19:23 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-09-26 14:51 bug#28609: simple.el Devon Sean McCullough
2017-09-26 16:28 ` John Wiegley
2017-09-26 16:33 ` John Wiegley
2017-09-26 19:09 ` Johan Bockgård
2017-09-26 19:37   ` John Wiegley
2017-09-29 13:28   ` Eli Zaretskii
2017-09-30 11:09     ` Johan Bockgård
2017-10-04 20:24     ` Johan Bockgård
2017-10-05  8:33       ` Eli Zaretskii
2020-08-22 19:23       ` Stefan Kangas
2017-09-29 13:02 ` Eli Zaretskii
     [not found] <<D4ACD8F1-C378-4363-B319-1DADFCB639EF@jovi.net>
     [not found] ` <<838tgx8xpa.fsf@gnu.org>
2017-09-30  2:30   ` Drew Adams
2017-09-30  8:12     ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).