Re: How to use :help?

Hi Niels!

On So, 13 Sep 2015, Niels Kobschaetzki wrote:

> Hi,
>
> I read quite often "just use the help" or recently on the list "don't
> use google, use :help". But how do I "use" it? When I want to know if
> something is possible in vim, I never figured out how to search for it
> because I always got the feeling that I need at least to know what
> something is called to be able to find it in the first place in the
> help.

If you know what you are looking for, it is usually easier to search for
it using the help system. Because the subjects follow a certain style
guide.

Also the help has the advantage, of belonging to your particular vim
version (well, usually), so that obsolete topics or topics that have
been added later won't turn up.

Therefore, it is essential to learn the help system and the language it
uses. Here are some examples (not necessarily complete and I might have
forgotten something).

1) Options generally are enclosed in single parenthesis. So you would
use :h 'list' to go to the help topic for the list option. If you
only know, you are looking for a certain option, you can also do :h
options.txt to open the help page which describes all option handling
and then you can search using regular expressions e.g. textwidth
Certain options have their own namespace, e.g. :h cpo-letter (for the
corresponding flag of the 'compatible" setting) or :h go-letter (for
the guioption flags).

2) normal mode commands are just that. User :h gt to go to the help page
for the "gt" command

3) regexp items always start with / So :h /\+ takes you to the help item
for the "\+" quantifier in Vim regexes. If you need to know anything
about regular expressions, start reading at :h pattern.txt

4) Key combinations. They usually start with a single letter indicating
the mode for which they can be used. E.g. :h i_CTRL-X takes you to
the family of Ctrl-X commands for insert mode which can be used to
auto complete different things. Note, that certain keys will always
be written the same, e.g. Control will always be CTRL.
Note, for normal mode commands, the 'n' is left away and the topic is
available at :h CTRL-Letter.
In contrast :h c_CTRL-R will describe what the Ctrl-R does when
entering commands in the Command line and :h v_Ctrl-A talks about
incrementing numbers in visual mode and :h g_CTRL-A talks about the
g<C-A> command (e.g. you have to press "g" then <Ctrl-A>). Here the
"g" stand for the normal command "g" which always expect a second key
before doing something similar to the commands starting with "z"

5) Registers always start with quote so use :h quote: to find out about
the special ":" register.

6) Vim Script (VimL) is available at :h eval.txt Certain aspects of the
language are available at :h expr-X where 'X' is a single letter,
e.g. :h expr-! will take you to the topic describing the '!' (Not)
operator for VimScript.
Also important :h function-list to find a short description of all
functions available.

7) mappings are talked about in the help page :h map.txt Use :h
mapmode-i to find out about :imap command. Also use :map-topic to
find out about certain subtopics particular for mappings (e.g. :h
:map-local for buffer-local mappings or map_bar for how the '|' is
handled in mappings.

8) Command definition are talked about :h command-topic so use
:h command-bar to find out about the '!' argument for custom
commands.

9) Window management commands always start with CTRL-W, so you find the
corresponding help at :h CTRL-W_letter (e.g. CTRL-W_p for moving the
previous accessed window). You can also access :h windows.txt and
read your way through if you are looking for window handling command.

10) Ex-commands always start with ":", so :h :s covers the :s command

11) use Ctrl-D after typing a topic and let Vim try to complete to all
available topics.

12) :helpgrep to search in the entire help pages (and also of any
installed plugins). See :h :helpgrep for how to use it.
Once you have searched for a topic, all matches are available in the
quickfix (or locationlist) window which can be opened with :copen or
:lopen. You can search there to (so you could search there for
options.txt to only find matches that talk about options and
settings).

13) :h helphelp contains some information on how to use the help.

14) The user manual. This describes help topics for beginners in a
rather friendly way. Start at :h usr_toc.txt to find the table of
content (as you might have guessed). Skimming over that help finding
certain topics, .e.g you will find an entry "Digraphs" and "Entering
special characters" in chapter 24 (so use :h usr_24.txt to go to
that particular help page).

15) highlighting groups. Always start with hl-groupname. E.g.
:h hl-WarningMsg talks about the WarningMsg highlighting group

16) syntax highlighting is namespaced to :syn-topic e.g. :h :syn-conceal
talks about the conceal argument for the :syn command.

17) quickfix commands usually start with :c while location list commands
usually start with :l

18) :h BufWinLeave talks about the BufWinLeave auto command. Also
:h autocommands-events talks about all possible events.

19) Startup arguments always start with "-" So :h -f takes you to the
help of the -f command switch of Vim.

20) compiled extra features always start with "+" so :h +conceal
talks about the conceal support

Also a link to the user documentation (which describes certain commands
more from a user perspective and less detailed) will be mentioned at the
top of help pages if they are available. So :h pattern.txt mentions the
user guide topics 03.9 and 27

> For example digraphs. I didn't know that this function exists. I read
> about it in "Practical Vim" by Drew Neil (btw best vim-book out there
> imho) and then I could use ":help digraphs" to find the characters I
> need. But before that I relied on copy and paste from character tables
> and stuff like that. How could I have found out about digraphs with the
> help-function without knowing that they exist? ":help special
> characters" doesn't find anything, also ":help insert special
> characters".

help tags work with single words, so often topics are abbreviated. You
could have used :helpgrep special characters and then open the quickfix
window and search for usr_ you will soon see "Entering special
characters" at usr_24.txt

Best,
Christian
--
Jeder Mensch hat seinen individuellen Aberglauben, der ihn bald im
Scherz, bald im Ernst leitet.
-- Georg Christoph Lichtenberg, Sudelbücher

--
--
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

---
You received this message because you are subscribed to the Google Groups "vim_use" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vim_use+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.