Generating help files for vim

Currently I write my documentation directly as vim help files. Sometimes I need to generate other formats (e.g. PDF). My work flow is to copy the content of the help files and transform them into something I need. This is quite a tedious work, since I mostly have to add additional markup.

I like the approach of Markdown, which can (e.g. using Pandoc) be transformed into a variety of output formats. Unfortunately not vim help files. I am looking for a converter that takes a standard input format (e.g. XML, Markdown, reStructed Text, plain text, …) and outputs a vim help file. Or is there any other means of automatically generate vim help files without writing such a converter myself?

Marco

Posted 2012-04-22T22:56:14.640

Reputation: 4 015

You could probably bang together a XSLT stylesheet in a few hours. – Ignacio Vazquez-Abrams – 2012-04-23T00:59:50.313

Answers

Sorry for resurrecting a very old thread. I'm the author of the mkd2vimdoc script behind the first link suggested by lornix previously. I recently rewrote mkd2vimdoc from the ground up as html2vimdoc. It still supports Markdown as input format; it will convert Markdown to HTML and then convert that HTML to a Vim help file. The focus during the rewrite was on support for a wider range of input documents.

The new script is being used by myself and several other plug-in authors so it is definitely intended for general use. If you'd like to give it another try, I'd love to hear if it now works better for the documents you want to use it on. If it still doesn't work, feel free to create an issue on GitHub.

xolox

Posted 2012-04-22T22:56:14.640

Reputation: 210

3Welcome to SuperUser! Answering old questions is appreciated here, some people may still be looking for answers on those and it's fine to improve the old ones. – gronostaj – 2013-06-01T18:55:06.933

I found this script, which the author created to convert markdown to vim documentation. Sounds very close to what you're looking for.

While this vim.org script (github repo) converts markdown into what looks like almost everything BUT vimdoc. (sigh) So close... maybe a slight modification?

lornix

Posted 2012-04-22T22:56:14.640

Reputation: 9 633

The first script is unusable for general use. It might work for the authors markup style, but it didn't convert a single one of my (valid) markdown files correctly. The second option is pandoc, a very capable converter I like a lot. Unfortunately, it doesn't support vimhelp. I asked on the mailing list to add support for it, but the response was that vimhelp is not a general purpose output format but a specialised format intended for vim documentation, in contrast to the other supported formats. Anyway, thanks a lot for the tip. – Marco – 2012-06-20T17:25:01.830

I'm curious as to what it might entail to create a converter from markdown to vimdoc, as most of the vimdoc is formatting and special marker characters, while the magic is done by the helptags command and the vim help viewer itself. Of course, I COULD be putting my foot in my mouth (again!)... maybe it depends on the complexity of your initial markdown. – lornix – 2012-06-20T17:34:21.043

A smart workaround suggested on the mailing list was to create vimhelp which is also valid markdown. The drawback is that the markdown is a bit cluttered with vim syntax and the vimhelp files don't obey to the formatting conventions. But apart from that it is usable. – Marco – 2012-06-20T17:49:02.667