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

[Jason Spiro]

On Fri, Dec 25, 2009 at 7:55 PM, Vegard Øye <vegard_oye at hotmail.com> 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 :)