- 820 words -
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
For a long time I just wrote the help command like
:h autocmd-events in my answers but this was not convenient:
:hand add the help topic.
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 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:
:GODwhich takes the exact same parameter as
:h. The autcomplete behavior is completely duplicated thanks to
:h :command-complete, see how I create the command:
command! -nargs=+ -complete=help GOD call GOD#GetOnlineDoc('vimhelp', <f-args>)
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]))'), '')
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
printf() is used with the following format:
%%is used to insert a litteral
%character (which is used in URL encoding to specify encoded characters)
%02xis used to get the hex value of the character.
02is the number of
0to use for the padding.
With our example topic
/\@<= the function returns
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 in the same category: [vim]