reversed(top()) code tags rss about

Converting Vim documentation file to HTML

January 13, 2016
[vim] [web]

Vim has a great documentation for sure. Part of its greatness is documentation format itself. The only difficulty is that it can’t be easily converted to and from other formats, which might be sometimes desirable or at least useful to provide same documentation in different form. In particular, conversion into HTML is sometimes useful and although there is an HTML version of Vim documentation, the tool with which it’s produced has never been made public. There is another way around it without the need to write such a tool from scratch.

Situation

First, people asked to make that tool of VimDoc project public, but the request was ignored.

Second, there is VimHelp site, which sources are available here.

Third, :TOhtml won’t produce the desired result, it’s more like generating HTML from Office Word… Good for some tasks, but doesn’t suite well in this situation.

Results

Frustrated by absence of the tool that as I thought should already be available, I took conversion class from VimHelp and added:

  • minimal argument parsing
  • input/output handling
  • anchors to tags declaration
  • automatic tags generation (via third-party Perl script called helpztags)

It’s called VimDoc2HTML.

Example of how files look like after conversion is available here.

Similar tools

There are some other tools related to VimDoc conversions that I have found while looking for VimDoc -> HTML converter.

Conversion to PDF

There is a way to generate PDF file containing entire Vim’s reference. It is described in this post and is available here. Based on the same parser I used.

Conversion from HTML and Markdown

Conversion in this direction seems to be more popular task. Somebody asked about it and there is now a tool for that here.