bug#2002: `beginning-of-defun' pushes mark undocumentedly. It shouldn't!

[Alan Mackenzie]

Hi, Emacs!

I was "horrified" to find `beginning-of-defun' pushes the mark.  OK,
maybe I should wake up, this having been done as long ago as 2004-05-01
in .../emacs-lisp/lisp.el 1.53.

However, this pushing of the mark is NOT DOCUMENTED, neither in the
Emacs nor the Elisp manual.  THIS IS A BUG!!!!

This marking is fine (maybe) when a user types C-M-a.  Actually, I think
it's of marginal utility - it's about as likely to be a nuisance as to
be helpful.

The marking is NOT ACCEPTABLE when begining-of-defun is used in a lisp
program.  Using b-o-d in a program is a reasonable thing to do.

The feature, if it is to remain must be documented in both manuals.  OK,
I'm volunteering to do this.  ;-)

POSSIBLE FIXES
==============

1. A new customizable option, with a name better than
`defun-movement-leaves-mark'.  This could be bound to nil by lisp
programs.

2. Document that lisp programs should use `beginning-of-defun-raw'.
(Does this exist in XEmacs?).

3. Revert b-o-d to leaving the mark well alone.

What do people think?

-- 
Alan Mackenzie (Nuremberg, Germany).