Reformatted.

[chise/xemacs-chise.git.1] / man / lispref / positions.texi

diff --git a/man/lispref/positions.texi b/man/lispref/positions.texi
index e52319d..abb7791 100644 (file)
--- a/man/lispref/positions.texi
+++ b/man/lispref/positions.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.

-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.

 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/positions.info
 @node Positions, Markers, Consoles and Devices, Top
 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/positions.info
 @node Positions, Markers, Consoles and Devices, Top

@@ -82,7 +82,7 @@ omitted.
 This function returns the maximum accessible value of point in
 @var{buffer}.  This is @code{(1+ (buffer-size buffer))}, unless
 narrowing is in effect, in which case it is the position of the end of
 This function returns the maximum accessible value of point in
 @var{buffer}.  This is @code{(1+ (buffer-size buffer))}, unless
 narrowing is in effect, in which case it is the position of the end of

-the region that you narrowed to. (@xref{Narrowing}).  @var{buffer}
+the region that you narrowed to. (@pxref{Narrowing}).  @var{buffer}

 defaults to the current buffer if omitted.
 @end defun
 
 defaults to the current buffer if omitted.
 @end defun
 

@@ -193,28 +193,27 @@ In an interactive call, @var{count} is the numeric prefix argument.
   These functions for parsing words use the syntax table to decide
 whether a given character is part of a word.  @xref{Syntax Tables}.
 
   These functions for parsing words use the syntax table to decide
 whether a given character is part of a word.  @xref{Syntax Tables}.
 

-@deffn Command forward-word count &optional buffer
+@deffn Command forward-word &optional count buffer

 This function moves point forward @var{count} words (or backward if
 @var{count} is negative).  Normally it returns @code{t}.  If this motion
 encounters the beginning or end of the buffer, or the limits of the
 accessible portion when narrowing is in effect, point stops there and
 This function moves point forward @var{count} words (or backward if
 @var{count} is negative).  Normally it returns @code{t}.  If this motion
 encounters the beginning or end of the buffer, or the limits of the
 accessible portion when narrowing is in effect, point stops there and

-the value is @code{nil}.  @var{buffer} defaults to the current buffer if
-omitted.
+the value is @code{nil}.  
+
+@var{count} defaults to @code{1} and @var{buffer} defaults to the
+current buffer.

 
 In an interactive call, @var{count} is set to the numeric prefix
 argument.
 @end deffn
 
 
 In an interactive call, @var{count} is set to the numeric prefix
 argument.
 @end deffn
 

-@deffn Command backward-word count &optional buffer
+@deffn Command backward-word &optional count buffer

 This function is just like @code{forward-word}, except that it moves
 backward until encountering the front of a word, rather than forward.
 @var{buffer} defaults to the current buffer if omitted.
 
 In an interactive call, @var{count} is set to the numeric prefix
 argument.
 This function is just like @code{forward-word}, except that it moves
 backward until encountering the front of a word, rather than forward.
 @var{buffer} defaults to the current buffer if omitted.
 
 In an interactive call, @var{count} is set to the numeric prefix
 argument.

-
-This function is rarely used in programs, as it is more efficient to
-call @code{forward-word} with a negative argument.

 @end deffn
 
 @defvar words-include-escapes
 @end deffn
 
 @defvar words-include-escapes

@@ -249,26 +248,26 @@ Likewise, to move to the end of the buffer, use:
 documented here to warn you not to use them in Lisp programs, because
 they set the mark and display messages in the echo area.
 
 documented here to warn you not to use them in Lisp programs, because
 they set the mark and display messages in the echo area.
 

-@deffn Command beginning-of-buffer &optional n
+@deffn Command beginning-of-buffer &optional count

 This function moves point to the beginning of the buffer (or the limits
 of the accessible portion, when narrowing is in effect), setting the
 This function moves point to the beginning of the buffer (or the limits
 of the accessible portion, when narrowing is in effect), setting the

-mark at the previous position.  If @var{n} is non-@code{nil}, then it
-puts point @var{n} tenths of the way from the beginning of the buffer.
+mark at the previous position.  If @var{count} is non-@code{nil}, then it
+puts point @var{count} tenths of the way from the beginning of the buffer.

 
 

-In an interactive call, @var{n} is the numeric prefix argument,
-if provided; otherwise @var{n} defaults to @code{nil}.
+In an interactive call, @var{count} is the numeric prefix argument,
+if provided; otherwise @var{count} defaults to @code{nil}.

 
 Don't use this function in Lisp programs!
 @end deffn
 
 
 Don't use this function in Lisp programs!
 @end deffn
 

-@deffn Command end-of-buffer &optional n
+@deffn Command end-of-buffer &optional count

 This function moves point to the end of the buffer (or the limits of
 the accessible portion, when narrowing is in effect), setting the mark
 This function moves point to the end of the buffer (or the limits of
 the accessible portion, when narrowing is in effect), setting the mark

