<font color='black' size='2' face='Arial, Helvetica, sans-serif'><span class="Apple-style-span" style="white-space: pre; font-size: small;"><br>
</span>
<div><span class="Apple-style-span" style="font-size: small;">In the interest of making the SLIME ChangeLogs more useful, I have</span></div>

<div><span class="Apple-style-span" style="font-size: small;">written the following notes concerning Change Log mode.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">1. The major mode Change Log can be used with ChangeLog files to make</span></div>

<div><span class="Apple-style-span" style="font-size: small;">them behave as hypertext that can then be used to review quickly the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">changes that are described.  To do this, type C-c C-c when point is</span></div>

<div><span class="Apple-style-span" style="font-size: small;">before or on a properly-formatted ChangeLog entry, and the changed</span></div>

<div><span class="Apple-style-span" style="font-size: small;">file will displayed in another window, optionally, at the definition</span></div>

<div><span class="Apple-style-span" style="font-size: small;">of a specified symbol.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">As the documentation for C-c C-c (change-log-goto-source) says:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">   "Go to source location of "change log tag" near `point'.  A change</span></div>

<div><span class="Apple-style-span" style="font-size: small;">    log tag is a symbol within a parenthesized, comma-separated list.</span></div>

<div><span class="Apple-style-span" style="font-size: small;">    If no suitable tag can be found nearby, try to visit the file for</span></div>

<div><span class="Apple-style-span" style="font-size: small;">    the change under `point' instead."</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">A properly-formatted ChangeLog entry has the form:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">[white-space]* [file name] (symbol name,...): [descriptive text]</span></div>

<div><span class="Apple-style-span" style="font-size: small;">[white-space](symbol name): [descriptive text]</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">The trailing ':' is customary, but C-c C-c will attempt to find the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">definition of the parenthesized symbol(s) listed without it,</span></div>

<div><span class="Apple-style-span" style="font-size: small;">or even if the symbol is listed after it.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">Examples:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * slime.el (slime-edit-uses-xrefs): New variable. For contribs to</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * swank-cmucl.lisp (reset-sigio-handlers): New function.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * swank-backend.lisp (socket-fd, make-fd-stream, dup, exec-image)</span></div>

<div><br>
</div>

<div>
<div><span class="Apple-style-span" style="font-size: small;">        * slime.el (slime-selector-other-window): New variable.</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        (slime-selector): Bind it as need.</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        (def-slime-selector-method): Use the other window if so indicated.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">Pressing C-c C-c while the cursor is anywhere on the first two entries</span></div>

<div><span class="Apple-style-span" style="font-size: small;">will cause Emacs to locate those symbols' definitions (only) in those</span></div>

<div><span class="Apple-style-span" style="font-size: small;">files.  In the comma-delimited list of the third entry, C-c C-c will</span></div>

<div><span class="Apple-style-span" style="font-size: small;">locate the definition of the symbol closest to point.  In the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">multi-line fourth entry, C-c C-c will locate in slime.el the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">definition of the symbol closest to point.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">If the file or symbol name is misspelled or the parenthesized text is</span></div>

<div><span class="Apple-style-span" style="font-size: small;">not (strictly) a symbol name, then Emacs will indicate this with a</span></div>

<div><span class="Apple-style-span" style="font-size: small;">message rather than locating the symbol's definition.  So, for</span></div>

<div><span class="Apple-style-span" style="font-size: small;">example,</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">   * foo.lisp: Fix a typo (grammar error)</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">will cause Emacs to look in the file foo.lisp for the symbol 'grammar'</span></div>

<div><span class="Apple-style-span" style="font-size: small;">because it is parenthesized text following a file name.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">Authors of ChangeLog entries should be able to quickly check the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">validity of their entries by typing C-c C-c before committing them to</span></div>

<div><span class="Apple-style-span" style="font-size: small;">CVS.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">2. It is also possible to "walk through" a sequence of ChangeLog entries</span></div>

<div><span class="Apple-style-span" style="font-size: small;">just as you do with compiler errors by typing C-x ` (backquote), which</span></div>

