18

Many answers (and some questions) include information from vim's builtin documentation. I often find myself on google looking for an HTML version of the vim help, so I can link to it in my answers.

With this in mind, I have two questions:

  1. Is there any way to automatically link :help [key] in answers to online documentation, so the audience doesn't have to switch from their browser to vim to check it out?
  2. Is there a preferred site hosting the vim documentation?

Thanks.

| |
  • Related: meta.vi.stackexchange.com/questions/90/… – user72 Feb 27 '15 at 19:51
  • 7
    I think it would be nicer if we could auto-link using Vim's help syntax, e.g. |:buffers|. Anything inside |'s would be treated as a help tag. Not requiring the :help keyword allows for more casual language. – tommcdo Mar 2 '15 at 15:36
  • Any syntax like [help:topic] would be nice, with a way to transform `:h [help::buffers]` into :h :buffers. But to automate it the doc hosting site needs to be reliable, like vimhelp probably is and this one that should be used for questions specific to Neovim. Maybe vi.SE could host some static files? :) – LEI Aug 26 '17 at 12:42
9

Update 20150825: an improved of this now lives at http://code.arp242.net/helplink.vim. It has a number of improvements, and you can install it as a plugin :-)

I will leave the original since it's a lot simpler and might be more helpful to show how this can be done.


I've been using this function; it will (backwards) look for the first tag, and return that in Markdown link. It also puts in the clipboard...

So you can just use :help from Vim, and when you want to link something use :echo Helplink().

" Make help link (markdown format)
" TODO: Find all tags, and let the user choose which one to use
fun! Helplink()
    " Get the name of the tag, With help from:
    " https://vi.stackexchange.com/questions/434/get-name-of-nearest-tag-to-the-cursor
    if !search('\*\zs[^*]\+\*$', 'bW')
        echoerr "No tag found"
    endif
    let l:line = getline('.')
    let l:start = col('.') - 1
    call search('\*', '', line('.'))
    let l:len =  col('.') - l:start - 1
    let l:tagname = strpart(l:line, l:start, l:len)

    " TODO: Also support Python 2 and maybe Ruby...
    let l:tagname_esc = system('python3 -c "import sys, urllib.parse as p;  empty=' . "''" . '; print(p.quote(sys.argv[1], safe=empty), end=empty)" ' . shellescape(b:tagname))
    let l:file = split(expand('%'), '/')[-1]
    let l:url = "http://vimhelp.appspot.com/" . l:file . ".html#" . l:tagname_esc
    let l:md = '[`:help ' . l:tagname . '`](' . l:url . ')'

    " Copy it to the clipboard
    let @+ = l:md

    return l:md
endfun
2

Is there any way to automatically link :help [key] in answers to online documentation, so the audience doesn't have to switch from their browser to vim to check it out?

Without commenting on whether or not I think such a feature would be useful, that kind of specialized feature generally wouldn't be written for a site until after it's out of beta. You may want to bring it up again if we get to that point.

Is there a preferred site hosting the vim documentation?

Whichever you want to use is entirely up to you.

http://vimhelp.appspot.com/ seems okay.
There's also http://vimdoc.sourceforge.net/htmldoc/ but this seems outdated (Vim 7.3)

| |
  • 2
    vimhelp has spectacularly poor searching, because it uses Google, and vimdoc has pretty good searching, because it uses an index. So what I often do is search either on vim or vimdoc, and "tranlate" the result to vimhelp. – muru Feb 27 '15 at 20:38
  • 1
    @Gilles The reason I prefer vimhelp is it's help for vim 7.4 (vimhelp) vs. 7.3 (vimdoc). Actually vimhelp says its 7.4.648, so almost 5 years newer. – derobert Mar 1 '15 at 0:36
  • I don't know, it's simply an option and happened to be the first one in my history list when I went looking for one. – user72 Mar 1 '15 at 0:36
  • @Gilles vimdoc.sourceforge.net is rather outdated; as home page page says: For Vim version 7.3. Last change: 2010 Jul 2... – Martin Tournoij Mar 1 '15 at 1:08
  • @Carpetsmoker vim --version | head -n 1VIM - Vi IMproved 7.3 (2010 Aug 15, compiled Feb 10 2013 02:27:59) so vimdoc.sf.net looks appropriate to me. That way you don't risk recommending super-recent stuff that the asker may not have yet. – Gilles 'SO- stop being evil' Mar 1 '15 at 1:25
  • 3
    @Gilles And now you risk linking to documentation that doesn't describe feature foo that you present in your answer; in a few other cases it may even be wrong (such as the cryptmethod setting). Vim 7.4 is from Aug 2013, so it's not "super-recent". CentOS 5 (support until 2017) ships with Vim 7.0; IIRC CentOS 6 uses Vim 7.2 (support until 2020). Should we link to Vim 7.0 until 2017, and 7.2 until 2020? No one site can please everyone. Given that Vim is very backwards-compatible (perhaps even to a fault) linking to the most recent stable version seems like the best thing to do to me. – Martin Tournoij Mar 1 '15 at 1:40

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .