goto-line documentation update.

goto-line documentation update.

[Lute Kamstra]

I've updated the documentation of goto-line in the lisp manual.  Any
objections?

  Lute.

Index: doc/lispref/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.147
diff -c -r1.147 ChangeLog
*** doc/lispref/ChangeLog	19 Nov 2008 04:25:49 -0000	1.147
--- doc/lispref/ChangeLog	19 Nov 2008 05:56:39 -0000
***************
*** 1,3 ****
--- 1,7 ----
+ 2008-11-19  Lute Kamstra  <lute@gnu.org>
+ 
+ 	* positions.texi (Text Lines): Update goto-line documentation.
+ 
  2008-11-19  Glenn Morris  <rgm@gnu.org>
  
  	* doclicense.texi: Update to FDL 1.3.
Index: doc/lispref/positions.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/positions.texi,v
retrieving revision 1.6
diff -c -r1.6 positions.texi
*** doc/lispref/positions.texi	27 Oct 2008 21:30:00 -0000	1.6
--- doc/lispref/positions.texi	19 Nov 2008 05:56:39 -0000
***************
*** 299,317 ****
  of the window, by line continuation in display, or by how tabs and
  control characters are displayed.
  
! @deffn Command goto-line line
  This function moves point to the front of the @var{line}th line,
! counting from line 1 at beginning of the buffer.  If @var{line} is less
! than 1, it moves point to the beginning of the buffer.  If @var{line} is
! greater than the number of lines in the buffer, it moves point to the
! end of the buffer---that is, the @emph{end of the last line} of the
! buffer.  This is the only case in which @code{goto-line} does not
! necessarily move to the beginning of a line.
  
  If narrowing is in effect, then @var{line} still counts from the
  beginning of the buffer, but point cannot go outside the accessible
! portion.  So @code{goto-line} moves point to the beginning or end of the
! accessible portion, if the line number specifies an inaccessible
  position.
  
  The return value of @code{goto-line} is the difference between
--- 299,316 ----
  of the window, by line continuation in display, or by how tabs and
  control characters are displayed.
  
! @deffn Command goto-line line &optional buffer
  This function moves point to the front of the @var{line}th line,
! counting from line 1 at beginning of the buffer, and leaves mark at
! the previous position.  If @var{line} is less than 1, it moves point
! to the beginning of the buffer.  If @var{line} is greater than the
! number of lines in the buffer, it moves point to the end of the
! buffer---that is, the @emph{end of the last line} of the buffer.
  
  If narrowing is in effect, then @var{line} still counts from the
  beginning of the buffer, but point cannot go outside the accessible
! portion.  So @code{goto-line} moves point to the beginning or end of
! the accessible portion, if the line number specifies an inaccessible
  position.
  
  The return value of @code{goto-line} is the difference between
***************
*** 319,329 ****
  able to move (in the full buffer, before taking account of narrowing).
  Thus, the value is positive if the scan encounters the real end of the
  buffer before finding the specified line.  The value is zero if scan
! encounters the end of the accessible portion but not the real end of the
! buffer.
  
  In an interactive call, @var{line} is the numeric prefix argument if
! one has been provided.  Otherwise @var{line} is read in the minibuffer.
  @end deffn
  
  @deffn Command beginning-of-line &optional count
--- 318,336 ----
  able to move (in the full buffer, before taking account of narrowing).
  Thus, the value is positive if the scan encounters the real end of the
  buffer before finding the specified line.  The value is zero if scan
! encounters the end of the accessible portion but not the real end of
! the buffer.
! 
! If you provide the optional argument @var{buffer}, @code{goto-line}
! uses @var{buffer} instead of the current buffer and and displays it in
! another window if it was not already visible.
  
  In an interactive call, @var{line} is the numeric prefix argument if
! you provide one.  Otherwise @var{line} is read in the minibuffer.  If
! there is a number in the buffer at point, it is the default for
! @var{line}.  If you just provide the universal argument,
! @code{goto-line} uses the most recently selected buffer other than the
! current buffer and reads @var{line} in the minibuffer.
  @end deffn
  
  @deffn Command beginning-of-line &optional count
Index: lisp/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/lisp/ChangeLog,v
retrieving revision 1.14803
diff -c -r1.14803 ChangeLog
*** lisp/ChangeLog	19 Nov 2008 05:51:30 -0000	1.14803
--- lisp/ChangeLog	19 Nov 2008 05:56:45 -0000
***************
*** 1,5 ****
--- 1,7 ----
  2008-11-19  Lute Kamstra  <lute@gnu.org>
  
+ 	* simple.el (goto-line): Rename argument.
+ 
  	* autoinsert.el (auto-insert-alist): Don't use match data.
  
  2008-11-19  Glenn Morris  <rgm@gnu.org>
