How to use :help?

[Niels Kobschaetzki]

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.

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". And this is just one example. Other examples would include
the .-command, gq to break lines anew to fit the set character width, or
showcmd (:h show command or :h showcommand won't find anything, only :h
showcmd). But there is certainly more.

Niels

[glts]

Read ':h help-summary' for an overview of what the :help command can do.

My method for looking for help on an unknown topic is typing

:h word

followed by CTRL-D. This pops up a listing of topics containing "word".
I glance over the listing until I find an entry that looks promising,
else I'll try another "word" plus CTRL-D.

Cheers,


--
David

[Erik Christiansen]

On 13.09.15 12:03, Niels Kobschaetzki wrote:
> 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.

Having used Vi/Vim for a couple of decades now, I have to concur. Unless
you already know precisely what you're looking for, by name, the help
system really isn't much help. For myself, I've accumulated 31 pages of
memory-jogging Vim notes - a scattering of reminders incompletely
covering stuff I use, including the :h codes to find the relevant help.
As a last resort, though, just ask the list; there's always someone in
the community who knows. (Maybe there are others with lists. ;-)

For completely unknown stuff, browsing the various webpages is good. A
Vim book might be good for basics. But I'm happy enough with what
appears over time on this list. For example, my 430 pages of software
notes became a little unruly over a couple of decades of growth, but
since learning of the existence of folding, I've been able to improve
the structure significantly.

The problem isn't unique to Vim, though. Try manpages w.r.t. unix
commands you've never heard of.

Erik

--
Telephone books are like dictionaries -- if you know the answer before
you look it up, you can eventually reaffirm what you thought you knew
but weren't sure. But if you're searching for something you don't
already know, your fingers could walk themselves to death.
- Erma Bombeck

[Tony Mechelynck]

Yes, and in addition, read the whole of the helphelp.txt file (":h
helphelp" or ":h helphelp.txt"). It explains in detail the various
ways to get help. Here are a few examples:

:help blabla<Ctrl-D>
list all help subjects containing the string "blabla"

With +wildmenu compiled-in and 'wildmenu' set to TRUE,
:help blabla<Tab>
gives you on the status line a menu of those same help subjects. Left
and right arrows navigate the menu, <Enter> accepts, <Esc> cancels.
Fine control with the 'wildmode' option.

With +quickfix compiled-in,
:helpgrep pattern
searches the whole help for anything matching the given pattern (which
is given as a search pattern, but not between slashes).

For use with :helpgrep (and with any quickfix commands), I recommend
the following mappings; vary the {lhs} to taste:
:map <F5> :cnext<CR>
:imap <F5> <C-O>:cnext<CR>
:map <S-F5> :cprev<CR>
:imap <S-F5> <C-O>:cprev<CR>
:map <F6> :cnfile<CR>
:imap <F6> <C-O>:cnfile<CR>
:map <S-F6> :cpfile<CR>
:imap <S-F6> <C-O>:cpfile<CR>
and maybe, if you don't need the keys for mappings you use more often,
:map <F7> :cfirst<CR>
:imap <F7> <C-O>:cfirst<CR>
:map <S-F7> :clast<CR>
:imap <S-F7> <C-O>:clast<CR>
The reversal of direction of these last two is in order to always use
the unshifted key for the more used command.

These mappings are explained in
:help map.txt
:help keycodes
:help quickfix.txt
:help i_CTRL-O


Best regards,
Tony.

[Christian Brabandt]

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

[Christian Brabandt]

Hi vim_use!

On So, 13 Sep 2015, Christian Brabandt wrote:

> 1) Options generally are enclosed in single parenthesis. So you would

not parenthesis but apostrophes.

Best,
Christian
--
Hinter jedem großen Mann steckt eine Frau, die ihn dressiert hat.

[Niels Kobschaetzki]

On 13/09 15:01, Christian Brabandt wrote:
>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.

<snip lots of help>

Thanks a lot Christian, Erik and Tony for your mails (and especially for
the really detailed one).

Niels

[Elimar Riesebieter]

* Christian Brabandt <cbl...@256bit.org> [2015-09-13 15:01 +0200]:

> 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

[...]

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

Shouldn't those point be placed on https://vim.wikia.com/ or
https://github.com/vimwiki/vimwiki ?

Elimar
--
You cannot propel yourself forward by
patting yourself on the back.

[Ben Fritz]

On Monday, September 14, 2015 at 3:41:13 AM UTC-5, Elimar Riesebieter wrote:
> >
> > 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
> [...]
> > 20) compiled extra features always start with "+" so :h +conceal
> > talks about the conceal support
>
> Shouldn't those point be placed on https://vim.wikia.com/ or
> https://github.com/vimwiki/vimwiki ?
>

