[slime-devel] Making SLIME ChangeLogs more useful

[Mark Harig]

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.




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/slime-devel/attachments/20100127/72efafb2/attachment.html>