[implementations-list] How important is a Vimpulse user manual? How to make one? Copy from Vim docs?
Vimpulse needs better documentation -- a better user manual, saying how to use all of its features. Look at the Viper info manual and see how great it is. Look at our documentation -- it's very incomplete. What can we do? Maybe we can copy text straight out of the Vim documentation for every single keystroke and feature that Viper or Vimpulse supports, then ship a series of .txt files containing our newly-cobbled-together documentation? We'd have to give proper copyright and license acknowledgment of course. And maybe we could use or write some software to do that copying, so that when Bram adds to the Vim documentation, we just type "make" and our documentation instantly will improve? Or must we ship Texinfo format instead? Should we get people who write patches to also include documentation in the patch, and say that if they don't, we won't accept their patches? What's doable? What's practical? What's the right thing to do? Then again, is it really so important for Vimpulse to have a user manual that tells users how to use its features? This is only important for people who went straight from using Emacs to using Vimpulse, and who have never used Vim. How common is that? How can we find out how common it is? Can we include a survey in the comments at the top of the next release of Vimpulse and ask people to fill it in, join the mailing list, and email it to the list? (This would also gain us lots of new list subscribers.)
From: [email protected] Date: Wed, 23 Dec 2009 22:54:20 -0500
Vimpulse needs better documentation -- a better user manual, saying how to use all of its features. Look at the Viper info manual and see how great it is. Look at our documentation -- it's very incomplete.
My view is that while Viper's manual is wonderfully comprehensive and wonderful in its comprehensiveness, it is not a good role model for Vimpulse. Vimpulse should be as no-nonsense as emacsly possible -- you load it up and start typing -- and along those lines, its documentation should be small, concise and straight to the point. This is just my view, of course, but I've googled a dozen accounts of how a Vim user would try the Emacs/Viper route, stumble onto some annoying inconsistency, and eventually give up on Emacs altogether. I therefore see as one of Vimpulse's main challenges to hold on to a new user for sufficiently long that they get "hooked" and maybe start exploring what amazingly cool things you can do when the underlying substrate consists of Emacs Lisp. Vim is a programmer's editor, in the true sense of that term. This is most apparent when looking up the documentation. The help files of a "popular" Windows editor like Notepad++ is full of friendly screenshots and easy-to-follow explanations of how you can perform a search and replace on your text in just six simple steps, but makes no mention at all of remapping the internals or tweaking cryptic variables. Vim's documentation has no pictures, but its level of detail is staggering, as seen when issuing ":help <BS>": [count] characters to the left. |exclusive| motion. Note: If you prefer <BS> to delete a character, use the mapping: :map CTRL-V<BS> X (to enter "CTRL-V<BS>" type the CTRL-V key, followed by the <BS> key) See |:fixdel| if the <BS> key does not do what you want. This is as no-nonsense as you can get. It is also overwhelmingly newbie-unfriendly. If you were to make a Vimpulse's User's Manual out of it, you wouldn't tell a Vim user anything they didn't know, nor a newbie anything they'd want to hear. What is it a Vim user doesn't know, then? Emacs, and Emacs Lisp. How to (setq ...) variables rather than :set them, how to tweak whatever needs tweaking, how to combine the power of Vim with the power of Emacs. All of this should be shown by example. When you've never used Lisp before, it is okay to copy and modify an expression without understanding completely how it works. But it mustn't be too overwhelming. At least not at first sight. Load it, tweak it, use it; the whole thing should be as transparent and straightforward as possible. To that end, maybe Vimpulse should load and configure Viper automatically, so that a single (require 'vimpulse) is sufficient to get started. I'm reminded of how Unix gained massive popularity not because it was consistent and complete, but because it was portable and practical. Vimpulse should at least be practical. Its documentation should be clear, example-loaded and straight to the point, and preferably some measures shorter than this e-mail, if possible. My two cents. :) _________________________________________________________________ Få nye Windows Live™ Messenger. http://download.live.com/messenger
On Sat, Dec 26, 2009 at 12:55:36AM +0000, Vegard Øye wrote:
Vim is a programmer's editor, in the true sense of that term. This is most apparent when looking up the documentation. The help files of a "popular" Windows editor like Notepad++ is full of friendly screenshots and easy-to-follow explanations of how you can perform a search and replace on your text in just six simple steps, but makes no mention at all of remapping the internals or tweaking cryptic variables. Vim's documentation has no pictures, but its level of detail is staggering, as seen when issuing ":help <BS>":
[count] characters to the left. |exclusive| motion. Note: If you prefer <BS> to delete a character, use the mapping: :map CTRL-V<BS> X (to enter "CTRL-V<BS>" type the CTRL-V key, followed by the <BS> key) See |:fixdel| if the <BS> key does not do what you want.
This is as no-nonsense as you can get. It is also overwhelmingly newbie-unfriendly. If you were to make a Vimpulse's User's Manual out of it, you wouldn't tell a Vim user anything they didn't know, nor a newbie anything they'd want to hear.
I strongly disagree -- IMO Vim documentation is very clear and useful both for beginners and long-time users, not newbie-unfriendly in any respect (if you really find the Reference Manual -- whence the above quotation -- too "unfriendly", there is also the wordier and more tutorial-like User Manual).
What is it a Vim user doesn't know, then? Emacs, and Emacs Lisp. How to (setq ...) variables rather than :set them, how to tweak whatever needs tweaking, how to combine the power of Vim with the power of Emacs. All of this should be shown by example. When you've never used Lisp before, it is okay to copy and modify an expression without understanding completely how it works.
For this, there are two Elisp manuals: The Emacs Lisp Reference Manual and A simple introduction to Emacs Lisp programming.
Date: Sat, 26 Dec 2009 12:12:34 +0100 From: [email protected]
I strongly disagree -- IMO Vim documentation is very clear and useful both for beginners and long-time users, not newbie-unfriendly in any respect (if you really find the Reference Manual -- whence the above quotation -- too "unfriendly", there is also the wordier and more tutorial-like User Manual).
I don't find it unfriendly, but I've used Vim for some time, and I was totally dependent on the Vim tutor to get started. Vim is famous for its steep learning curve,[1] and gaining the prerequisite knowledge is a time-consuming process, likely to be aborted unless the user is kept interested by some cool feature or otherwise indicator that the effort will be worth it. The same is true of Emacs. Today I feel Emacs' help system and general transparency is the best thing since sliced bread, but I didn't appreciate neither when I started out. [1] http://lca2srv30.epfl.ch/sathe/data/emacs_learning_curves.png :)
What is it a Vim user doesn't know, then? Emacs, and Emacs Lisp.
For this, there are two Elisp manuals: The Emacs Lisp Reference Manual and A simple introduction to Emacs Lisp programming.
Yes, and they are excellent, but they are also very comprehensive. They don't provide a quick way to get started, which is what the Vim user will be looking for. For my part, I only got around to reading the Introduction after a year or so of amateurish Lisp hacking and I finally decided that my hackery wasn't cutting it anymore, but up to that point -- and this is crucial -- my "hacker's approach" had been very effective. We need to let the newcomers get away with a few shortcuts and spark their interest before we hand out the 500-page manuals. _________________________________________________________________ Nye Windows 7: PCen som passer for deg. Finn ut mer. http://windows.microsoft.com/shop
On Fri, Dec 25, 2009 at 7:55 PM, Vegard Øye <[email protected]> wrote:
My view is that while Viper's manual is wonderfully comprehensive and wonderful in its comprehensiveness, it is not a good role model for Vimpulse. Vimpulse should be as no-nonsense as emacsly possible -- you load it up and start typing -- and along those lines, its documentation should be small, concise and straight to the point.
Yes. I did some work just now on simplifying INSTALL.
I've googled a dozen accounts of how a Vim user would try the Emacs/Viper route, stumble onto some annoying inconsistency, and eventually give up on Emacs altogether.
That's a serious problem. I bet it causes Vimpulse to lose users, and because of that, maybe it makes Vimpulse lose future developers too. (By the way, I bet bugs also cause such losses. Thanks for the bug-fixing work you've done.)
I therefore see as one of Vimpulse's main challenges to hold on to a new user for sufficiently long that they get "hooked" and maybe start exploring what amazingly cool things you can do when the underlying substrate consists of Emacs Lisp.
That's one possibility. Though there are other possibilities too. I don't remember for sure anymore, but I think what hooked me onto Viper is this: I had already been using Emacs, and realized that its Ctrl- and Ctrl-Shift-key combinations were unpleasant to type. So I switched to using Viper inside of Emacs.
Vim is a programmer's editor, in the true sense of that term. This is most apparent when looking up the documentation. [snip]
You're right. The Vim reference manual is very newbie-unfriendly. For another example, here's the help for :split. CTRL-W s *CTRL-W_s* CTRL-W S *CTRL-W_S* CTRL-W CTRL-S *CTRL-W_CTRL-S* :[N]sp[lit] [++opt] [+cmd] *:sp* *:split* Split current window in two. The result is two viewports on the same file. Make new window N high (default is to use half the height of the current window). Reduces the current window height to create room (and others, if the 'equalalways' option is set and 'eadirection' isn't "hor"). Note: CTRL-S does not work on all terminals and might block further input, use CTRL-Q to get going again. Also see |++opt| and |+cmd|. But Štěpán made a very good point elsewhere in this thread. We could copy from the user manual instead. It looks like this: *08.1* Split a window The easiest way to open a new window is to use the following command: :split This command splits the screen into two windows and leaves the cursor in the top one: +----------------------------------+ |/* file one.c */ | |~ | |~ | |one.c=============================| |/* file one.c */ | |~ | |one.c=============================| | | +----------------------------------+ What you see here is two windows on the same file. The line with "====" is that status line. It displays information about the window above it. (In practice the status line will be in reverse video.) The two windows allow you to view two parts of the same file. For example, you could make the top window show the variable declarations of a program, and the bottom one the code that uses these variables. The CTRL-W w command can be used to jump between the windows. If you are in the top window, CTRL-W w jumps to the window below it. If you are in the bottom window it will jump to the first window. (CTRL-W CTRL-W does the same thing, in case you let go of the CTRL key a bit later.) This manual is much friendlier.
What is it a Vim user doesn't know, then? Emacs, and Emacs Lisp. How to (setq ...) variables rather than :set them, how to tweak whatever needs tweaking, how to combine the power of Vim with the power of Emacs. All of this should be shown by example. When you've never used Lisp before, it is okay to copy and modify an expression without understanding completely how it works.
There is something called the guided tour of Emacs, by Phil Sung. I once found it by Googling for introductory Emacs material. The first part is mirrored in prose form somewhere at www.gnu.org, but you can see both parts at http://web.psung.name/emacs/. The first part of the tour is full of screenshots and shows the user screenshots of or information about: * ediff * shell-mode * gdb-mode * Gnus * isearch * TRAMP * VC mode * the programming-language-specific modes like the Python mode and HTML mode * C-h k, C-h f, C-h m, C-h b, C-h a, and how to get into the online manual * C-g to cancel commands The second talks about elisp. Once I requested that the tour be added to the GNU Emacs splash screen, and they added it. More recently, at http://emacsbugs.donarmstrong.com/4960 I requested that this be added to the GNU Emacs Help menu, just like in XEmacs. But nothing has happened yet. It seems to me that it would be excellent if all Vimpulse users were encouraged to look at the tour, no? If so, what's the best way to encourage this?
But it mustn't be too overwhelming. At least not at first sight. Load it, tweak it, use it; the whole thing should be as transparent and straightforward as possible.
This is a very good idea. I'm assigning you three feature requests based on this idea. :) If they sound like ideas you don't want to do because they're not important to you, then please reassign them to Alessandro. If they sound like ideas you don't want to do because they're not good ideas, then reassign them to me and say "Patches welcome". I'm unlikely to write a patch; but this will get those feature requests off your "My issues" list.
I'm reminded of how Unix gained massive popularity not because it was consistent and complete, but because it was portable and practical. Vimpulse should at least be practical. Its documentation should be clear, example-loaded and straight to the point,
Yes.
and preferably some measures shorter than this e-mail, if possible.
Maybe :)
From: [email protected] Date: Mon, 28 Dec 2009 15:30:28 -0500
Vimpulse should be as no-nonsense as emacsly possible -- you load it up and start typing -- and along those lines, its documentation should be small, concise and straight to the point.
Yes. I did some work just now on simplifying INSTALL.
Great!
(By the way, I bet bugs also cause such losses. Thanks for the bug-fixing work you've done.)
You're welcome. :)
I don't remember for sure anymore, but I think what hooked me onto Viper is this: I had already been using Emacs, and realized that its Ctrl- and Ctrl-Shift-key combinations were unpleasant to type. So I switched to using Viper inside of Emacs.
This is often referred to as the "Emacs pinky" problem, but I don't think it's Emacs specific, having done careful comparisons with other mature editors like TextMate, jEdit and SlickEdit. Guess what I found? They all suffer from the same Ctrl-Shift-Alt clutter. The simple fact is that if the editor is non-modal, keyboard-oriented and rich in features, overloading of the modified keys is just inevitable. It's not a matter of "bloat", either; yes, Emacs bundles Tetris, but it doesn't make a key binding for it. (For that matter, tetris.el is autoloaded, so the "bloat" charge doesn't really apply.) The paradoxical truth is that it is feature-heavy Emacs, often touted as the arch-enemy of modal editor Vim in an epic "editor war", which would benefit the most from a modal interface.
You're right. The Vim reference manual is very newbie-unfriendly. ... But Štěpán made a very good point elsewhere in this thread. We could copy from the user manual instead. ... This manual is much friendlier.
Very much so, but also a longer read, necessarily. I think all documentation, no matter who it's targeted at, is subject to the following restriction: "friendly, concise, detailed -- pick two". That is, it may be concise and detailed, but not friendly, like Vim's Reference Manual; friendly and detailed, but not concise, like the Introduction to Emacs Lisp (and the Lisp Reference Manual); or friendly and concise, but not detailed, like a Quick Starter's Guide. If exceptions exist, they are products of exceptional skill and effort. I'm a natural long-winded writer, myself. So maybe our documentation will need to be two-fold: a quick starter's guide, with (require 'vimpulse) and some Emacs pointers, and a more complete reference manual, showing how to tweak variables with `setq'. The former would be friendly and concise, the latter friendly and detailed. I don't think there's a place for concise and detailed, except maybe in source code comments.
There is something called the guided tour of Emacs, by Phil Sung. ... http://web.psung.name/emacs/ ... It seems to me that it would be excellent if all Vimpulse users were encouraged to look at the tour, no? If so, what's the best way to encourage this?
It's a nice overview, and HTML-based to boot, which I consider a huge plus. Every Vimpulse user is going to need a little Emacs knowledge at some point, so a careful selection of good introductions is definitely valuable. At the same time, I think stand-alone Viper requires too much knowledge too early: for instance, there's no h/j/k/l navigation in the help buffers, as Viper disables itself in a number of cases to avoid overriding special keymaps. I suggest Vimpulse slightly augment these keymaps with basic vi navigation (but without overwriting anything) to avoid infinite recursion: "vi keys don't work in Help, use Emacs keys instead. To learn Emacs keys, use the Help system."
Load it, tweak it, use it; the whole thing should be as transparent and straightforward as possible.
This is a very good idea. I'm assigning you three feature requests based on this idea. :)
I'll look at them in time, after I've done away with some more of the older tickets. Vegard _________________________________________________________________ Windows 7: Se direkte-TV fra den bærbare PCen. Finn ut mer. http://windows.microsoft.com/windows-7
On Tue, Dec 29, 2009 at 2:49 PM, Vegard Øye <[email protected]> wrote: [snip]
This is often referred to as the "Emacs pinky" problem, but I don't think it's Emacs specific, having done careful comparisons with other mature editors like TextMate, jEdit and SlickEdit. Guess what I found? They all suffer from the same Ctrl-Shift-Alt clutter. The simple fact is that if the editor is non-modal, keyboard-oriented and rich in features, overloading of the modified keys is just inevitable. [snip] The paradoxical truth is that it is feature-heavy Emacs, often touted as the arch-enemy of modal editor Vim in an epic "editor war", which would benefit the most from a modal interface. [snip]
Wow. I like your analysis a lot.
At the same time, I think stand-alone Viper requires too much knowledge too early: for instance, there's no h/j/k/l navigation in the help buffers, as Viper disables itself in a number of cases to avoid overriding special keymaps. I suggest Vimpulse slightly augment these keymaps with basic vi navigation (but without overwriting anything) to avoid infinite recursion: "vi keys don't work in Help, use Emacs keys instead. To learn Emacs keys, use the Help system." [snip]
I think people can just use the arrow keys and Enter in Info mode. :)
From: [email protected] Date: Wed, 10 Feb 2010 03:52:13 -0500
I think stand-alone Viper requires too much knowledge too early: for instance, there's no h/j/k/l navigation in the help buffers, as Viper disables itself in a number of cases to avoid overriding special keymaps.
I think people can just use the arrow keys and Enter in Info mode. :)
Yes. But to the seasoned Vim user with his hands at the home row, the annoyance will be there. (If you're going to use Vim keys in Emacs, you're probably somewhat seasoned. :) Anyway, I added some utility code to vimpulse-misc-keybindings.el in changeset [58] to address this in time. The idea is that there are two forms of vi navigation: the "core" commands, like h/j/k/l, and the rest. The core commands should, in general, be available in every mode, even if this means overwriting the mode's own bindings for these keys. On the other hand, the rest of the vi navigation commands -- w, e, b, f, etc. -- are optional: they are only added if their keys don't already do something else. Thus w may move forward by words or it may not, while h always moves one character to the left, no matter what. The code is smart enough that if you have rearranged the vi bindings (perhaps to use a different keyboard layout), this is duplicated when the commands are bound in the various modes. I'll put it to work soon. Vegard _________________________________________________________________ Windows 7: Se direkte-TV fra den bærbare PCen. Finn ut mer. http://windows.microsoft.com/windows-7
participants (3)
-
Jason Spiro -
Vegard Øye -
Štěpán Němec