3

Part of the job performed by virtually all plugin managers in Vim is to create helptags, which will index the help files shipped with the plugins and will allow searching for commands and mappings added by the plugins themselves.

This action is implemented by calling the :helptags command and passing it the path to the doc/ directory inside a plugin directory tree.

The :helptags command will scan that directory for files matching *.txt, index the tags inside those files and then create a new file named tags inside that same directory.

So the contents of the tags file only depend on contents of files shipped by the plugin itself (the doc/*.txt files) and the file lives within the plugin directory tree as well (also under the doc/ subdirectory.)

So why is it that this file always needs to be generated when installing or updating plugins, rather than shipped with the plugins themselves?

I ask because it's kind of a pain to keep that always up to date when manually managing plugins, for instance when using the package manager support from Vim 8 and when storing the plugins as git submodules of a main repository.

Improve this question
2
  • 1
    IMHO generated files do not belong into a git repository. This shortens commit size, makes git log shorter, less human errors such as the tag file can be outdated w.r.t. actual doc file etc. BTW do you know that you can run :helptags ALL to generate/update all tags file with a single command?
    – Hotschke
    May 14, 2019 at 7:36
  • @Hotschke I somewhat agree with that in principle, but in this case the git repository is used both as source control and as a delivery mechanism, so I don't think storing the tags file there would be such a huge problem. Framing the question a bit differently, I think at some point Vim plugins were typically distributed as tarballs (Vimballs?) and I believe those didn't come with helptags either. Getting out of sync is definitely a concern, but git can somewhat deal with that using hooks to ensure contents are synchronized.
    – filbranden ♦
    May 14, 2019 at 7:54

2 Answers 2

Reset to default
2

I think the helptags are not distributed with the plugins for the same reasons you don't put the tags generated by cscope or ctags in version control:

  • That limits the size of your repo
  • Since generating them is deterministic, there is no added value to have the file generated by the author
  • And that limit the risk for the author to distribute the wrong tags or to forget to update them.

Also if your problem is to manually keep track of your helptags, maybe you don't know about :helptag ALL which generates the tags for all of the directories in your runtimepath :h :helptags

EDIT I didn't see @Hotschke comment before redacting this answer but basically I agree with all they said :)

Improve this answer
6
  • Actually yes, I do know about :helptags ALL (on Vim 8) or similarly :Helptags from Pathogen, but I don't think calling those from .vimrc is a good idea, both because it would always slow down startup, and because it wouldn't fix the help tags if a plugin is updated while Vim is opened already... So far, the best I've come up with is a wrapper around git submodule to update the helptags whenever they get synced, but I'm not in love with that since it can be easily forgotten...
    – filbranden ♦
    May 14, 2019 at 7:50
  • Personally I don't use vim's built-in package manager because I find it way less convenient than vim-plug. However maybe you could create a git hook to automatically run the command after a git pull I think maybe a post merge hook could do the trick.
    – statox
    May 14, 2019 at 7:57
  • So for actual tags files in projects written in C, I'm using vim-gutentags, which works really well. I wonder if it would be possible to do something similar to generate helptags on demand, only when really needed? Perhaps an autocmd? Just not sure how to match it to :help being called... I'll take a look and see if I can find something that makes that work.
    – filbranden ♦
    May 14, 2019 at 8:10
  • I don't think generating code tags and help tags are the same use case: I see the point of automatically generating code tags because they change often and you need to keep track of that, but you don't update your plugins as often (maybe once a month? I know that all of my plugins work just fine so I update them maybe once every few month) and in this case I have trouble seeing how running :helptag ALL manually is an issue. However instead of creating an hacky autocommand maybe you can just define your own :Help command which will run :helptags before running the actual :help command
    – statox
    May 14, 2019 at 15:08
  • 1
    @statox i have a makefile that runs my dotfiles; one of the phony targets is the helptags, also triggered by an update.
    – D. Ben Knoble ♦
    May 14, 2019 at 17:12
1

Here is an alternative solution to running :helptags ALL.

Assume that all your plugins are installed in subdirectories the directory ~/.vim/pack/ as you would do with vim8. Also suppose that ~/.vim/ is part of your runtimepath variable.

Add a symbolic link doc in the directory ~/.vim/ using the command cd ~/.vim; ln -s ~/.vim/pack doc. You only need to do this once.

Now run :helptags ~/.vim/pack/ whenever you install a new package (or the first time). This will update/create a tags file accessible as ~/.vim/doc/tags.

As per the documentation for :help it looks for a tags file in doc/tags for every path in the runtimepath. Moreover, the locations in that tags file should be relative to that directory. Both of these objectives are achieved with the above method.

One "advantage" of this method is that the tags files do not clutter up the package directories where the individual packages reside. This could also be a disadvantage since the size of this one tags file could become quite large if there are many packages.

Improve this answer
3
  • Welcome to Vi and Vim and thanks for answering! I guess my original question was about why we need to run :helptags at all, why don't plug-ins already ship the tags files themselves. (And in fact I found some that already do.) Thanks for your suggestion. I see some drawbacks in it, mostly that Vim will end up searching both directories for tags files anyways... In the end, I'm just using a plug-in manager that takes care of that to me (even on Vim 8 packages, I found it having a plug-in manager around, even if it's just "minpac", is quite helpful.)
    – filbranden ♦
    May 26, 2020 at 20:06
  • Thanks @Kapil ! this seems to be only clean/simple way to get helptags for vim8 packages
    – balki
    Dec 7, 2021 at 0:53
  • See here for a better way. This solution breaks when the package has a non-help txt file. e.g. github.com/prabirshrestha/vim-lsp/blob/master/test/testfiles/…
    – balki
    Jan 3 at 23:35

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.