2

:h {subject} reads

If there is no full match for the pattern, or there
are several matches, the "best" match will be used.
A sophisticated algorithm is used to decide which
match is better than another one.  These items are
considered in the computation:
    - A match with same case is much better than a match
      with different case.
    - A match that starts after a non-alphanumeric
      character is better than a match in the middle of a
      word.
    - A match at or near the beginning of the tag is
      better than a match further on.
    - The more alphanumeric characters match, the better.
    - The shorter the length of the match, the better.

How can I get the system-wide help files to take precedence in the search? It has been bugging me for a while that plugin help seems to always come first. (for example, :h cursor brings me to the file ~/.local/share/nvim/site/pack/github/start/hyperstyle/doc/hyperstyle.txt). I can't find information about the search order.

:set helpfile?
helpfile=/usr/share/nvim/runtime/doc/help.txt
:echo $VIMRUNTIME
/usr/share/nvim/runtime
:echo $VIM
/usr/share/nvim

I use neovim v0.4.0-391-gb90256e6c.

Improve this question

1 Answer 1

Reset to default
3

If you just do :help vim opens the file specified in 'helpfile'. If you supply a tag then vim will look for it in all "doc/tags" files it can find. It does this by going through the directories listed in 'runtimepath' (alias: 'rtp').

Theoretically you could modify the order of directories in rtp to your liking and therby change help file priority. Since you want system help first I think what you want to do is put the directory named in $VIMRUNTIME ahead of all plugin directories in the rtp list string.

Note: at first I was wary of suggesting such a reorder but :h 'rtp' talks about reordering it for certain (unrelated) purposes so it should be safe.

Update: My answer was hypothetical but now I've verified that it works as described. Specifically I...

  • Created a dummy plugin
  • Added plugin's path to 'rtp'
  • Added a help file for the plugin
  • In the helpfile added a tag that duplicates a Vim help tag
  • Generated the tag file
  • Ran :h {duplicate-tag}

When the dummy plugin's path in 'rtp' is in front of all the paths that are subdirs of $VIMRUNTIME then its help is loaded. When I move the plugin path after those same paths then Vim's help is loaded.

Update 2: As I noted in a comment if you have issues with duplicate tags :tselect and other commands can help. See the :h tag-matchlist section which opens with...

When there are several matching tags, these commands can be used to jump between them.

Improve this answer
9
  • I'm now setting set rtp=$VIMRUNTIME,$XDG_CONFIG_HOME/nvim,$XDG_DATA_HOME/nvim/site,$XDG_DATA_HOME/nvim/site/after,$XDG_CONFIG_HOME/nvim/after before adding packages (and double checked rtp) but :h cursor still gives me the plugin help...
    – Bart
    May 25, 2019 at 9:35
  • echo &rtp pastebin.com/aDQyR2ET
    – Bart
    May 25, 2019 at 9:45
  • thank you for testing, I checked, you're right. Maybe I should rephrase the question to Can I change the default algorithm to include the rule like "The earlier a parent directory of a file with a close match is in the rtp, the better."?
    – Bart
    May 28, 2019 at 7:24
  • For now, I will use a wrapper command that temporarily resets rtp to $VIMRUNTIME, and another command for when I expect matches in plugin help.
    – Bart
    May 28, 2019 at 7:28
  • Questions shouldn't be changed substantively once answers have been submitted. You can always add a new question. That being said I'm pretty sure the answer to that question is "Short of changing Vim code, no, you can't do that." This is the first I've heard of someone having persistent issues with this. For one, most plugin docs don't reuse tags from Vim help (precede tag with plugin name if there's conflict). Are you familiar with :tselect? Give it a tag and you'll get a menu of choices from which you can select the one you want. No need for custom solution if that's acceptable to you.
    – B Layer
    May 28, 2019 at 9:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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