-at the previous position.  If @var{n} is non-@code{nil}, then it puts
-point @var{n} tenths of the way from the end of the buffer.
+at the previous position.  If @var{count} is non-@code{nil}, then it puts
+point @var{count} tenths of the way from the end of the buffer.

 
 

-In an interactive call, @var{n} is the numeric prefix argument,
-if provided; otherwise @var{n} defaults to @code{nil}.
+In an interactive call, @var{count} is the numeric prefix argument,
+if provided; otherwise @var{count} defaults to @code{nil}.

 
 Don't use this function in Lisp programs!
 @end deffn
 
 Don't use this function in Lisp programs!
 @end deffn

@@ -353,7 +352,7 @@ the end of the last line, and the value will be 2.
 In an interactive call, @var{count} is the numeric prefix argument.
 @end deffn
 
 In an interactive call, @var{count} is the numeric prefix argument.
 @end deffn
 

-@defun count-lines start end
+@defun count-lines start end &optional ignore-invisible-lines-flag

 @cindex lines in region
 This function returns the number of lines between the positions
 @var{start} and @var{end} in the current buffer.  If @var{start} and
 @cindex lines in region
 This function returns the number of lines between the positions
 @var{start} and @var{end} in the current buffer.  If @var{start} and

@@ -362,6 +361,16 @@ This function returns the number of lines between the positions
 because the text between them, considered in isolation, must contain at
 least one line unless it is empty.
 
 because the text between them, considered in isolation, must contain at
 least one line unless it is empty.
 

+With optional @var{ignore-invisible-lines-flag} non-@code{nil}, lines
+collapsed with selective-display are excluded from the line count.
+
+@strong{N.B.} The expression to return the current line number is not
+obvious:
+
+@example
+(1+ (count-lines 1 (point-at-bol)))
+@end example
+

 Here is an example of using @code{count-lines}:
 
 @example
 Here is an example of using @code{count-lines}:
 
 @example

@@ -475,7 +484,7 @@ performance of your code.  @xref{Text Lines, cache-long-line-scans}.
 This function moves point to the start of the frame line @var{count}
 frame lines down from the frame line containing point.  If @var{count}
 is negative, it moves up instead.  The optional second argument
 This function moves point to the start of the frame line @var{count}
 frame lines down from the frame line containing point.  If @var{count}
 is negative, it moves up instead.  The optional second argument

-@var{window} may be used to specify a window other than the 
+@var{window} may be used to specify a window other than the

 selected window in which to perform the motion.
 
 Normally, @code{vertical-motion} returns the number of lines moved.  The
 selected window in which to perform the motion.
 
 Normally, @code{vertical-motion} returns the number of lines moved.  The

@@ -592,7 +601,7 @@ beginning of the first screen line.  @xref{Minibuffer Misc}.
 @end ignore
 
 @node List Motion
 @end ignore
 
 @node List Motion

-@subsection Moving over Balanced Expressions 
+@subsection Moving over Balanced Expressions

 @cindex sexp motion
 @cindex Lisp expression motion
 @cindex list motion
 @cindex sexp motion
 @cindex Lisp expression motion
 @cindex list motion

@@ -602,7 +611,7 @@ expressions (also called @dfn{sexps} in connection with moving across
 them in XEmacs).  The syntax table controls how these functions interpret
 various characters; see @ref{Syntax Tables}.  @xref{Parsing
 Expressions}, for lower-level primitives for scanning sexps or parts of
 them in XEmacs).  The syntax table controls how these functions interpret
 various characters; see @ref{Syntax Tables}.  @xref{Parsing
 Expressions}, for lower-level primitives for scanning sexps or parts of

-sexps.  For user-level commands, see @ref{Lists and Sexps,,, emacs, XEmacs
+sexps.  For user-level commands, see @ref{Lists and Sexps,,, xemacs, XEmacs

 Reference Manual}.
 
 @deffn Command forward-list &optional arg
 Reference Manual}.
 
 @deffn Command forward-list &optional arg

@@ -612,29 +621,30 @@ quotes are ignored.) @var{arg} defaults to 1 if omitted.  If @var{arg}
 is negative, move backward across that many groups of parentheses.
 @end deffn
 
 is negative, move backward across that many groups of parentheses.
 @end deffn
 

-@deffn Command backward-list &optional arg
-This function moves backward across @var{arg} balanced groups of
+@deffn Command backward-list &optional count
+This function moves backward across @var{count} balanced groups of

 parentheses. (Other syntactic entities such as words or paired string
 parentheses. (Other syntactic entities such as words or paired string

-quotes are ignored.) @var{arg} defaults to 1 if omitted.  If @var{arg}
-is negative, move forward across that many groups of parentheses.
+quotes are ignored.) @var{count} defaults to 1 if omitted.  If
+@var{count} is negative, move forward across that many groups of
+parentheses.

 @end deffn
 
 @end deffn
 

-@deffn Command up-list arg
-This function moves forward out of @var{arg} levels of parentheses.
+@deffn Command up-list &optional count
+This function moves forward out of @var{count} levels of parentheses.

 A negative argument means move backward but still to a less deep spot.
 @end deffn
 
 A negative argument means move backward but still to a less deep spot.
 @end deffn
 

