Generating helptags for vim plugins

Generating helptags for vim plugins

[nils]

Hello everyone,

I'm trying to switch my home environment to guix home (from Chef).
As a first step, I'm writing package definitions for the various vim plugins I use.
I followed the simple plugins in gnu/packages/vim, using git-fetch + copy-build-system. This worked fine, but I noticed that there is no code to generate the helptags, meaning the plugin documentations don't show up in vim when using :help. Having the documentations available is important to me! 

My solution was to write a vimplugin-build-system. It uses copy-build-system for most things, but generates the helptags for the plugin as an additional step after installation. Technically that works, in that the helptags for the plugin are generated and available in vim. Sadly the concept was wrong, because the helptags file is always named "tags" and needs to be in the same directory as the help file. This means installing multiple plugins has the doc files for all plugins symlinked in ~/.guix-home/profile/share/vim/vimfiles/doc , and then the "tags" file of (I'm guessing) the last plugin, meaning only that last plugin documentation is available in vim.

Solutions I could think of:

1) Run the helptags generation after *all* plugins are installed
2) Do not install all plugins to ~/.guix-home/profile/share/vim/vimfiles but rather keep them in one subfolder per plugin (which is how the built-in vim package management works, and most or all vim plugin managers). 

How could 1) be implemented? I could do 2) rather easily I think, but it would contributing the plugin packages difficult, since it needs changes in the gnu/packages/aux-files/guix.vim to add those directories to the vim runtime path.

Has anyone already spent some time on this? It looks to me like an issue that everyone would run into if they use the already packaged plugins in gnu/packages/vim.

Re: Generating helptags for vim plugins

[Efraim Flashner]

[-- Attachment #1: Type: text/plain, Size: 2866 bytes --]

On Sun, Feb 19, 2023 at 11:09:57AM +0100, nils@promisedlandt.de wrote:
> Hello everyone,
> 
> I'm trying to switch my home environment to guix home (from Chef).
> As a first step, I'm writing package definitions for the various vim plugins I use.
> I followed the simple plugins in gnu/packages/vim, using git-fetch + copy-build-system. This worked fine, but I noticed that there is no code to generate the helptags, meaning the plugin documentations don't show up in vim when using :help. Having the documentations available is important to me! 
> 
> My solution was to write a vimplugin-build-system. It uses copy-build-system for most things, but generates the helptags for the plugin as an additional step after installation. Technically that works, in that the helptags for the plugin are generated and available in vim. Sadly the concept was wrong, because the helptags file is always named "tags" and needs to be in the same directory as the help file. This means installing multiple plugins has the doc files for all plugins symlinked in ~/.guix-home/profile/share/vim/vimfiles/doc , and then the "tags" file of (I'm guessing) the last plugin, meaning only that last plugin documentation is available in vim.
> 
> Solutions I could think of:
> 
> 1) Run the helptags generation after *all* plugins are installed
> 2) Do not install all plugins to ~/.guix-home/profile/share/vim/vimfiles but rather keep them in one subfolder per plugin (which is how the built-in vim package management works, and most or all vim plugin managers). 
> 
> How could 1) be implemented? I could do 2) rather easily I think, but it would contributing the plugin packages difficult, since it needs changes in the gnu/packages/aux-files/guix.vim to add those directories to the vim runtime path.
> 
> Has anyone already spent some time on this? It looks to me like an issue that everyone would run into if they use the already packaged plugins in gnu/packages/vim.

There are two possibilities that I can see at this point:
1: There's a patch to install all the vim plugins into their own prefix
and use vim's :packadd to actually load the packages when they're
wanted. I feel like this is probably the technically correct way to do
it.

2: Add a profile hook to build all the help tags as part of building the
profile, similar to the emacs sub-directories or the font cache or the
mime database or other things. This would introduce the least amount of
change to users since they wouldn't need to start doing :packadd and the
help files would just show up.

As someone who actively wants the help files, I'm curious which you'd
prefer.