<div><span class="Apple-style-span" style="font-size: small;">is mapped to `next-error'.  This will:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">  - open the file in another window at the definition specified by the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">    ChangeLog entry</span></div>

<div><span class="Apple-style-span" style="font-size: small;">  - move the cursor to that definition</span></div>

<div><span class="Apple-style-span" style="font-size: small;">  - move point in the ChangeLog file to the next entry for when you</span></div>

<div><span class="Apple-style-span" style="font-size: small;">    return to the ChangeLog</span></div>

<div>
<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">(Be aware that once the cursor is in the source file, `next-error' does</span></div>

<div><span class="Apple-style-span" style="font-size: small;">not have the same meaning as it does in the ChangeLog file.  After</span></div>

<div><span class="Apple-style-span" style="font-size: small;">reviewing the change, you will need to move the cursor back to the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">ChangeLog file before typing C-x ` to examine the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">file/symbol-definition of the next ChangeLog entry.)</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">3. This capability of Change Log mode exists for Lisp code.  It does not</span></div>

<div><span class="Apple-style-span" style="font-size: small;">work with, for example, texinfo files, that is, it does not understand</span></div>

<div><span class="Apple-style-span" style="font-size: small;">texinfo symbol definitions.  The following entry will open</span></div>

<div><span class="Apple-style-span" style="font-size: small;">"doc/slime.texi", but will not move point to the definition of the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">symbol:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * doc/slime.texi (swank-loader:init): is also needed for loading swank.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">Similarly, non-symbol-name text inside parentheses is meaningless to</span></div>

<div><span class="Apple-style-span" style="font-size: small;">C-c C-c.  So, for example, this entry:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * slime.el (compile-defun [test]): Add two cases.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">cannot be found using C-c C-c.  But the following entry can locate the</span></div>

<div><span class="Apple-style-span" style="font-size: small;">definition of `compile-defun', which can then be reviewed for the two</span></div>

<div><span class="Apple-style-span" style="font-size: small;">test cases.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * slime.el (compile-defun): Add two test cases.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">Also, non-definitions of symbols (that is, when you call a function or</span></div>

<div><span class="Apple-style-span" style="font-size: small;">reference a variable) cannot be found by C-c C-c.  So, the following</span></div>

<div><span class="Apple-style-span" style="font-size: small;">entry:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        * swank.lisp:</span></div>

<div><span class="Apple-style-span" style="font-size: small;">        (decode-message): Adopted</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">will cause Emacs to do nothing except display an informative message</span></div>

<div><span class="Apple-style-span" style="font-size: small;">when C-c C-c is pressed because, while `decode-message' is *used* in</span></div>

<div><span class="Apple-style-span" style="font-size: small;">swank.lisp, it is not defined there.</span></div>

<div>
<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">"Source location of tag `decode-message' not found in file `swank.lisp'"</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">An alternative entry that does not use the (symbol-name) syntax would</span></div>

<div><span class="Apple-style-span" style="font-size: small;">have the benefit of opening swank.lisp, allowing the user to then</span></div>

<div><span class="Apple-style-span" style="font-size: small;">search for references of `decode-message', for example:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">       * swank.lisp: Adopted the function `decode-message' where</span></div>

<div><span class="Apple-style-span" style="font-size: small;">         appropriate.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">4. Finally, on-the-fly spelling checking can be added to Change Log</span></div>

<div><span class="Apple-style-span" style="font-size: small;">mode with, for example, the following:</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">   (add-hook 'change-log-mode-hook 'turn-on-flyspell)</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">or, indirectly, with</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">   (add-hook 'text-mode-hook 'turn-on-flyspell)</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">This could be of help to non-native English readers who may have a</span></div>

<div><span class="Apple-style-span" style="font-size: small;">harder time guessing what a misspelled word should be.  A misspelled</span></div>

<div><span class="Apple-style-span" style="font-size: small;">word can be quickly repaired by cycling through possible corrections</span></div>

<div><span class="Apple-style-span" style="font-size: small;">using repeated M-Tab key presses.</span></div>

<div><span class="Apple-style-span" style="font-size: small;"><br>
</span></div>

<div><span class="Apple-style-span" style="font-size: small;">Thank you again to the authors of SLIME.</span></div>

<div><br>
</div>
</div>
</div>
</div>

<div style="clear:both"></div>
</font>=