[implementations-list] How important is a Vimpulse user manual? How to make one? Copy from Vim docs?

Tue Dec 29 20:49:13 CET 2009

> From: jasonspiro3 at gmail.com
> 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