I should have noticed that 'reply' went to Luke and not the list.
J.
----- Forwarded message from Jeffrey Cunningham jeffrey@cunningham.net -----
On Sun Jan 21, 2007 at 02:32:32PM +0100, Luke Gorrie wrote:
The manual improvements look good, great work!
Appendix A (index of keybindings) is excellent but I'm not sure that Appendix B (index of functions) is worth its price in virtual trees. Are there good "use cases" for it?
My reasoning was that if you want to find out what a function does without doing a text search it may be your only option. It isn't always clear what section you would find it in from the name alone.
But what really induced me to add it was when an upgrade of xpdf at work broke its text search capability and all I had on that machine was slime.pdf. ;-)
If no one else thinks it could be useful, I'll take it out.
--Jeff
----- End forwarded message -----
Hi Jeffrey,
On Sun Jan 21, 2007 at 02:32:32PM +0100, Luke Gorrie wrote:
The manual improvements look good, great work!
Appendix A (index of keybindings) is excellent but I'm not sure that Appendix B (index of functions) is worth its price in virtual trees. Are there good "use cases" for it?
My reasoning was that if you want to find out what a function does without doing a text search it may be your only option. It isn't always clear what section you would find it in from the name alone.
But what really induced me to add it was when an upgrade of xpdf at work broke its text search capability and all I had on that machine was slime.pdf. ;-)
If no one else thinks it could be useful, I'll take it out.
I'd like to second Luke's praise for your efforts in improving the SLIME documentation.
However, with regards to the 2 appendices, I am opposed to long lists of commands such as are in Appendix A and Appendix B because I think (for the most part) they are not of value. My reasons are:
1. Almost nobody reads long command lists 2. Unless they are automatically generated, they tend to get out-of-date fairly quickly 3. Contextual listings of the commands (such as are in section 3.2 for example) are much more useful. If someone is reading a specific section of the manual (for example, section 3.2.1.5 - Cross Reference Commands) because they want to learn how to do something, they will see that subset of commands that relates to the area that they are interested in. This is usually more relevant and there is more retention of the material since it is presented in a context where it can be best utilized. 4. Long command lists tend to add quantity rather than quality to documentation. 5. Most long-time slime users will probably rely on built-in emacs help commands (e.g. - C-h commands or find-function commands and source code) when they want to learn about a function. Therefore, command documentation in the manual should be targeted towards newbies who want to quickly learn functionality and towards experienced users who want to know more than function help and source might tell them. Long command lists serve neither newbies nor experienced users.
In general, I feel that occam's razor should apply to documentation. Usually, "less is more" with good technical documentation.
However, one thing was highlighted for me in the texi file for Appendix B (which has the list of ALL slime commands). The commands that aren't documented in the manual are commented out in the texi file so that they won't appear in the generated documentation and there are a lot of undocumented commands. I hadn't realized how many undocumented commands there were. Some of the commands are "internal" and shouldn't be documented in the manual; however, others are worth adding to the manual.
So, my opinion would be that the two appendices should be removed. It would be nice to have some of the undocumented commands added to the manual as well as more "how to" information of the type found in the Tips & Tricks section of the manual.
Anyhow, just my 2 cents.
-- Bill Clementson
On Sun Jan 21, 2007 at 09:07:04PM -0800, Bill Clementson wrote: <snip stuff>
- Almost nobody reads long command lists
- Unless they are automatically generated, they tend to get
out-of-date fairly quickly 3. Contextual listings of the commands (such as are in section 3.2 for example) are much more useful. If someone is reading a specific section of the manual (for example, section 3.2.1.5 - Cross Reference Commands) because they want to learn how to do something, they will see that subset of commands that relates to the area that they are interested in. This is usually more relevant and there is more retention of the material since it is presented in a context where it can be best utilized. 4. Long command lists tend to add quantity rather than quality to documentation. 5. Most long-time slime users will probably rely on built-in emacs help commands (e.g. - C-h commands or find-function commands and source code) when they want to learn about a function. Therefore, command documentation in the manual should be targeted towards newbies who want to quickly learn functionality and towards experienced users who want to know more than function help and source might tell them. Long command lists serve neither newbies nor experienced users.
Interesting comments.
I'm definitely one of the users that falls somewhere in between a long-time user and a total noob, and I've actually grown rather attached to the keybinding index. For example, I accidentally press the wrong key combination and it does something I don't expect and I want to find out what it was. I would usually have no idea what section to look in. But can I look it up in the key-binding index. And often, I'm not sure about a keybinding and find that its a lot less work to visually browse the two pages and see it than drill down through the various levels to find its section. Two pages doesn't seem like a terrible burden. And the links to the sections get me in the vicinity of similar commands very quickly. I guess the more I think about it, the less I see it as a quantity vs quality issue.
Keeping the documentation up to date is always going to be a chore. I wrote a script early on to extract the key-bindings and it was partially successful. But there are many exceptions which made the list incomplete. I don't know what can be done about that. I think keeping those two indices up to date is far less trouble than documenting all the undocumented functions I found.
Incidentally, I pruned everything that wasn't "public" so far as I could tell - meaning that I couldn't call it from either a key-binding or a M-x command, I figured it probably didn't belong in the documentation.
It seems like we lose nothing by by having the indices, and gain some degree of lookup capability when it is needed. The bits are pretty much free.
My two cents.
--Jeff
Jeffrey Cunningham jeffrey@cunningham.net writes:
For example, I accidentally press the wrong key combination and it does something I don't expect and I want to find out what it was. I would usually have no idea what section to look in. But can I look it up in the key-binding index.
Are you deliberately spiting Emacs's brilliant online help facilities? The gods will be angry. :-)
C-h k "What does this key do?" C-h l "Woah, what key chord did I just do?" C-h m "Tell me all about this mode" C-h b "Exactly what bindings are available?"
On Tue Jan 23, 2007 at 07:49:09PM +0100, Luke Gorrie wrote:
Jeffrey Cunningham jeffrey@cunningham.net writes:
For example, I accidentally press the wrong key combination and it does something I don't expect and I want to find out what it was. I would usually have no idea what section to look in. But can I look it up in the key-binding index.
Are you deliberately spiting Emacs's brilliant online help facilities? The gods will be angry. :-)
C-h k "What does this key do?" C-h l "Woah, what key chord did I just do?" C-h m "Tell me all about this mode" C-h b "Exactly what bindings are available?"
Not at all. You see I've got a slight problem. My C-h key was bound to backspace on the emacs system I learned on years ago, so I never learned the above key-bindings.
And after reading a couple recent threads where its usefulness has appeared manifest, I've been stewing about what to do. Unlearn one and learn the others? Are there other commonly used alternatives?
I don't want to do it wrong twice.
--Jeff
Jeffrey Cunningham jeffrey@cunningham.net writes:
Not at all. You see I've got a slight problem. My C-h key was bound to backspace on the emacs system I learned on years ago, so I never learned the above key-bindings.
And after reading a couple recent threads where its usefulness has appeared manifest, I've been stewing about what to do. Unlearn one and learn the others? Are there other commonly used alternatives?
I don't want to do it wrong twice.
I used Emacs for many years before I properly configured C-h. I'm glad I finally went through the trouble of setting it up to work in X, via terminals, etc, because it makes accessing all the help-system features much easier. I can't do without C-h today.
Zach
Jeffrey Cunningham jeffrey@cunningham.net writes:
Not at all. You see I've got a slight problem. My C-h key was bound to backspace on the emacs system I learned on years ago, so I never learned the above key-bindings.
Yeah this is a problem actually -- all right-thinking people have C-h meaning backspace, including in isearch:
(global-set-key "\C-h" 'backward-delete-char-untabify) (define-key isearch-mode-map "\C-h" 'isearch-delete-char))
but then we have to find a new binding for `help-command' like:
(global-set-key "\C-ch" 'help)
or keep on typing `M-x help'
so even though I write `C-h' as a canonical key in email I would never type this myself except to delete a character. :-)
-Luke (who ust migrated `help' from Hyper-h after switching from X11 to hyperless terminal Emacs..)
Not at all. You see I've got a slight problem. My C-h key was bound to backspace on the emacs system I learned on years ago, so I never learned the above key-bindings.
C-h is goto-last-change for me, but F1 does the same as C-h by default (at least when using emacs/xeamcs with X).
On Wed Jan 24, 2007 at 09:26:18AM +0100, Attila Lendvai wrote:
C-h is goto-last-change for me, but F1 does the same as C-h by default (at least when using emacs/xeamcs with X).
On gnu emacs F1 tries to invoke the "process sentinel". I suppose I could rebind that to C-h.
But wouldn't it be less confusing to have the default help keys actually match the 'canonical keys' we use to describe them with? If not, we should have (in the documentation) a description of what it takes to make it so.
--Jeff
C-h is goto-last-change for me, but F1 does the same as C-h by default (at least when using emacs/xeamcs with X).
On gnu emacs F1 tries to invoke the "process sentinel". I suppose I could rebind that to C-h.
for me F1 k F1 k returns a buffer with
"<f1> k runs the command describe-key..."
both on gnu emacs cvs and some older xemacs.
But wouldn't it be less confusing to have the default help keys actually match the 'canonical keys' we use to describe them with? If not, we should have (in the documentation) a description of what it takes to make it so.
oh, sorry for my confusing wording: i meant that i've remapped C-h to 'goto-last-change in my local emacs config (because i use that feature a lot and F1 is good replacement for C-h)
On Wed Jan 24, 2007 at 02:56:45PM +0100, Attila Lendvai wrote:
C-h is goto-last-change for me, but F1 does the same as C-h by default (at least when using emacs/xeamcs with X).
On gnu emacs F1 tries to invoke the "process sentinel". I suppose I could rebind that to C-h.
for me F1 k F1 k returns a buffer with
"<f1> k runs the command describe-key..."
both on gnu emacs cvs and some older xemacs.
But wouldn't it be less confusing to have the default help keys actually match the 'canonical keys' we use to describe them with? If not, we should have (in the documentation) a description of what it takes to make it so.
oh, sorry for my confusing wording: i meant that i've remapped C-h to 'goto-last-change in my local emacs config (because i use that feature a lot and F1 is good replacement for C-h)
This whole thread has been very useful. After working for a day with out C-h mapped to delete-char-left I put it back and remapped F1 to 'help-command. Now I the emacs gods should be happy once again. And I have a good idea for an addition to the document. This weekend I'll write it.
--Jeff
On Wed Jan 24, 2007 at 06:35:55PM -0800, Jeffrey Cunningham wrote:
This whole thread has been very useful. After working for a day with out C-h mapped to delete-char-left I put it back and remapped F1 to 'help-command. Now I the emacs gods should be happy once again. And I have a good idea for an addition to the document. This weekend I'll write it.
I just committed an update to docs/slime.texi that consisted of adding a brief discussion of the Emacs help functions as they apply to Slime, raised the level of the "Key bindings" subsection to section - preceding "Commands" (3 layers deep is too deep for new users I think - its one of the first things they will look for). And I eliminated the the keybindings index. Bill C.'s comments make complete sense given the Emacs facilities. I left the function index in for the time being. It might still be useful.
-Jeff
* Jeffrey Cunningham 20070127184619.GA26903@achilles.olympus.net : | And I eliminated the the keybindings index. Bill C.'s comments make | complete sense given the Emacs facilities.
Personally I think this is a bad move, and the manual is the place where the index should live. The manual serves a different purpose from a live running emacs. Any decently documented emacs package has a `Key Index' section in their manuals. just look at your info pages for any emacs mode.
People print commands of emacs cheat sheets after all.
It requires additional work in keeping with sync with the code, yes but that is a case for doing the additional work, not throwing the section out.
-- Madhu
On Sun Jan 28, 2007 at 08:21:19AM +0530, Madhu wrote:
- Jeffrey Cunningham 20070127184619.GA26903@achilles.olympus.net :
| And I eliminated the the keybindings index. Bill C.'s comments make | complete sense given the Emacs facilities.
Personally I think this is a bad move, and the manual is the place where the index should live. The manual serves a different purpose from a live running emacs. Any decently documented emacs package has a `Key Index' section in their manuals. just look at your info pages for any emacs mode.
People print commands of emacs cheat sheets after all.
It requires additional work in keeping with sync with the code, yes but that is a case for doing the additional work, not throwing the section out.
Hmmm. Your the first person who said they thought it was a good idea.
-Jeff
I like lists in the documentation too... I'm still an Emacs newbie though... is there a way to get a nice listing from the interactive help...?
thanks,
On Jan 28, 2007, at 12:58 AM, Jeffrey Cunningham wrote:
On Sun Jan 28, 2007 at 08:21:19AM +0530, Madhu wrote:
- Jeffrey Cunningham 20070127184619.GA26903@achilles.olympus.net :
| And I eliminated the the keybindings index. Bill C.'s comments make | complete sense given the Emacs facilities.
Personally I think this is a bad move, and the manual is the place where the index should live. The manual serves a different purpose from a live running emacs. Any decently documented emacs package has a `Key Index' section in their manuals. just look at your info pages for any emacs mode.
People print commands of emacs cheat sheets after all.
It requires additional work in keeping with sync with the code, yes but that is a case for doing the additional work, not throwing the section out.
Hmmm. Your the first person who said they thought it was a good idea.
-Jeff _______________________________________________ slime-devel site list slime-devel@common-lisp.net http://common-lisp.net/mailman/listinfo/slime-devel
-- Gary Warren King, metabang.com Cell: (413) 885 9127 Fax: (206) 338-4052 gwkkwg on Skype * garethsan on AIM
On Sun, 28 Jan 2007, Gary King wrote:
I like lists in the documentation too... I'm still an Emacs newbie though... is there a way to get a nice listing from the interactive help...?
describe-mode (usually bound to C-h m)
Andras
Thanks,
On Jan 28, 2007, at 9:12 AM, Andras Simon wrote:
On Sun, 28 Jan 2007, Gary King wrote:
I like lists in the documentation too... I'm still an Emacs newbie though... is there a way to get a nice listing from the interactive help...?
describe-mode (usually bound to C-h m)
Andras
-- Gary Warren King, metabang.com Cell: (413) 885 9127 Fax: (206) 338-4052 gwkkwg on Skype * garethsan on AIM
* Andras Simon Pine.LNX.4.56.0701281510330.31338@hexagon.math-inst.hu :
| On Sun, 28 Jan 2007, Gary King wrote: | |> I like lists in the documentation too... I'm still an Emacs newbie |> though... is there a way to get a nice listing from the interactive |> help...? | | describe-mode (usually bound to C-h m)
Just a caveat that even this not reflect the actual keybindings in effect! From a different thread ("C-M-q not working in SLIME 2007-01-20") in this mailing list:
http://permalink.gmane.org/gmane.lisp.slime.devel/5861
and the detailed explanation (with pointers to how to get the keybindings at the bottom of this post by Ariel Badichi.
http://permalink.gmane.org/gmane.lisp.slime.devel/5862
(perhaps another reason why, C-h m is no excuse to get rid of the key index? :p)
-- Madhu
On 1/28/07, Madhu enometh@meer.net wrote:
- Andras Simon Pine.LNX.4.56.0701281510330.31338@hexagon.math-inst.hu :
| On Sun, 28 Jan 2007, Gary King wrote: | |> I like lists in the documentation too... I'm still an Emacs newbie |> though... is there a way to get a nice listing from the interactive |> help...? | | describe-mode (usually bound to C-h m)
Just a caveat that even this not reflect the actual keybindings in effect! From a different thread ("C-M-q not working in SLIME 2007-01-20") in this mailing list:
http://permalink.gmane.org/gmane.lisp.slime.devel/5861
and the detailed explanation (with pointers to how to get the keybindings at the bottom of this post by Ariel Badichi.
It should also be noted that the Key Binding index in Appendix A does not reflect the actual key bindings that are in effect either! There are slime key bindings that are in effect when a user is in a lisp source member editing code, key bindings that are in effect when one is in a repl buffer, key bindings that are in effect when one is in an sdlb debugger buffer, key bindings that are in effect when one is in an inspector buffer, etc. So, to be accurate, Appendix A should list the default key bindings that are provide by slime in each of the different types of slime buffers (note also that not each type of slime buffer is a major or a minor mode).
(perhaps another reason why, C-h m is no excuse to get rid of the key index? :p)
In reality, there is no substitute for: 1. "C-h b" if you want to know all of the key bindings that are "in scope" at a specific time and, for specific keys/functions: 2. "C-h k" if you want to know what a specific key binding does 3. "C-h w" if you know a function name and want to know which key chord it is bound to
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 (http://common-lisp.net/pipermail/slime-devel/2007-January/005803.html). 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 it is not useful). 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. However, if it is to be retained, it should at least be accurate.
IMO, it would be better to replace Appendix A with a pointer to the appropriate help commands in the Emacs reference and to include a paragraph explaining why there is no full list of key bindings and how to access them (which, I believe, Jeffrey has already added). But, I don't want to beat this horse to death, so I'll defer to the group consensus on this if people really want Appendix A.
-- Bill Clementson
* "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.
| 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
On Mon Jan 29, 2007 at 06:23:47AM +0530, Madhu wrote:
| 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 removed it because (a) I had received only negative responses about the keybindings index, (b) I was the one that put it in in the first place. Hard to see what is presumptuous about that.
I wouldn't take much to put it back. But at this point I'm waiting to see some consensus from the community.
--Jeff
Jeffrey Cunningham jeffrey@cunningham.net writes:
I wouldn't take much to put it back. But at this point I'm waiting to see some consensus from the community.
I think that a good index adds to the value of any piece of documentation, and I have to confess to being slightly baffled that there's an opposing view. If there were a way of automatically ensuring that the documentation matched the code, whether through automatic generation or automatic testing, that might make the maintainer's job easier, but that may not be practical.
Cheers,
Christophe
On 1/28/07, Christophe Rhodes csr21@cantab.net wrote:
Jeffrey Cunningham jeffrey@cunningham.net writes:
I wouldn't take much to put it back. But at this point I'm waiting to see some consensus from the community.
I think that a good index adds to the value of any piece of documentation, and I have to confess to being slightly baffled that there's an opposing view.
I've listed the reasons why I'm opposed to the index in these posts: http://common-lisp.net/pipermail/slime-devel/2007-January/005803.html http://common-lisp.net/pipermail/slime-devel/2007-January/005869.html http://common-lisp.net/pipermail/slime-devel/2007-January/005872.html
You can disagree with me, but I don't think you need to be baffled. ;-)
If there were a way of automatically ensuring that the documentation matched the code, whether through automatic generation or automatic testing, that might make the maintainer's job easier, but that may not be practical.
-- Bill Clementson
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
* "Bill Clementson" 8757cb490701281739w13649d3dxf0374280a8135cd3@XXX :
| However, I disagree with your assertion that "any decent manual should | contain indices"
Ah, there we disagree!
| and also the implication that the manual (as it currently is) does | not represent "correct documentation".
It was an unfortunate incorrect use of the word `correct' but the I didnt want to claim the "current manual is not correct"
| 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.
I was operating under the assumption of a wider audience, of users who are not slime developers, including those who may also be learning emacs simultaneously with slime.
| 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.
This misses the point of an index.
-- Regards Madhu