`mark' func returning nil

`mark' func returning nil

[Kevin Ryde]

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

The docstring and manual of the `mark' func reads to me like it always
returns an integer, and the nil return is only if you use the FORCE arg.

But if I'm not mistaken nil is normal when the mark has never been set
in a buffer (eg. C-x b foo C-: (mark) => nil).  It'd be nice if that
could be clarified, since I didn't realize it until I'd written some
code expecting an integer, which bombed in a new buffer.

2006-01-02  Kevin Ryde  <user42@zip.com.au>

        * simple.el (mark): Clarify docstring, return is nil if mark not yet
        set.

        * markers.texi (The Mark): Clarify `mark', return is nil if mark not
        yet set.


[-- Attachment #2: simple.el.diff --]
[-- Type: text/plain, Size: 1943 bytes --]

Index: simple.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/simple.el,v
retrieving revision 1.782
diff -u -c -r1.782 simple.el
cvs diff: conflicting specifications of output style
*** simple.el	28 Dec 2005 21:52:33 -0000	1.782
--- simple.el	4 Jan 2006 22:14:15 -0000
***************
*** 1,7 ****
  ;;; simple.el --- basic editing commands for Emacs
  
  ;; Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
! ;;   2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
  
  ;; Maintainer: FSF
  ;; Keywords: internal
--- 1,7 ----
  ;;; simple.el --- basic editing commands for Emacs
  
  ;; Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
! ;;   2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
  
  ;; Maintainer: FSF
  ;; Keywords: internal
***************
*** 3069,3078 ****
    "Hook run when the mark becomes inactive.")
  
  (defun mark (&optional force)
!   "Return this buffer's mark value as integer; error if mark inactive.
! If optional argument FORCE is non-nil, access the mark value
! even if the mark is not currently active, and return nil
! if there is no mark at all.
  
  If you are using this in an editing command, you are most likely making
  a mistake; see the documentation of `set-mark'."
--- 3069,3082 ----
    "Hook run when the mark becomes inactive.")
  
  (defun mark (&optional force)
!   "Return this buffer's mark value.
! The return is an integer buffer position, or nil if the mark is not
! yet set for this buffer.
! 
! In `transient-mark-mode', and unless `mark-even-if-inactive' is set,
! then an error is signalled if the mark is inactive.  Optional
! argument FORCE can be non-nil to get the mark anyway (as an integer
! or nil).
  
  If you are using this in an editing command, you are most likely making
  a mistake; see the documentation of `set-mark'."

[-- Attachment #3: markers.texi.diff --]
[-- Type: text/plain, Size: 1873 bytes --]

*** markers.texi.~1.24.~	2005-08-28 10:15:57.000000000 +1000
--- markers.texi	2006-01-05 09:18:54.602488696 +1100
***************
*** 1,7 ****
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
! @c   2004, 2005 Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/markers
  @node Markers, Text, Positions, Top
--- 1,7 ----
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
! @c   2004, 2005, 2006 Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/markers
  @node Markers, Text, Positions, Top
***************
*** 441,453 ****
  
  @defun mark &optional force
  @cindex current buffer mark
! This function returns the current buffer's mark position as an integer.
  
! If Transient Mark mode is enabled, @code{mark-even-if-inactive} is
! @code{nil} and the mark is inactive, @code{mark} normally signals
! an error.  However, if @var{force} is non-@code{nil}, then @code{mark}
! returns the mark position anyway---or @code{nil}, if the mark is not
! yet set for this buffer.
  @end defun
  
  @defun mark-marker
--- 441,454 ----
  
  @defun mark &optional force
  @cindex current buffer mark
! This function returns the current buffer's mark position as an
! integer, or @code{nil} if the mark is not yet set for this buffer.
  
! If Transient Mark mode is enabled, and unless
! @code{mark-even-if-inactive} is non-@code{nil}, then @code{mark}
! signals an error if the mark is inactive.  However, if @var{force} is
! non-@code{nil}, then @code{mark} returns the mark position anyway (an
! integer or @code{nil}).
  @end defun
  
  @defun mark-marker

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: `mark' func returning nil

[Kevin Rodgers]

Kevin Ryde wrote:
 >   (defun mark (&optional force)
 > !   "Return this buffer's mark value.
 > ! The return is an integer buffer position, or nil if the mark is not
 > ! yet set for this buffer.

"The return" reads rather oddly.  I think "The value" would be better.

-- 
Kevin