The stuff I do

GOD.vim - The easiest way to quote Vim's help

← Posts

I love to Quote the doc

I often participate on the vi.stackexchange website because this community really helped me to get going with Vim when I first started using it and because it feels great to be able to help new vimmers.

When I write an answer I always try to think about how I can not only help the user to achieve what they want to do, but more importantly how I can help them to answer their own question next time they have one. And the best way to do that is to help them getting comfortable with the help.

Indeed Vim has an amazing built-in help system accessible directly from the editor itself using the command :h. So whenever I write my answers I do my best to add the relevant help topics. And I also like to add a link to one of the several online version of the help

But it's painful

For a long time I just wrote the help command like :h autocmd-events in my answers but this was not convenient:

After doing that for a few months and feeling the pain I started creating a short hack in my .vimrc to improve this workflow, until the day I read How can I quickly convert a Vim help tag to a vimhelp.appspot.com link?. This question confirmed that this action was a pain point for other people and that pushed me to create a proper plugin.

So let's create a plugin!

So I created GOD.vim this is a very simple plugin which goal is to easily get a markdown expression describing a help topic and linking to its online version. The plugin does the following:

I also added some additional features:

I think the trickiest part about writing this plugin was to create a pure vimscript encoding function to handle the URLs. Indeed a lot of help topics have some characters which need to be URL encoded. The first version of my encoding function didn't work very well but fortunately I got the help of great developers from the vi.stackexchange community, namely Luc Hermitte and Martin Tournoij who helped me with different parts of this plugin and in particular who helped me coming up with this function:

" Encode url
function! s:URLEncode(str) abort
" Replace each non hex character of the string by its hex representation
return join(map(range(0, strlen(a:str)-1), 'a:str[v:val] =~ "[a-zA-Z0-9\-._]" ? a:str[v:val] : printf("%%%02x", char2nr(a:str[v:val]))'), '')
endfun

It takes an help topic as a parameter like /\@<=, iterates on each characters of the string and if the character doesn't match /[a-zA-Z0-9\-._]/ (i.e. characters which don't need to be URL encoded) it uses :h char2nr() to get the numerical value of the character and passes this value to :h printf().

Here printf() is used with the following format: %%%02x:

With our example topic /\@<= the function returns %2f%5c%40%3c%3d.

Field tested

I've been using this plugin regularly for several years now and I don't recall encountering a topic which didn't work well. And of course it is always a great satisfaction to create a tool that you still continue to use several years after you first needed it!

The sources of the plugin and its documentation are on Github

← Posts


Comments