From: Clementson, B. <Bil...@jd...> - 2003-07-15 14:30:44
|
From: Nikodemus Siivola on Tuesday, July 15, 2003 6:15 AM =20 > I recall that you (or someone) at some stage had a web-page=20 > with a nice table of bindings when you were asking for=20 > community input. >=20 > Have you considered putting that at a permanent location? The web page that I created while modifying the FSF keybindings was only meant to be a tool for soliciting feedback on different alternative mappings. Now that the changes have been made, the web page is no longer relevant. I am reluctant to make it available on a permanent basis as I have no intentions of keeping it updated. Also, ILISP documentation should be maintained as part of ILISP. If you think there are ways that we should improve the ILISP documentation, let's have that discussion; however, I don't think my old web page should be resurrected.=20 My personal feeling is that the ILISP texi file shouldn't have any keybindings in it at all - only commands. The "C-h m" output provides a very good summary of the keybindings and commands and I refer to it when I'm looking up keybindings rather than the documentation. However, that is just my viewpoint. How do others feel about this? -- Bill Clementson |
From: Clementson, B. <Bil...@jd...> - 2003-07-15 15:32:02
|
From: Nikodemus Siivola on Tuesday, July 15, 2003 8:57 AM > IMHO, the main value for keybinding documentation is easing=20 > the learning curve. =20 >=20 > People who are new to both emacs and Common Lisp > aren't in the most enviable of positions as it is: for them=20 > there is great value in being able to find keybindings by=20 > searching the documentation for such. ;) >=20 > Also, during the early learning stages a list of keybindings=20 > is a good learning tool as it is pretty much equivalent to=20 > "frequently used commands". >=20 > I've used emacs for a few years, but "C-h m" isn't something=20 > I yet do by reflex. I probably should, but I'm only bringing=20 > this up to illustrate that overcoming emacs-cluelessness is a=20 > long-term project for at least some of it's users. >=20 > That said, I can most certainly understand you reluctance to=20 > maintain multiple sets of documentation... >=20 > Hence I'd suggest mentioning the "C-h m" &co under=20 > "Keybindings" in the Ilisp documentation. Or maybe a "Short=20 > Guide to Developing with Ilisp" would be the correct solution. Ummm, I already put the following at the bottom of the intro to the "Keybindings" section: "Remember that you can type `C-h m' at any time to see help on the current major mode, which will show (among other things) a list of all currently active keybindings." :-( I agree that a "Short Guide to Developing with Ilisp" would be a useful thing. That will (hopefully) be what my ILC2003 paper on "Using Emacs as a Lisp IDE" will turn out to be. However, it will cover both Ilisp, eli & inferior lisp modes, so may not be as succinct as an ilisp-only guide would be. My intention was to post a version of the paper on the CL Cookbook site in order to make it more generally available for anyone who wants to use Emacs to develop lisp code.=20 This brings up the generic question of how much documentation is "enough" and what is the best way to provide supplemental documentation? I think it is difficult to know exactly where to draw the line between package-specific documentation (that needs to be included with something like ilisp) and tutorial-type documentation. My own feeling is that the former needs to be concise and just enough to get users going (because after people become comfortable with a package, most rarely return to the documentation) and that is what is included with ilisp at the moment (although I'm sure there's lots of room for improvements). The latter (tutorial-type documenation) is more appropriate for a site like CL Cookbook which can provide a better range of tutorial topics and can be maintained by a larger population. I think Edi Weitz deserves a lot of praise for setting up the CL Cookbook site as it gives the community a place to collect tutorial-type documentation. If you like, I can send you an early draft (once I have something to a reasonable state) and you can provide me with feedback as to whether it might be an adequate alternative to a "Short Guide to Developing with Ilisp" and whether the combination of the ilisp documentation and the CL Cookbook would provide beginners with sufficient "getting started" material. I appreciate your comments and feedback. -- Bill Clementson |
From: Clementson, B. <Bil...@jd...> - 2003-07-16 15:05:15
|
From: Bob Rogers on Tuesday, July 15, 2003 9:12 PM [snip]=20 > Although I use C-h m frequently, I still find lists of=20 > command bindings useful. Recall that C-h m lists bindings=20 > alphabetically, with it's own rules for how to alphabetize=20 > prefix combinations, so a cheat sheet that is topically=20 > organized does have some value-added of its own. True, however, with the new fsf keybindings, the commands ARE grouped topically because of the 3-key keybindings (e.g. -- all the compile commands are grouped under "C-c C-k ...", all the eval commands are grouped under "C-c C-j ...", etc. =20 [snip] > I would like to suggest a topically-organized index of=20 > commands with key bindings. What I liked about the Web page=20 > is that it showed all three sets of bindings -- original, old=20 > FSF, and your proposal -- in parallel. We'd only need two now=20 > -- "standard" and "traditional" -- but I think it's still a=20 > good idea to document both, especially since switching=20 > bindings modes in order to do "C-h m" is onerous. Why is (setq ilisp-*use-fsf-compliant-keybindings* t), "M-x run-ilisp", "C-h m" so onerous? So, I'm not really convinced, but let's consider what the "optimal" way of presenting such a listing would be and then decide if the value of such a listing would be worth the effort to create it. At the moment, the "legacy" bindings (but not the "fsf" bindings) are displayed next to the individual commands in the "ILISP Commands" section of the manual. I can think of three reasonable alternatives if we did decide to provide keybinding detail in the documentation: 1. Remove the "legacy" bindings from the "ILISP Commands" section so that the section contains only command descriptions. Then, add a table to the "Keybindings" section of the manual showing a list of the ILISP commands (grouped topically) with the corresponding "legacy" and "fsf" bindings. 2. Leave the "legacy" binding detail in the "ILISP Commands" section but add the "fsf" binding detail in there too. 3. Remove the "legacy" bindings from the "ILISP Commands" section so that the section contains only command descriptions. Then, create 2 separate reference cards (similar to ilisp-refcard.tex but with all commands) showing the ILISP commands and their keybindings. All of these would take a few hours work and I'm not convinced that they would provide substantially more value than just the "C-h m" listings.=20 Thoughts? -- Bill Clementson |
From: Bob R. <rog...@rg...> - 2003-07-17 01:25:16
|
From: "Clementson, Bill" <Bil...@jd...> Date: Wed, 16 Jul 2003 09:04:40 -0600 From: Bob Rogers on Tuesday, July 15, 2003 9:12 PM [snip] > Although I use C-h m frequently, I still find lists of > command bindings useful. Recall that C-h m lists bindings > alphabetically, with it's own rules for how to alphabetize > prefix combinations, so a cheat sheet that is topically > organized does have some value-added of its own. True, however, with the new fsf keybindings, the commands ARE grouped topically because of the 3-key keybindings (e.g. -- all the compile commands are grouped under "C-c C-k ...", all the eval commands are grouped under "C-c C-j ...", etc. OK, good; I hadn't checked. Though, of course, that's only one way to slice it; you could have all the operate-on-region commands, operate-on- definition commands, operate-on-buffer commands, etc. Not that doing it this way would necessarily be an improvement, and C-h m always has the advantage of being definitively up-to-date. [snip] > I would like to suggest a topically-organized index of > commands with key bindings. What I liked about the Web page > is that it showed all three sets of bindings -- original, old > FSF, and your proposal -- in parallel. We'd only need two now > -- "standard" and "traditional" -- but I think it's still a > good idea to document both, especially since switching > bindings modes in order to do "C-h m" is onerous. Why is (setq ilisp-*use-fsf-compliant-keybindings* t), "M-x run-ilisp", "C-h m" so onerous? That much of it isn't, but if you're trying to compare both sets side-by-side, that's only a small part of the picture. Especially if you are unfamilar enough with ilisp to discover that calling ilisp-bindings will rebuild them after resetting ilisp-*use-fsf-compliant-keybindings*; a newbie would have to start a second emacs. So, I'm not really convinced, but let's consider what the "optimal" way of presenting such a listing would be and then decide if the value of such a listing would be worth the effort to create it . . . All of these would take a few hours work and I'm not convinced that they would provide substantially more value than just the "C-h m" listings. Thoughts? -- Bill Clementson Personally, I would prefer the first, then the second, then the third, but I can't volunteer to help right now, so it's all your call. Sorry. -- Bob Rogers |
From: Clementson, B. <Bil...@jd...> - 2003-07-17 15:05:42
|
Hi Bob, [snip] > Personally, I would prefer the first, then the second, then=20 > the third, but I can't volunteer to help right now, so it's=20 > all your call. Sorry. Ok, I'll leave the documentation as it is for now. If it seems to be an issue in the future for people who are trying to use ILISP, I'll revisit the issue.=20 -- Bill Clementson |
From: Nikodemus S. <de...@ra...> - 2003-07-15 14:58:35
|
On Tue, Jul 15, 2003 at 08:30:35AM -0600, Clementson, Bill wrote: > My personal feeling is that the ILISP texi file shouldn't have any > keybindings in it at all - only commands. The "C-h m" output provides a > very good summary of the keybindings and commands and I refer to it when > I'm looking up keybindings rather than the documentation. However, that > is just my viewpoint. How do others feel about this? IMHO, the main value for keybinding documentation is easing the learning curve. =20 People who are new to both emacs and Common Lisp aren't in the most enviable of positions as it is: for them there is great value in being able to find keybindings by searching the documentation for such. ;) Also, during the early learning stages a list of keybindings is a good learning tool as it is pretty much equivalent to "frequently used commands". I've used emacs for a few years, but "C-h m" isn't something I yet do by reflex. I probably should, but I'm only bringing this up to illustrate that overcoming emacs-cluelessness is a long-term project for at least some of it's users. That said, I can most certainly understand you reluctance to maintain multiple sets of documentation... Hence I'd suggest mentioning the "C-h m" &co under "Keybindings" in the Ilisp documentation. Or maybe a "Short Guide to Developing with Ilisp" would be the correct solution. Cheers, -- Nikodemus |
From: Edi W. <ed...@ag...> - 2003-07-15 17:21:56
|
Nikodemus Siivola <de...@ra...> writes: > Or maybe a "Short Guide to Developing with Ilisp" would be the > correct solution. That would certainly be the best solution. AFAIK Bill is working on something like this. Edi. |
From: Bob R. <rog...@rg...> - 2003-07-16 03:13:17
|
From: Nikodemus Siivola <de...@ra...> Date: Tue, 15 Jul 2003 17:56:58 +0300 IMHO, the main value for keybinding documentation is easing the learning curve . . . Also, during the early learning stages a list of keybindings is a good learning tool as it is pretty much equivalent to "frequently used commands". I agree; think of it as a "cheat sheet," Bill. I've used emacs for a few years, but "C-h m" isn't something I yet do by reflex. I probably should, but I'm only bringing this up to illustrate that overcoming emacs-cluelessness is a long-term project for at least some of it's users. Although I use C-h m frequently, I still find lists of command bindings useful. Recall that C-h m lists bindings alphabetically, with it's own rules for how to alphabetize prefix combinations, so a cheat sheet that is topically organized does have some value-added of its own. That said, I can most certainly understand you reluctance to maintain multiple sets of documentation... Hence I'd suggest mentioning the "C-h m" &co under "Keybindings" in the Ilisp documentation. Or maybe a "Short Guide to Developing with Ilisp" would be the correct solution. I would like to suggest a topically-organized index of commands with key bindings. What I liked about the Web page is that it showed all three sets of bindings -- original, old FSF, and your proposal -- in parallel. We'd only need two now -- "standard" and "traditional" -- but I think it's still a good idea to document both, especially since switching bindings modes in order to do "C-h m" is onerous. -- Bob Rogers http://rgrjr.dyndns.org/ |