Why are helptags not shipped with plugins?

Question

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.

Answer 1

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 :)

Answer 2

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.