On 1/28/07, Madhu enometh@meer.net wrote:
- "Bill Clementson" 8757cb490701281120p7d88eb8eg5f6e6a01821d4061@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.
I really liked the original slime documentation (written, I believe, by Luke Gorrie). It was concise, covered what I needed to know and was fun to read. So far, the documentation hasn't deviated much from this (I like most of the changes that Jeffrey has made and it's great that someone has taken on the task of tidying up the docs).
However, I disagree with your assertion that "any decent manual should contain indices" and also the implication that the manual (as it currently is) does not represent "correct documentation". A manual should be designed for an audience and I think the slime manual DOES meet the needs of slime developers without function and key binding indices.
| 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.
I don't know that there is any good use case for keeping them. The key bindings and functions are covered in context in other parts of the manual. There's no need to duplicate that coverage in appendices.
| 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.
My point was that not all key bindings are "in scope" in all buffers in slime. If there is a key binding index, it should indicate where/when a particular binding is in effect. Otherwise, a user looks in the appendix, finds a key binding, tries it out, and gets a "key is undefined" error.
| 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.
Code is written. Bugs are found. Code is fixed. Very rarely does something that is written about key bindings in a manual contribute to finding/fixing a bug. However, it is very easy for lists of key bindings and lists of functions to get out-of-sync with the code. If there is some alternative way of getting this type of key/function documentation (and there is), then it is preferable to not have it manually maintained as it will constantly need updating.
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).
I don't remember that the documentation of key bindings played any part in the demise of ILISP. ILISP had become a bit bloated, harder to hack, and tended to lock up too frequently with some CL implementations.
-- Bill Clementson