Positions are usually represented as integers starting from 1, but can
also be represented as @dfn{markers}---special objects that relocate
automatically when text is inserted or deleted so they stay with the
-surrounding characters. @xref{Markers}.
+surrounding characters. Functions that expect an argument to be a
+position (an integer), but accept a marker as a substitute, normally
+ignore the marker buffer. Of course, markers used this way usually
+point to a position in the buffer that the function operates on, but
+that is entirely the programmer's responsibility. @xref{Markers}.
See also the ``field'' feature (@pxref{Fields}), which provides
functions that are used by many cursor-motion commands.
@end defun
@defun buffer-end flag
-This function returns @code{(point-min)} if @var{flag} is less than 1,
-@code{(point-max)} otherwise. The argument @var{flag} must be a number.
+This function returns @code{(point-max)} if @var{flag} is greater than
+0, @code{(point-min)} otherwise. The argument @var{flag} must be a
+number.
@end defun
@defun buffer-size &optional buffer
@defun count-lines start end
@cindex lines in region
+@anchor{Definition of count-lines}
This function returns the number of lines between the positions
@var{start} and @var{end} in the current buffer. If @var{start} and
@var{end} are equal, then it returns 0. Otherwise it returns at least
(defun current-line ()
"Return the vertical position of point@dots{}"
(+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)
- -1))
+ (if (= (current-column) 0) 1 0)))
@end group
@end example
@end defun
+@defun line-number-at-pos &optional pos
+@cindex line number
+This function returns the line number in the current buffer
+corresponding the buffer position @var{pos}. If @var{pos} is @code{nil}
+or omitted, the current buffer position is used.
+@end defun
+
@ignore
@c ================
The @code{previous-line} and @code{next-line} commands are functions
@end deffn
@deffn Command down-list &optional arg
-This function moves forward into @var{arg} (default 1) levels of parentheses. A
-negative argument means move backward but still go
+This function moves forward into @var{arg} (default 1) levels of
+parentheses. A negative argument means move backward but still go
deeper in parentheses (@minus{}@var{arg} levels).
@end deffn
This function moves backward across @var{arg} (default 1) balanced expressions.
@end deffn
-@deffn Command beginning-of-defun arg
+@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.
@end deffn
-@deffn Command end-of-defun arg
+@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.
Note that char classes are not currently supported in
@var{character-set}; they will be treated as literals. Thus you
cannot use @code{"[:alpha:]"} instead of @code{"a-zA-Z"} to include
-non-ASCII letters. A way to skip forward over all letters is:
+non-@acronym{ASCII} letters. A way to skip forward over all letters is:
@example
(re-search-forward "\\=[[:alpha:]]*" nil t)
@strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all markers.
-Therefore, when the saved point value is restored, it normally comes
-before the inserted text.
+More precisely, the saved value is a marker with insertion type
+@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved
+point value is restored, it normally comes before the inserted text.
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
of the current region (point and the mark, with the smallest first).
@end deffn
-@deffn Command narrow-to-page move-count
+@deffn Command narrow-to-page &optional move-count
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
@var{move-count} non-@code{nil} means to move forward or backward by