In the interest of making the SLIME ChangeLogs more useful, I have written the following notes concerning Change Log mode.
1. The major mode Change Log can be used with ChangeLog files to make them behave as hypertext that can then be used to review quickly the changes that are described. To do this, type C-c C-c when point is before or on a properly-formatted ChangeLog entry, and the changed file will displayed in another window, optionally, at the definition of a specified symbol.
As the documentation for C-c C-c (change-log-goto-source) says:
"Go to source location of "change log tag" near `point'. A change log tag is a symbol within a parenthesized, comma-separated list. If no suitable tag can be found nearby, try to visit the file for the change under `point' instead."
A properly-formatted ChangeLog entry has the form:
[white-space]* [file name] (symbol name,...): [descriptive text] [white-space](symbol name): [descriptive text]
The trailing ':' is customary, but C-c C-c will attempt to find the definition of the parenthesized symbol(s) listed without it, or even if the symbol is listed after it.
Examples:
* slime.el (slime-edit-uses-xrefs): New variable. For contribs to
* swank-cmucl.lisp (reset-sigio-handlers): New function.
* swank-backend.lisp (socket-fd, make-fd-stream, dup, exec-image)
* slime.el (slime-selector-other-window): New variable. (slime-selector): Bind it as need. (def-slime-selector-method): Use the other window if so indicated.
Pressing C-c C-c while the cursor is anywhere on the first two entries will cause Emacs to locate those symbols' definitions (only) in those files. In the comma-delimited list of the third entry, C-c C-c will locate the definition of the symbol closest to point. In the multi-line fourth entry, C-c C-c will locate in slime.el the definition of the symbol closest to point.
If the file or symbol name is misspelled or the parenthesized text is not (strictly) a symbol name, then Emacs will indicate this with a message rather than locating the symbol's definition. So, for example,
* foo.lisp: Fix a typo (grammar error)
will cause Emacs to look in the file foo.lisp for the symbol 'grammar' because it is parenthesized text following a file name.
Authors of ChangeLog entries should be able to quickly check the validity of their entries by typing C-c C-c before committing them to CVS.
2. It is also possible to "walk through" a sequence of ChangeLog entries just as you do with compiler errors by typing C-x ` (backquote), which is mapped to `next-error'. This will:
- open the file in another window at the definition specified by the ChangeLog entry - move the cursor to that definition - move point in the ChangeLog file to the next entry for when you return to the ChangeLog
(Be aware that once the cursor is in the source file, `next-error' does not have the same meaning as it does in the ChangeLog file. After reviewing the change, you will need to move the cursor back to the ChangeLog file before typing C-x ` to examine the file/symbol-definition of the next ChangeLog entry.)
3. This capability of Change Log mode exists for Lisp code. It does not work with, for example, texinfo files, that is, it does not understand texinfo symbol definitions. The following entry will open "doc/slime.texi", but will not move point to the definition of the symbol:
* doc/slime.texi (swank-loader:init): is also needed for loading swank.
Similarly, non-symbol-name text inside parentheses is meaningless to C-c C-c. So, for example, this entry:
* slime.el (compile-defun [test]): Add two cases.
cannot be found using C-c C-c. But the following entry can locate the definition of `compile-defun', which can then be reviewed for the two test cases.
* slime.el (compile-defun): Add two test cases.
Also, non-definitions of symbols (that is, when you call a function or reference a variable) cannot be found by C-c C-c. So, the following entry:
* swank.lisp: (decode-message): Adopted
will cause Emacs to do nothing except display an informative message when C-c C-c is pressed because, while `decode-message' is *used* in swank.lisp, it is not defined there.
"Source location of tag `decode-message' not found in file `swank.lisp'"
An alternative entry that does not use the (symbol-name) syntax would have the benefit of opening swank.lisp, allowing the user to then search for references of `decode-message', for example:
* swank.lisp: Adopted the function `decode-message' where appropriate.
4. Finally, on-the-fly spelling checking can be added to Change Log mode with, for example, the following:
(add-hook 'change-log-mode-hook 'turn-on-flyspell)
or, indirectly, with
(add-hook 'text-mode-hook 'turn-on-flyspell)
This could be of help to non-native English readers who may have a harder time guessing what a misspelled word should be. A misspelled word can be quickly repaired by cycling through possible corrections using repeated M-Tab key presses.
Thank you again to the authors of SLIME.