vc.el documentation in wacky place (tentative patch included)

[era eriksson]

This bug report will be sent to the Free Software Foundation,
 not to your local site managers!!
Please write in English, because the Emacs maintainers do not have
translators to read other languages for them.

In GNU Emacs 20.3.2 (i386-debian-linux-gnu, X toolkit)
 of Thu Jan 28 1999 on raven
configured using `configure  i386-debian-linux-gnu --prefix=/usr 
--sharedstatedir=/var/lib --libexecdir=/usr/lib --localstatedir=/var/lib 
--infodir=/usr/info --with-pop=yes --with-x=yes --with-x-toolkit=yes'

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

The mode help for vc-mode is nonexistent, while vc-log-mode has
documentation which doesn't apply to vc-log-mode, and which in fact
looks like it would belong with vc-mode.

However, there is no vc-mode function, and so no natural place to move
this documentation.

Somehow, you get the feeling that some of this confusion is
intentional. Perhaps the author of vc.el didn't want to clutter mode
help with the fairly long description for vc-mode, which is likely to
be in use in a lot of buffers if you use version control for many
things. Nevertheless, I feel that the deviations from general
conventions for minor modes are confusing and gratuitous, and my
personal experience is that the documentation can only be stumbled
over if you happen to look at the Elisp source.

I've tried to rectify the situation with a simple change, but I'm not
sure it's really the way to go. My proposed change amounts to defining
a dummy function `vc-mode' to hang the documentation string on. It
does not do anything useful, it's just there for the documentation.
(Perhaps somebody could come up with an idea for what the function
should really do ...)

I'm including a diff against Emacs 20.3.2. Sorry for developing
against an older version; I'm afraid I don't have the resources to
keep up with Emacs development on my personal production machine. (I
tried to upgrade once, but ran into disk space problems.) I hope there
have not been substantial developments of vc-mode recently which
invalidate my proposed changes.

I'm afraid the diff is not as readable as it could be. I've moved
stuff from vc-log-mode and added it to the new function vc-mode, but
diff decided to make it look like vc-mode is a trimmed-down version of
the old vc-log-mode. It's quite the other way around.

For what it's worth, the added defvar of vc-mode is not really part of
this change, and a couple of the comments are also somewhat
tangential. But I thought they made sense to include as well.

I've taken the liberty to trim the standard "Recent input" and "Recent
messages" parts from this report, as they are irrelevant.


--- /usr/share/emacs/20.3/lisp/vc.el    Sun Oct  4 19:54:31 1998
+++ vc.el       Wed Nov  7 19:19:29 2001
@@ -5,7 +5,7 @@
 ;; Author:     Eric S. Raymond <esr@snark.thyrsus.com>
 ;; Maintainer: Andre Spiegel <spiegel@inf.fu-berlin.de>
 
-;; $Id: vc.el,v 1.236 1998/08/04 13:14:41 spiegel Exp $
+;; $Id: vc.el,v 1.236.1.3 2001/11/07 17:19:29 era Exp $
 
 ;; This file is part of GNU Emacs.
 
@@ -313,6 +313,12 @@
 (defvar vc-log-operation nil)
 (defvar vc-log-after-operation-hook nil)
 (defvar vc-checkout-writable-buffer-hook 'vc-checkout-writable-buffer)
+
+;; Experimental addition by era
+(defvar vc-mode nil
+  "Variable for holding the current buffer's mode-line VC information.
+This variable is buffer-local.")
+
 ;; In a log entry buffer, this is a local variable
 ;; that points to the buffer for which it was made
 ;; (either a file, or a VC dired buffer).
@@ -1625,6 +1631,7 @@
 the file named in the current Dired buffer line.  `vv' invokes
 `vc-next-action' on this file, or on all files currently marked.
 There is a special command, `*l', to mark all files currently locked."
+  ;; TODO: include \\<vc-dired-mode-map> here?
   (make-local-hook 'dired-after-readin-hook)
   (add-hook 'dired-after-readin-hook 'vc-dired-hook nil t)
   ;; The following is slightly modified from dired.el,
@@ -3002,9 +3009,9 @@
 
 ;; Back-end-dependent stuff ends here.
 
-;; Set up key bindings for use while editing log messages
+;; Dummy mode function, for holding the documentation
 
-(defun vc-log-mode (&optional file)
+(defun vc-mode ()
   "Minor mode for driving version-control tools.
 These bindings are added to the global keymap when you enter this mode:
 \\[vc-next-action]             perform next logical version-control operation 
on current file
@@ -3020,22 +3027,6 @@
 \\[vc-annotate]                colorful display of the cvs annotate command 
 \\[vc-update-change-log]               add change log entry from recent 
checkins
 
-While you are entering a change log message for a version, the following
-additional bindings will be in effect.
-
-\\[vc-finish-logentry] proceed with check in, ending log message entry
-
-Whenever you do a checkin, your log comment is added to a ring of
-saved comments.  These can be recalled as follows:
-
-\\[vc-next-comment]    replace region with next message in comment ring
-\\[vc-previous-comment]        replace region with previous message in comment 
ring
-\\[vc-comment-search-reverse]  search backward for regexp in the comment ring
-\\[vc-comment-search-forward]  search backward for regexp in the comment ring
-
-Entry to the change-log submode calls the value of text-mode-hook, then
-the value of vc-log-mode-hook.
-
 Global user options:
        vc-initial-comment      If non-nil, require user to enter a change
                                comment upon first checkin of the file.
@@ -3064,6 +3055,35 @@
                                itself).
 "
   (interactive)
+  (error
+   (substitute-command-keys
+    ;; FIXME: What would be a better message here?
+    "Use e.g. \\[vc-next-action] to interact with the version control system.")
+   ))
+
+
+;; Set up key bindings for use while editing log messages
+
+(defun vc-log-mode (&optional file)
+"Major mode for authoring version control change log messages.
+
+While you are entering a change log message for a version, the following
+bindings will be in effect.
+
+\\[vc-finish-logentry] proceed with check in, ending log message entry
+
+Whenever you do a checkin, your log comment is added to a ring of
+saved comments.  These can be recalled as follows:
+
+\\[vc-next-comment]    replace region with next message in comment ring
+\\[vc-previous-comment]        replace region with previous message in comment 
ring
+\\[vc-comment-search-reverse]  search backward for regexp in the comment ring
+\\[vc-comment-search-forward]  search backward for regexp in the comment ring
+
+Entry to the change-log submode calls the value of text-mode-hook, then
+the value of vc-log-mode-hook."
+
+  (interactive)
   (set-syntax-table text-mode-syntax-table)
   (use-local-map vc-log-entry-mode)
   (setq local-abbrev-table text-mode-abbrev-table)
@@ -3077,6 +3097,9 @@
   (setq buffer-file-name nil)
   (run-hooks 'text-mode-hook 'vc-log-mode-hook)
 )
+
+;; Mystery: why is the keymap called `vc-log-entry-MODE'? // era
+;; TODO: rename to vc-log-mode-map?
 
 ;; Initialization code, to be done just once at load-time
 (if vc-log-entry-mode


Hope this helps,

/* era */

-- 
 Too much to say to fit into this .signature anyway: <http://www.iki.fi/era/>
  Fight spam in Europe: <http://www.euro.cauce.org/> * Sign the EU petition