Code Vault

xaizek / vimdoc2html (License: GPLv3+) (since 2018-12-07)

Converts Vim-style documentation into HTML.

Clone URLs: https://code.reversed.top/user/xaizek/vimdoc2html ssh://rocketgit@code.reversed.top/user/xaizek/vimdoc2html

File	Mode	Size
.gitignore	100644	13B
COPYING	100644	34KiB
README.md	100644	2,410B
helpztags	100755	2,278B
vimd2h.py	100755	8,551B
vimdoc2html.py	100755	3,304B
vimhelp.css	100644	1,093B

/README.md

Overview

This is a script to convert Vim documentation file into HTML.

Dependencies

Perl
Python

Description

The basic usage is:

./vimdoc2html.py plugin.txt

or if the script is somewhere in the $PATH:

vimdoc2html.py plugin.txt

Operation

As a first step, helpztags script is used to generate tags file similar to what Vim's :helptags command produces. This is needed to know which references should be turned into hyperlinks. Then the tags and documentation in Vim's format are processed to produce HTML output.

Options

`-m,--map FILE=URL` option

Associates a file path as found in tags file with a URL. This option can be specified multiple times. By default base name of the input file is mapped to an empty string (current URL in a browser). All other unmapped file names in the tags file are mapped to an empty string and cause printing of a warning which can be used to adjust invocation.

`-o,--output path` option

Specifies name of the output file. The default behaviour is to derive it from the name of the input file by appending .html.

`-r,--raw` flag

Instead of outputting complete standalone HTML page, produce only minimal output without <html>/<head>/<body>/<pre> tags.

`-t,--template path` option

Overrides builtin template. The following sequences will be expanded: - {title} with the name of the source file - {style} with the contents of vimhelp.css - {html} with documentation formatted as HTML

Default template is trivial:

<html>
    <head>
        <title>{title}</title>
        <style>{style}</style>
    </head>
    <body>
        <pre>
        {html}
        </pre>
    </body>
</html>

Credit

HTML formatting is performed via modified version of vimh2h.py by Carlo Teubner <(first name) dot (last name) at gmail dot com>. This one is simplified to remove unused here code and a bit improved to add anchors to each tag definition. CSS style is from there too.

Tags are extracted via helpztags tool written by Jakub Turski yacoob@chruptak.plukwa.net and Artur R. Czechowski arturcz@hell.pl. It's supplied alongside for convenience and to provide a couple of changes, see there.

Hints

Before first commit, do not forget to setup your git environment:

git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):

git clone https://code.reversed.top/user/xaizek/vimdoc2html

Clone this repository using ssh (do not forget to upload a key first):

git clone ssh://rocketgit@code.reversed.top/user/xaizek/vimdoc2html

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a pull request:

... clone the repository ...
... make some changes and some commits ...
git push origin master