12

This is kind of two questions in one. Lately I've been spending a lot of time learning vimscript in-depth, learning vim's internals & taking my first steps writing vim plugins. During this process, I've been keeping extensive notes in individual markdown files & add lots of inline 'documentation' comments to the vimscript files.

I feel like I've finally got some code that's worth sharing, and want to start adding some actual documentation. I haven't authored any of my own helpdoc files yet, so I'm still figuring out that process.

Without any experience yet or solid understanding of this workflow, there are two tasks I'm trying to figure out:

  1. Generating helpdoc files from my markdown 'notes' files on vim/vimscript, so I can read/reference quickly & easily from vim at any time.
  2. Parsing the inline documentation from my vimscript files (similar to the way shocco works for shell scripts) to generate the associated helpdoc for the vimscripts.

Any suggestions or advice on the ideas (this is a bad idea because ..., a better idea is ...), or how to accomplish them would be greatly appreciated.

7

As far as I know there is currently no good solution for either problem, but a lot of people would be interested in solving them.

Markdown is a superset of HTML, so I'd say a frontal approach to conversion from markdown to Vim help is unlikely to succeed. If you can speak Haskell you could try to write a Vim help backend for pandoc. That would be a very nice solution even if it isn't perfect.

There have been a few attempts at doing it the other way around, convert Vim help pages to some useful format. There are a few scripts floating around that produce HTML and PDF versions of the official help, with varying degrees of success. But they all rely on the help being more or less homogenous in style. Even a Vim help reader for something like pandoc would be a worthwhile project.

As for extracting documentation from Vim code, there's a parser for VimL in Python, JavaScript, and VimL itself, named vimlparser. It's pretty good, it shouldn't be hard to write something that parses VimL sources and dumps special crafted comments. Being able to convert these comments to something like, say, POD would be highly useful too.

3

html2vimdoc.py

The most promising tool I've found is html2vimdoc.py which can be found here http://peterodding.com/code/vim/tools and on github. It can convert markdown and html to vim's help format. Advertised features are:

  • It can deal with complex HTML thanks to [BeautifulSoup] bs
  • Automatically generates Vim help file tags for headings
  • Generates table of contents from headings & tags
  • Supports nested block structures like nested lists, preformatted blocks inside lists, etc.
  • Compacts & expands list items based on average number of lines per list item

An older alternative is https://github.com/mklabs/vim-markdown-helpfile

There has also been a discussion on https://superuser.com/q/415470/generating-help-files-for-vim

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.