-@deffn Command down-list arg
-This function moves forward into @var{arg} levels of parentheses.  A
-negative argument means move backward but still go
-deeper in parentheses (@minus{}@var{arg} levels).
+@deffn Command down-list &optional count
+This function moves forward into @var{count} levels of parentheses.
+A negative argument means move backward but still go deeper in
+parentheses (@minus{}@var{count} levels).

 @end deffn
 
 @end deffn
 

-@deffn Command forward-sexp &optional arg
-This function moves forward across @var{arg} balanced expressions.
+@deffn Command forward-sexp &optional count
+This function moves forward across @var{count} balanced expressions.

 Balanced expressions include both those delimited by parentheses and
 Balanced expressions include both those delimited by parentheses and

-other kinds, such as words and string constants.  @var{arg} defaults to
-1 if omitted.  If @var{arg} is negative, move backward across that many
+other kinds, such as words and string constants.  @var{count} defaults to
+1 if omitted.  If @var{count} is negative, move backward across that many

 balanced expressions.  For example,
 
 @example
 balanced expressions.  For example,
 
 @example

@@ -655,24 +665,24 @@ balanced expressions.  For example,
 @end example
 @end deffn
 
 @end example
 @end deffn
 

-@deffn Command backward-sexp &optional arg
-This function moves backward across @var{arg} balanced expressions.
-@var{arg} defaults to 1 if omitted.  If @var{arg} is negative, move
+@deffn Command backward-sexp &optional count
+This function moves backward across @var{count} balanced expressions.
+@var{count} defaults to 1 if omitted.  If @var{count} is negative, move

 forward across that many balanced expressions.
 @end deffn
 
 forward across that many balanced expressions.
 @end deffn
 

-@deffn Command beginning-of-defun &optional arg
-This function moves back to the @var{arg}th beginning of a defun.  If
-@var{arg} is negative, this actually moves forward, but it still moves
-to the beginning of a defun, not to the end of one.  @var{arg} defaults
-to 1 if omitted.
+@deffn Command beginning-of-defun &optional count
+This function moves back to the @var{count}th beginning of a defun.
+If @var{count} is negative, this actually moves forward, but it still
+moves to the beginning of a defun, not to the end of one.  @var{count}
+defaults to 1 if omitted.

 @end deffn
 
 @end deffn
 

-@deffn Command end-of-defun &optional arg
-This function moves forward to the @var{arg}th end of a defun.  If
-@var{arg} is negative, this actually moves backward, but it still moves
-to the end of a defun, not to the beginning of one.  @var{arg} defaults
-to 1 if omitted.
+@deffn Command end-of-defun &optional count
+This function moves forward to the @var{count}th end of a defun.
+If @var{count} is negative, this actually moves backward, but it still
+moves to the end of a defun, not to the beginning of one.  @var{count}
+defaults to 1 if omitted.

 @end deffn
 
 @defopt defun-prompt-regexp
 @end deffn
 
 @defopt defun-prompt-regexp

@@ -813,9 +823,9 @@ This special form evaluates @var{forms} with @var{buffer} as the current
 buffer.  It returns the value of the last form.
 @end defspec
 
 buffer.  It returns the value of the last form.
 @end defspec
 

-@defspec with-temp-file file forms@dots{}
+@defspec with-temp-file filename forms@dots{}

 This special form creates a new buffer, evaluates @var{forms} there, and
 This special form creates a new buffer, evaluates @var{forms} there, and

-writes the buffer to @var{file}.  It returns the value of the last form
+writes the buffer to @var{filename}.  It returns the value of the last form

 evaluated.
 @end defspec
 
 evaluated.
 @end defspec
 

@@ -901,7 +911,7 @@ before you try it.
 
 If @var{body} changes the current buffer, @code{save-restriction} still
 restores the restrictions on the original buffer (the buffer whose
 
 If @var{body} changes the current buffer, @code{save-restriction} still
 restores the restrictions on the original buffer (the buffer whose

-restructions it saved from), but it does not restore the identity of the
+restrictions it saved from), but it does not restore the identity of the

 current buffer.
 
 @code{save-restriction} does @emph{not} restore point and the mark; use
 current buffer.
 
 @code{save-restriction} does @emph{not} restore point and the mark; use

@@ -925,13 +935,13 @@ tool for the job.  Here is what you must use instead:
 
 @example
 @group
 
 @example
 @group

-(let ((beg (point-min-marker))
+(let ((start (point-min-marker))

       (end (point-max-marker)))
   (unwind-protect
       (progn @var{body})
     (save-excursion
       (end (point-max-marker)))
   (unwind-protect
       (progn @var{body})
     (save-excursion

-      (set-buffer (marker-buffer beg))
-      (narrow-to-region beg end))))
+      (set-buffer (marker-buffer start))
+      (narrow-to-region start end))))

 @end group
 @end example
 
 @end group
 @end example