I hoped someone had emphasized the importance of :help to me. The Vim Help manual may not be hard to discover. One may just press "F1" to open it up. However, the flood of information made it hard to realize that a dictionary-like document is the most valuable user guide.

Many experiences reading manuals (including the electric appliances) showed that words and language styles are unique. Maybe it is the most concise, least ambiguous way of discussing the product among users. That is the reference users would agree to use the terms to refer to something.

I still learn a lot by reading random pieces in the Vim manual during my daily jobs.

As a newcomer to Vim, I struggled to learn because of disjointed tutorials and nomenclature like register, text-object, mode, buffer, and filetype. These terms are Vim's unique context. Actually, I agree the language style in Vim is kind of discouraging. May it be an insignificant point, learners actually need to adapt their thinking modes to the linguistics of the manual.

Preliminaries

I agree that a new Vimer should start with shorter articles/tutorials and so did I. There are plenty of online sources. There’s no specific order to learn Vim parts, as they interrelate. At the least, if one can

  • use command mode with : colon
  • move around with hjkl
  • use command :q to quit

He is equipped to start reading the manual.

Practice is the key.

Organization

Browsing in the Vim manual is like the experience on web pages. The structure of the manual is also in Tree. The "help.txt" is the root page similar to "index.html." When surfing inside a page, use "Control+]" (<C-]>) to jump to the subject (which is highlighted) like the hyperlinks in HTML. And use "Control+o" (<C-o>) to jump back to previous locations (Stack-like data structure).

There are a lot of entries inside the root of the help page, some of which are particularly helpful to get acquainted with Vim daily operations:

  • :help tutor or :Tutor, recommended by many people.
  • :help quickref, :help user-manual, quite comprehensive guide as well.
  • :help motion, moving around text objects, line-wise movement, scrolling
  • :help pattern, the searching Vim supported, besides REGEX
  • :help buffer, :help window, :help tagpage, :help session, the cognitive hierarchy using Vim with documents. Good to pay attention to it
  • :help vimscript, :help vimscript-functions, :help eval, advanced and good for customization and configuration logic.
  • :help local-additions, the extra help manuals from plugins

All the listed topics are available on the root help page. You can scroll, search, or simply use :help topic to explore them. After reading the manual, I discovered that I was learning it more quickly and naturally.

How does the :help topic work? I guess it is done with tagging and word matching.

Moving Around

Mouse-clicking and hopping around are not commonly used in Vim. Users often prefer to perform exact or partial keyword matches, REGEX searches, fuzzy searches, or even directory-scoped full-text searches. Different search involves different text algorithms.

  • To quickly reach specific topics (but one needs to remember the keyword correctly), :help topic is the way to jump to that subject. Note that the subjects can be for different contexts, it comes with prepends like "i_", "v_", ":"
    • For example <C-u> (or ^u) is a keymap/shortcut/short key appearing in both normal and insert mode. To look up their functions, one needs to :help CTRL-U for normal mode, it is about scrolling. However, in insert mode, one needs to :help i_CTRL-U instead, it is about deleting all entered characters before the cursor.
    • For more information, see :help help-context. Other prepend symbols exist for different contexts. For example, : denotes a command-related context. The second colon in :help :help states, "I want to look up the help command."
  • One can use gO to open the "table of contents" panel.
  • The parts of the manual are actually different .txt files. One can use :Ex to browse the actual text files of the manuals
  • The search command / functions similarly to "Control-F" or "Cmd-F" in Windows applications. Searching for text in different contexts is essential when considering and coding in the Vim style.
  • helpgrep keyword: If someone forgets the exact subject or only partially recalls certain words from a passage, "helpgrep" serves as a tool to help retrieve that information.

Tips

The :help (or just :h subject) or "F1" keys open the Vim manual in a new horizontally split window. I don't prefer this because the screen is wide; splitting in verticality looks more natural to me. Also, the help text is formatted in fixed text width. Horizontal split is a waste of screen space when displaying the manual text.

Therefore, :vert help can be a remedy. But it can be too much typing. It would be nice if help is opened vertically with fixed window width. One can add the following into his .vimrc config (like the .bashrc) as like:

augroup made_vertical
  autocmd!
  autocmd FileType help,netrw
        \ setlocal bufhidden=unload |
        \ wincmd H |
        \ vertical resize 79 |
        \ if match(expand("<amatch>"),'\(help\|netrw\)') != -1| setlocal wfw | endif
augroup END

The above auto-command targets new window which the file type is "help" or "netrw" automatically. wincmd H put the new window to the leftmost side and vertical resize 79 set the width of the new window.

Ending

No other place provides more comprehensive information about using Vim than the Vim manual.

The Vim manual has encouraged me to stay with text documents from the native (first party) for coding/learning tasks.

What’s your perspective? Is LLM the superior choice? LLM effectively integrates direct text context into its language, which users perceive as fluent, capable, authoritative, and empathetic. It is an amazing job in no doubt, and I like it too. However, depending solely on LLM, I worry that I may never truly grasp the original essence of the word expressions. Familiarity with the original Vim manual taught me a better Vimer.

Your thoughts...