http://vim.wikia.com/wiki/Learn_to_use_help

[Elimar Riesebieter]

* Ben Fritz <fritzo...@gmail.com> [2015-09-14 08:04 -0700]:

> On Monday, September 14, 2015 at 3:41:13 AM UTC-5, Elimar Riesebieter wrote:

[...]>

> > 1) Options generally are enclosed in single parenthesis. So you would
> > [...]
> > > 20) compiled extra features always start with "+" so :h +conceal
> > > talks about the conceal support
> >
> > Shouldn't those point be placed on https://vim.wikia.com/ or
> > https://github.com/vimwiki/vimwiki ?
> >
>
> http://vim.wikia.com/wiki/Learn_to_use_help

Mostly ;-)

Elimar
--
Alles was viel bedacht wird ist bedenklich!;-)
Friedrich Nietzsche

[Christian Brabandt]

Additionally,

21) Error codes can be looked up directly in the help. So :h E297
takes you exactly to the description of the error message.
Sometimes however, those error codes are not described, but
rather are listed at the vim command, that usually causes this.
So E128 takes you directly to the :function command

22) Documentation for included syntax files is usually
available at :h ft-<filetype>-syntax.
So :h ft-c-syntax talks about the C syntax file and the option
it provides. Sometimes, additional section for omni completion
(:h ft-php-omni) or filetype plugins (:h ft-tex-plugin) is available

If someone wants to merge this into a wiki, feel free to do so.


Best,
Christian

[George Dinwiddie]

Erik,

On 9/13/15 7:31 AM, Erik Christiansen wrote:
> The problem isn't unique to Vim, though. Try manpages w.r.t. unix
> commands you've never heard of.

The command 'apropos' is your friend. :-)

- George

--
----------------------------------------------------------------------
* George Dinwiddie * http://blog.gdinwiddie.com
Software Development http://www.idiacomputing.com
Consultant and Coach http://www.agilemaryland.org
----------------------------------------------------------------------

[Gevisz]

On Tue, 15 Sep 2015 12:24:13 -0400 George Dinwiddie <li...@iDIAcomputing.com> wrote:

> Erik,
>
> On 9/13/15 7:31 AM, Erik Christiansen wrote:
> > The problem isn't unique to Vim, though. Try manpages w.r.t. unix
> > commands you've never heard of.
>
> The command 'apropos' is your friend. :-)

Just looked in 'man apropos' and tried 'apropos mount'

It does not work. Can you, please, provide an example.

[Niels Kobschaetzki]

When I use "apropos mount", I get this output:

ecryptfs-add-passphrase (1) - add an eCryptfs mount passphrase to the kernel keyring.
ecryptfs-mount-private (1) - interactive eCryptfs private mount wrapper script.
ecryptfs-recover-private (1) - find and mount any encrypted private directories
ecryptfs-umount-private (1) - eCryptfs private unmount wrapper script.
ecryptfs-unwrap-passphrase (1) - unwrap an eCryptfs mount passphrase
from file.
ecryptfs-wrap-passphrase (1) - wrap an eCryptfs mount passphrase.
encfs (1) - mounts or creates an encrypted virtual filesystem
free (1) - Display amount of free and used memory in the system
fstrim (8) - discard unused blocks on a mounted filesystem
fusermount (1) - mount and unmount FUSE filesystems
gnome-disk-image-mounter (1) - Attach and mount disk images
grub-mount (1) - export GRUB filesystem with FUSE
gvfs-mount (1) - Mounts the locations
ideviceimagemounter (1) - Mount disk images on the device.
mklost+found (8) - create a lost+found directory on a mounted Linux second extended file system
mount (2) - mount filesystem
mount (8) - mount a filesystem
mount.ceph (8) - mount a ceph file system
mount.cifs (8) - mount using the Common Internet File System (CIFS)
mount.ecryptfs (8) - eCryptfs mount helper.
mount.ecryptfs_private (1) - eCryptfs private mount helper.
mount.exfat-fuse (8) - mount an exFAT file system
mount.fuse (8) - format and options for the fuse file systems
mount.lowntfs-3g (8) - Third Generation Read/Write NTFS Driver
mount.nfs (8) - mount a Network File System
mount.nilfs2 (8) - mount a NILFS2 file system
mount.ntfs-3g (8) - Third Generation Read/Write NTFS Driver
mountd (8) - NFS mount daemon
mountpoint (1) - see if a directory or file is a mountpoint
mountstats (8) - Displays various NFS client per-mount statistics
nfsiostat (8) - Emulate iostat for NFS mount points using
/proc/self/mountstats
nfsmount.conf (5) - Configuration file for NFS mounts
ntfs-3g.probe (8) - Probe an NTFS volume mountability
open-fuse-iso (1) - mount or unmount image files
rpc.mountd (8) - NFS mount daemon
setup (2) - setup devices and filesystems, mount root
filesystem
showmount (8) - show mount information for an NFS server
sleep (1) - delay for a specified amount of time
switch_root (8) - switch to another filesystem as the root of the
mount tree
systemd-gpt-auto-generator (8) - Generator for automatically discovering and mounting root, /home and /srv partitions, as well as discovering and enabling swap partitions, based o...
systemd-remount-fs (8) - Remount root and kernel file systems
systemd-remount-fs.service (8) - Remount root and kernel file systems
systemd.automount (5) - Automount unit configuration
systemd.mount (5) - Mount unit configuration
Tcl_FSMountsChanged (3) - procedures to interact with any filesystem
umount (2) - unmount filesystem
umount (8) - unmount file systems
umount.ecryptfs (8) - eCryptfs umount helper.
umount.ecryptfs_private (1) - eCryptfs private unmount helper.
umount.nfs (8) - unmount a Network File System
umount.nilfs2 (8) - unmount NILFS2 file systems
umount.udisks2 (8) - unmount file systems that have been mounted by
udisks
umount2 (2) - unmount filesystem
xfs (5) - layout, mount options, and supported file attributes for the XFS filesystem



