Suppose :h {subject} results in multiple matches for the tag {subject}.

The :h entry says that the "best" match will be used, which is not very useful, If I don't know exactly what to search for.

How can I see a complete list of the matches and cycle through them?

:h[elp] {subject}   Like ":help", additionally jump to the tag {subject}.
            For example:  >
                :help options

<           {subject} can include wildcards such as "*", "?" and
               :help z? jump to help for any "z" command
               :help z. jump to the help for "z."
            But when a tag exists it is taken literally:
               :help :? jump to help for ":?"

            If there is no full match for the pattern, or there
            are several matches, the "best" match will be used.
  • to make sure to find the relevant help entry, have a look at :h help-summary – Christian Brabandt Jul 15 '20 at 9:39
  • 1
    @BLayer Yeah, also have a look here (which I guess technically answers the question): github.com/vim/vim/blob/master/runtime/doc/… – Christian Brabandt Jul 15 '20 at 9:44
  • @ChristianBrabandt Indeed, it looks like that's two ways to do the same thing. Which is kind of cool. Knowing you you're not planning on writing an answer :) in which case I'll mention next to the tab completion stuff your discovery as an alternate approach. – B Layer Jul 15 '20 at 9:58
  • (I'm holding off, though, until I hear back from you. Don't want to assume too much.) – B Layer Jul 15 '20 at 10:07
  • @BLayer sure, please go ahead :) – Christian Brabandt Jul 15 '20 at 11:03

With basic :help the best you can do is use Tab completion once you've entered your search term or a part thereof (but before hitting Enter). That will show some matching options and you can use Tab to move to whatever interests you. This is somewhat limited, though, since the submitted term must be recognized by Vim as sufficiently close to one or more real tags.

On a related note, Christian Brabandt made an interesting discovery that hews closer to a direct answer to how one can "cycle through tags matching :h {subject}. The steps are...

If there are several matches for an item you are looking for, this is how you can jump to each one of them:

  1. Open a help window
  2. Use the ":tag" command with a slash prepended to the tag. E.g.: > :tag /min
  3. Use :tnext to jump to the next matching tag.

There is no direct link to this text in help but you can jump to a point 20 lines above it with :h :viu

Don't forget the slash. Without it the string is interpreted literally and will match either one tag name or none. With a slash it is interpreted as a pattern and you can specify a regular expression that matches multiple tags. (Per :h tag-regexp)

I got curious about the source of these "several" matches and how they relate to the tab-completion entries discussed above. I tried both approaches with the same term and as far as I can tell they expand to the exact same set of related terms (though they're ordered differently). Which approach you use really depends on how much confidence you have in your term/tag as well as your personal preference.

Speaking of confidence in a term/tag...

One thing you can do to improve your odds of choosing a valid tag when you use :help is to get familiar with how the tags are named. They follow a well-defined pattern as described in :help help-summary. Beyond that, though, there's a command better suited for cases when you're just not sure of what term to use...

Use :helpgrep {pattern} and that will search all help text using the pattern. Results will be listed in so-called "quickfix" form. That means the list will be displayed in a new window which you can scroll through and jump to a particular entry by hitting Enter with the cursor over it. Outside the window you can navigate from match to match with commands like :cnext.

See :h quickfix for full details about such lists. (And :h :helpgrep for all its capabilities.)

  • Why do I need to slash preprended, like :tag /min? – Shuzheng Jul 16 '20 at 15:13
  • Without the slash the string is interpreted literally. It will match either one tag name or none. With a slash it is interpreted as a pattern. You can specify a regular expression and thus match multiple tags. I updated the answer with this info. – B Layer Jul 16 '20 at 15:21

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.