Index: lisp/simple.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/simple.el,v
retrieving revision 1.954
diff -c -r1.954 simple.el
*** lisp/simple.el	17 Nov 2008 01:54:05 -0000	1.954
--- lisp/simple.el	19 Nov 2008 05:56:47 -0000
***************
*** 837,851 ****
  
  ;; Counting lines, one way or another.
  
! (defun goto-line (arg &optional buffer)
!   "Goto line ARG, counting from line 1 at beginning of buffer.
! Normally, move point in the current buffer, and leave mark at previous
! position.  With just \\[universal-argument] as argument, move point
! in the most recently displayed other buffer, and switch to it.
! When called from Lisp code, the optional argument BUFFER specifies
! a buffer to switch to.
  
! If there's a number in the buffer at point, it is the default for ARG."
    (interactive
     (if (and current-prefix-arg (not (consp current-prefix-arg)))
         (list (prefix-numeric-value current-prefix-arg))
--- 837,852 ----
  
  ;; Counting lines, one way or another.
  
! (defun goto-line (line &optional buffer)
!   "Goto line LINE, counting from line 1 at beginning of buffer.
! Normally, move point in the current buffer, and leave mark at the
! previous position.  With just \\[universal-argument] as argument,
! move point in the most recently selected other buffer, and switch
! to it.  When called from Lisp code, the optional argument BUFFER
! specifies a buffer to switch to.
  
! If there's a number in the buffer at point, it is the default for
! LINE."
    (interactive
     (if (and current-prefix-arg (not (consp current-prefix-arg)))
         (list (prefix-numeric-value current-prefix-arg))
***************
*** 887,894 ****
      (widen)
      (goto-char 1)
      (if (eq selective-display t)
! 	(re-search-forward "[\n\C-m]" nil 'end (1- arg))
!       (forward-line (1- arg)))))
  
  (defun count-lines-region (start end)
    "Print number of lines and characters in the region."
--- 888,895 ----
      (widen)
      (goto-char 1)
      (if (eq selective-display t)
! 	(re-search-forward "[\n\C-m]" nil 'end (1- line))
!       (forward-line (1- line)))))
  
  (defun count-lines-region (start end)
    "Print number of lines and characters in the region."

Re: goto-line documentation update.

[Eli Zaretskii]

> From: Lute Kamstra <Lute.Kamstra.lists@xs4all.nl>
> Date: Wed, 19 Nov 2008 07:01:04 +0100
> 
> I've updated the documentation of goto-line in the lisp manual.

Thanks.

> Any objections?

No, but some comments.

> ! encounters the end of the accessible portion but not the real end of
                                               ^^^
A comma is missing here (yes, I know: it was missing in the original
text as well).

> ! uses @var{buffer} instead of the current buffer and and displays it in

Two "and"s.

> ! another window if it was not already visible.
                  ^
I think we need a comma here.

>   In an interactive call, @var{line} is the numeric prefix argument if
> ! you provide one.  Otherwise @var{line} is read in the minibuffer.  If
                               ^
and here.  Also "read from the minibuffer" is better, I think.

> ! there is a number in the buffer at point, it is the default for
> ! @var{line}.  If you just provide the universal argument,
> ! @code{goto-line} uses the most recently selected buffer other than the
> ! current buffer and reads @var{line} in the minibuffer.

Do we need such a detailed description of the interactive invocation
in the ELisp manual?  I think these details belong in the Emacs
manual, not here.

Re: goto-line documentation update.

[Lute Kamstra]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Lute Kamstra <Lute.Kamstra.lists@xs4all.nl>
>> Date: Wed, 19 Nov 2008 07:01:04 +0100
>>
>> I've updated the documentation of goto-line in the lisp manual.
>
> Thanks.
>
>> Any objections?
>
> No, but some comments.
>
>> ! encounters the end of the accessible portion but not the real end of
>                                                ^^^
> A comma is missing here (yes, I know: it was missing in the original
> text as well).
>
>> ! uses @var{buffer} instead of the current buffer and and displays it in
>
> Two "and"s.
>
>> ! another window if it was not already visible.
>                   ^
> I think we need a comma here.
>
>>   In an interactive call, @var{line} is the numeric prefix argument if
>> ! you provide one.  Otherwise @var{line} is read in the minibuffer.  If
>                                ^
> and here.  Also "read from the minibuffer" is better, I think.
>
>> ! there is a number in the buffer at point, it is the default for
>> ! @var{line}.  If you just provide the universal argument,
>> ! @code{goto-line} uses the most recently selected buffer other than the
>> ! current buffer and reads @var{line} in the minibuffer.
>
> Do we need such a detailed description of the interactive invocation
> in the ELisp manual?  I think these details belong in the Emacs
> manual, not here.

Thanks for the feedback.  I've incorporated your (and Juri's) comments
in the patch below.

  Lute.

Index: doc/lispref/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.148
diff -c -r1.148 ChangeLog
*** doc/lispref/ChangeLog	20 Nov 2008 02:42:27 -0000	1.148
--- doc/lispref/ChangeLog	20 Nov 2008 06:26:25 -0000
***************
*** 1,3 ****
--- 1,7 ----
+ 2008-11-20  Lute Kamstra  <lute@gnu.org>
+ 
+ 	* positions.texi (Text Lines): Update goto-line documentation.
+ 
  2008-11-20  Glenn Morris  <rgm@gnu.org>
  
  	* files.texi (Format Conversion Round-Trip): Mention `preserve'
Index: doc/lispref/positions.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/positions.texi,v
retrieving revision 1.6
diff -c -r1.6 positions.texi
*** doc/lispref/positions.texi	27 Oct 2008 21:30:00 -0000	1.6
--- doc/lispref/positions.texi	20 Nov 2008 06:26:26 -0000
***************
*** 299,312 ****
  of the window, by line continuation in display, or by how tabs and
  control characters are displayed.
  
! @deffn Command goto-line line
  This function moves point to the front of the @var{line}th line,
! counting from line 1 at beginning of the buffer.  If @var{line} is less
! than 1, it moves point to the beginning of the buffer.  If @var{line} is
! greater than the number of lines in the buffer, it moves point to the
! end of the buffer---that is, the @emph{end of the last line} of the
! buffer.  This is the only case in which @code{goto-line} does not
! necessarily move to the beginning of a line.
  
  If narrowing is in effect, then @var{line} still counts from the
  beginning of the buffer, but point cannot go outside the accessible
--- 299,311 ----
  of the window, by line continuation in display, or by how tabs and
  control characters are displayed.
  
! @deffn Command goto-line line &optional buffer
  This function moves point to the front of the @var{line}th line,
! counting from line 1 at beginning of the buffer, and leaves mark at the
! previous position.  If @var{line} is less than 1, it moves point to the
! beginning of the buffer.  If @var{line} is greater than the number of
! lines in the buffer, it moves point to the end of the buffer---that is,
! the @emph{end of the last line} of the buffer.
  
  If narrowing is in effect, then @var{line} still counts from the
  beginning of the buffer, but point cannot go outside the accessible
***************
*** 319,329 ****
  able to move (in the full buffer, before taking account of narrowing).
  Thus, the value is positive if the scan encounters the real end of the
  buffer before finding the specified line.  The value is zero if scan
! encounters the end of the accessible portion but not the real end of the
! buffer.
  
! In an interactive call, @var{line} is the numeric prefix argument if
! one has been provided.  Otherwise @var{line} is read in the minibuffer.
  @end deffn
  
  @deffn Command beginning-of-line &optional count
--- 318,329 ----
  able to move (in the full buffer, before taking account of narrowing).
  Thus, the value is positive if the scan encounters the real end of the
  buffer before finding the specified line.  The value is zero if scan
! encounters the end of the accessible portion, but not the real end of
! the buffer.
  
! If you provide the optional argument @var{buffer}, @code{goto-line} uses
! @var{buffer} instead of the current buffer and displays it in another
! window, if it was not already visible.
  @end deffn
  
  @deffn Command beginning-of-line &optional count
Index: doc/emacs/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/ChangeLog,v
retrieving revision 1.217
diff -c -r1.217 ChangeLog
*** doc/emacs/ChangeLog	19 Nov 2008 04:21:09 -0000	1.217
--- doc/emacs/ChangeLog	20 Nov 2008 06:26:28 -0000
***************
*** 1,3 ****
--- 1,10 ----
+ 2008-11-20  Lute Kamstra  <lute@gnu.org>
+ 
+ 	* buffers.texi (Select Buffer): Index goto-line.
+ 	* basic.texi (Moving Point): Mention the use of a numeric prefix
+ 	argument with goto-line and refer to Select Buffer for the use of a
+ 	plain prefix argument.
+ 
  2008-11-19  Glenn Morris  <rgm@gnu.org>
  
  	* doclicense.texi: Update to FDL 1.3.
Index: doc/emacs/basic.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/basic.texi,v
retrieving revision 1.10
diff -c -r1.10 basic.texi
*** doc/emacs/basic.texi	23 Oct 2008 01:08:30 -0000	1.10
--- doc/emacs/basic.texi	20 Nov 2008 06:26:28 -0000
***************
*** 221,229 ****
  @item M-g M-g
  @itemx M-g g
  Read a number @var{n} and move point to the beginning of line number
! @var{n} (@code{goto-line}).  Line 1 is the beginning of the buffer.
! If point is on or just after a number in the buffer, and you type
! @key{RET} with the minibuffer empty, that number is used for @var{n}.
  @item C-x C-n
  @findex set-goal-column
  @kindex C-x C-n
--- 221,232 ----
  @item M-g M-g
  @itemx M-g g
  Read a number @var{n} and move point to the beginning of line number
! @var{n} (@code{goto-line}).  Line 1 is the beginning of the buffer.  If
! point is on or just after a number in the buffer, that is the default
! for @var{n}.  Just type @key{RET} in the minibuffer to use it.  You can
! also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument.
! @xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it
! a plain prefix argument.
  @item C-x C-n
  @findex set-goal-column
  @kindex C-x C-n
Index: doc/emacs/buffers.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/buffers.texi,v
retrieving revision 1.4
diff -c -r1.4 buffers.texi
*** doc/emacs/buffers.texi	11 Oct 2008 17:35:20 -0000	1.4
--- doc/emacs/buffers.texi	20 Nov 2008 06:26:28 -0000
***************
*** 142,147 ****
--- 142,148 ----
  non-@code{nil}, and the buffer you want to switch to is already
  displayed in some frame, Emacs will just raise that frame.
  
+ @findex goto-line
    @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
  argument, reads a number @var{n} using the minibuffer, selects the
  most recently selected buffer other than the current buffer in another
Index: lisp/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/lisp/ChangeLog,v
retrieving revision 1.14810
diff -c -r1.14810 ChangeLog
*** lisp/ChangeLog	20 Nov 2008 02:45:32 -0000	1.14810
--- lisp/ChangeLog	20 Nov 2008 06:26:33 -0000
***************
*** 1,3 ****
--- 1,7 ----
+ 2008-11-20  Lute Kamstra  <lute@gnu.org>
+ 
+ 	* simple.el (goto-line): Rename argument.
+ 
  2008-11-20  Glenn Morris  <rgm@gnu.org>
  
  	* format.el (format-alist, format-write-file): Doc fix.
Index: lisp/simple.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/simple.el,v
retrieving revision 1.954
diff -c -r1.954 simple.el
*** lisp/simple.el	17 Nov 2008 01:54:05 -0000	1.954
--- lisp/simple.el	20 Nov 2008 06:26:36 -0000
***************
*** 837,851 ****
  
  ;; Counting lines, one way or another.
  
! (defun goto-line (arg &optional buffer)
!   "Goto line ARG, counting from line 1 at beginning of buffer.
! Normally, move point in the current buffer, and leave mark at previous
! position.  With just \\[universal-argument] as argument, move point
! in the most recently displayed other buffer, and switch to it.
! When called from Lisp code, the optional argument BUFFER specifies
! a buffer to switch to.
  
! If there's a number in the buffer at point, it is the default for ARG."
    (interactive
     (if (and current-prefix-arg (not (consp current-prefix-arg)))
         (list (prefix-numeric-value current-prefix-arg))
--- 837,852 ----
  
  ;; Counting lines, one way or another.
  
! (defun goto-line (line &optional buffer)
!   "Goto LINE, counting from line 1 at beginning of buffer.
! Normally, move point in the current buffer, and leave mark at the
! previous position.  With just \\[universal-argument] as argument,
! move point in the most recently selected other buffer, and switch
! to it.  When called from Lisp code, the optional argument BUFFER
! specifies a buffer to switch to.
  
! If there's a number in the buffer at point, it is the default for
! LINE."
    (interactive
     (if (and current-prefix-arg (not (consp current-prefix-arg)))
         (list (prefix-numeric-value current-prefix-arg))
***************
*** 887,894 ****
      (widen)
      (goto-char 1)
      (if (eq selective-display t)
! 	(re-search-forward "[\n\C-m]" nil 'end (1- arg))
!       (forward-line (1- arg)))))
  
  (defun count-lines-region (start end)
    "Print number of lines and characters in the region."
--- 888,895 ----
      (widen)
      (goto-char 1)
      (if (eq selective-display t)
! 	(re-search-forward "[\n\C-m]" nil 'end (1- line))
!       (forward-line (1- line)))))
  
  (defun count-lines-region (start end)
    "Print number of lines and characters in the region."

Re: goto-line documentation update.

[Juri Linkov]

> ! (defun goto-line (line &optional buffer)
> !   "Goto line LINE, counting from line 1 at beginning of buffer.

Usually doc strings avoid duplicate words for the argument name,
so a better doc string would be:

  "Go to LINE, counting from line 1 at beginning of buffer.

-- 
Juri Linkov
http://www.jurta.org/emacs/