[slime-devel] Re: [Re: SLIME manual fixes]

[Madhu]

* "Bill Clementson"  <8757cb490701281120p7d88eb8eg5f6e6a01821d4061 at XXX> :
[snip good points]

| I originally opposed including both Appendix A (key binding index)
| and Appendix B (function index) in the documentation for the reasons
| I listed in my earlier post

I read those reasons, but maintain that any decent manual should
contain indices, and in the case of an emacs package, case keybindings
are highly relevant. I supplied my own 2 reasons, that the manual
should be correct documentation, and independent of a live emacs
session, which may not be at hand. [Also see below about `KEY INDEX']

When a live emacs session is available one could use the facilies of
course to get the exact current state of things. 

| Jeffrey has agreed and removed Appendix B. Since a number of people
| have indicated that they think Appendix A (key binding index) is a
| good idea, it might be worthwhile to keep it (although I still think
| i is not useful).

That may be presumptious and ignores how other people may have
traditionally used good manuals.

| However, if it is retained, it should be corrected to reflect the
| different types of slime buffers and the key bindings that are in
| effect in each. This will have the (in my mind) negative effect of
| increasing the size of this appendix, making it more difficult to
| maintain, and reducing its value to newbies.

No, if you note the other manuals, the `KEY INDEX' cross references
commands already listed in the manual.  Perhaps This would be
sufficient in SLIME's case too.

| However, if it is to be retained, it should at least be accurate.

There is no disputing that the keybindings should be accurate, and if
there is a disparity, it indicates a bug that should be addressed. The
bug could be equally well in the code, (which may need to be fixed to
conform to the manual) OR in the manual which would need to be fixed
to conform to the code. Docs have this `good' stabilizing effect.

There is no disputing that the keybindings should be accurate. I think
one of the final nails in ILISP's coffin may have been the
documentation of keybindings. (under this scenario: people downloaded
it, read the documentation and then tried it).

--
Madhu