Niels

[Cedric Bhihe (毕生泰)]

What system are you on ?
You must be missing something basic in yr system, if `apropos mount' return a blank.
Try `which apropos' at the prompt.  `apropos' is located at /ust/bin/apropos.
In *nix environments the `apropos [keyword]' cmd yields the exact same results as the cmd `man -k [keyword]'
Compare`apropos mount' and `man -k mount'.

-- This is definitely _off-topic_. Look up StackExchange for further questions on that. I'll be glad to answer you there.

Cédric
GMT+1

---

[Erik Christiansen]

On 16.09.15 11:28, Gevisz wrote:
> Just looked in 'man apropos' and tried 'apropos mount'
>
> It does not work. Can you, please, provide an example.

The "apropos" command is the same as "man -k".
Here, both give 27 hits for "mount".
You'll need to diagnose the problem at your end.

Erik

[Gevisz]

$ apropos mount
mount: nothing appropriate

$ which apropos
/usr/bin/apropos

$ which man
/usr/bin/man

$ man -k mount
mount: nothing appropriate

The last is really strange as I used this command before (but not in Gentoo).

Thank you for explanation.

[Gevisz]

Strange enough but I have only this:

[Gevisz]

On Wed, 16 Sep 2015 10:50:54 +0200 Cedric Bhihe (毕生泰) <cedric...@gmail.com> wrote:

> On 16/09/15 10:28, Gevisz wrote:
> > On Tue, 15 Sep 2015 12:24:13 -0400 George Dinwiddie <li...@iDIAcomputing.com> wrote:
> >
> >> Erik,
> >>
> >> On 9/13/15 7:31 AM, Erik Christiansen wrote:
> >>> The problem isn't unique to Vim, though. Try manpages w.r.t. unix
> >>> commands you've never heard of.
> >> The command 'apropos' is your friend. :-)
> > Just looked in 'man apropos' and tried 'apropos mount'
> >
> > It does not work. Can you, please, provide an example.
> >
> What system are you on?

Sorry, I thought that I am replying to gentoo-user. Really.

I am using Gentoo, default/linux/amd64/13.0/desktop/gnome profile,
though gnome has long ago been ditched in favor of xfce4.

> You must be missing something basic in yr system, if `apropos mount'
> return a blank.
> Try `which apropos' at the prompt. `apropos' is located at
> /ust/bin/apropos.

Not exactly blank but

$ apropos man
man: nothing appropriate

$ which apropos
/usr/bin/apropos

> In *nix environments the `apropos [keyword]' cmd yields the exact same
> results as the cmd `man -k [keyword]'
> Compare`apropos mount' and `man -k mount'.

I know the 'man -k' command but it gives the same result here, what is strange.

> -- This is definitely _off-topic_.

Yes, for vim_use mailing list, it is indeed off topic.

I really thought that I am answering to gentoo-user.

> Look up StackExchange for further questions on that. I'll be glad to answer you there.
>

> *Cédric*
> /GMT+1/
> ------------------------------------------------------------------------
>

[Erik Falor]

For posterity's sake,

apropos(1), man -k and whatis(1) all consult the `whatis' database.
You may create this database with the makewhatis(1) command.

On Gentoo these are all a part of the sys-apps/man package.

Cheers
--
Erik Falor
Registered Linux User #445632 http://unnovative.net

[Gevisz]

Thank you.