How to cycle through all "tags" matching `:h {subject}`?

Question

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
            "[a-z]":
               :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.

B Layer · Accepted Answer

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:

Open a help window
Use the ":tag" command with a slash prepended to the tag.  E.g.: >     :tag /min
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.)

How to cycle through all "tags" matching `:h {subject}`?

One Answer

Add your own answers!

Ask a Question