Re: Contacting Vim Tips Wiki Admin JohnBeckett

On Friday, November 9, 2012 9:50:40 PM UTC-6, Suresh Govindachar wrote:
>
> You have misunderstood the issue. No one is attempting to
> reconfigure vim in any way. No one is attempting to avoid the
> normal mode. It is just that while in insert mode, there is often a
> need to do something quick in normal mode and get back to insert
> mode -- the creator of Vim himself recognized this need and provided
> the feature of i_ctrl-o (:help i_ctrl-o). The mappings merely
> enhance Vim's built in feature of i_ctrl-o.
>

Good, you could mention this--in descriptive prose, not in a comment--in the tip
page itself.

>
> > The fundamental problem is that if someone has trouble going to
> > normal mode to navigate or massage text,
>
> No one has trouble going into normal mode to navigate or massage
> text. The point of that there are times, such as when a new
> document is being created, when one want to go to normal mode and
> come back to inset mode quickly.
>

I can see where that would make sense. It is very rare where most programmers
are able to start at the beginning of a document and just write code from start
to finish. And it is probably just as rare for me to write prose in Vim. The
idea of starting insert mode and just typing until the document is finished is
completely foreign to me but from my few long sessions in insert mode writing up
yearly reviews or even function header comments and the like, I can see why an
easy way to do one or two normal mode commands could be useful. CTRL-O can be
cumbersome.

> > At any rate, I would like the tip fixed so the concerns raised by
> > Fritzophrenic (who added the "dodgy" tag) are addressed. Then we
> > could add a note saying that some people like avoiding normal
> > mode, and some don't, and we could remove the comments and other
> > old stuff from the page.
>
> I do not see the name "Fritzophrenic" on the wiki page in question.
> By "the concerns raised by Fritzophrenic (who added the "dodgy"
> tag)" do you mean the following?:
>
> "Not enough explanation. What is the purpose of each set of
> mappings, and what do they accomplish? What problem is being
> solved?"
>
> The comments toward the top of the tip provide the motivation for
> the tip -- which would answer the question about "what do they
> accomplish" and "What problem is being solved?" The only thing I
> can think of adding is that the reader see :help i_ctrl-o since the
> tip enhances Vim's built in feature of i_ctrl-o. Regarding what
> each mapping does, there is a comment at the top of each group of
> mappings.
>

A reader of a wiki page should not be expected to study a script to see what it
does before they decide whether it is useful to them. They may as well download
code in a plugin with a name like thisisuseful.vim without knowing what it does.

You should add an explanation, in prose, of what the script is for. And the
script in question is really a series of unrelated mappings. Each group of
mappings should be described, and described in a way that is immediately obvious
what is meant. A code comment that says "numbers for repeats", for example, is
not at all obvious. What could be written instead is, "A single normal-mode
command can be executed with CTRL-O, but this can be awkward to type. Also, if
the command needs to be executed multiple times, you must enter a count before
the command. These mappings save a few keystrokes by supplying a count for you
corresponding to the key pressed."

Raw .vimrc dumps without explanatory text on the wiki are almost never useful,
even if their content is. Think of your explanatory text like the opening
paragraph on wikipedia. Before you get into the boring details, sum it up and
let people know why they should be interested. A header comment buried in the
script itself won't get read.

--
You received this message from the "vim_use" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php