-- 
Efraim Flashner   <efraim@flashner.co.il>   אפרים פלשנר
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Generating helptags for vim plugins

[nils]

> Efraim Flashner <efraim@flashner.co.il> hat am 19.02.2023 21:06 CET geschrieben:
> 
>  
> On Sun, Feb 19, 2023 at 11:09:57AM +0100, nils@promisedlandt.de wrote:
> > Solutions I could think of:
> > 
> > 1) Run the helptags generation after *all* plugins are installed
> > 2) Do not install all plugins to ~/.guix-home/profile/share/vim/vimfiles but rather keep them in one subfolder per plugin (which is how the built-in vim package management works, and most or all vim plugin managers). 
> > 
> > How could 1) be implemented? I could do 2) rather easily I think, but it would contributing the plugin packages difficult, since it needs changes in the gnu/packages/aux-files/guix.vim to add those directories to the vim runtime path.
> > 
> > Has anyone already spent some time on this? It looks to me like an issue that everyone would run into if they use the already packaged plugins in gnu/packages/vim.
> 
> There are two possibilities that I can see at this point:
> 1: There's a patch to install all the vim plugins into their own prefix
> and use vim's :packadd to actually load the packages when they're
> wanted. I feel like this is probably the technically correct way to do
> it.
> 
> 2: Add a profile hook to build all the help tags as part of building the
> profile, similar to the emacs sub-directories or the font cache or the
> mime database or other things. This would introduce the least amount of
> change to users since they wouldn't need to start doing :packadd and the
> help files would just show up.
> 
> As someone who actively wants the help files, I'm curious which you'd
> prefer.

I also think that having each plugin in its own folder is the most robust solution. Both vim and neovim have package loading that works with no or minimal configuration for quite a few years now, and to me it makes sense if guix adds the plugins in the structure the built-in loaders expect.
However, I would not expect the user to have to :packadd each plugin separately. Having plugins autoload is the behaviour with the current guix packages, and I think that's the most common use case anyway.
For that, I think all that needs to be done is to install the plugins  at ~/.guix-home/profile/share/vim/plugins/pack/guix/start/<plugin_name>
and then having set packpath=~/.guix-home/profile/share/vim/plugins in the system vimrc. 

For neovim plugins, the path would be ~/.guix-home/profile/share/nvim/site/pack/guix/start/<plugin_name>.

The "luxury" solution would be to specify for each plugin whether it's a vim or neovim plugin, and whether it should be autoloaded or not, but the above solution mimics the current behaviour of the guix vim plugin packages.

I was unable to locate the code for the profile hooks you mentioned. Where can I find them?

Re: Generating helptags for vim plugins

[SeerLite]

On 2023-02-21 11:32, nils@promisedlandt.de wrote:
> I also think that having each plugin in its own folder is the most 
> robust solution. Both vim and neovim have package loading that works 
> with no or minimal configuration for quite a few years now, and to me 
> it makes sense if guix adds the plugins in the structure the built-in 
> loaders expect.
> However, I would not expect the user to have to :packadd each plugin 
> separately. Having plugins autoload is the behaviour with the current 
> guix packages, and I think that's the most common use case anyway.
> For that, I think all that needs to be done is to install the plugins  
> at ~/.guix-home/profile/share/vim/plugins/pack/guix/start/<plugin_name>
> and then having set packpath=~/.guix-home/profile/share/vim/plugins in 
> the system vimrc.
> 
> For neovim plugins, the path would be 
> ~/.guix-home/profile/share/nvim/site/pack/guix/start/<plugin_name>.

Hi! Whichever way you go I recommend you avoid hardcoded paths and 
instead use search paths. This way you can have Vim and its plugins in a 
non-default profile and no collisions or unexpected sourcing will happen 
in `guix shell`. `--pure` should be pure!

See my old patch for more info: <https://issues.guix.gnu.org/54221#30>

SeerLite