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
master
Commit 903b342d665c7f613c053040949eb98aaabc3af5

Add -m,--map option to map files to URLs
Closes #13 on GitHub.
Author: xaizek
Author date (UTC): 2025-04-16 13:46
Committer name: xaizek
Committer date (UTC): 2025-04-16 13:47
Parent(s): 01be6b06559fec964607dd815a7b0292a2b6a374
Signing key: 99DC5E4DB05F6BE2
Tree: 4eade294c1ddded6a82336f589d1086861541a01
File Lines added Lines deleted
README.md 8 0
vimd2h.py 10 5
vimdoc2html.py 10 2
File README.md changed (mode: 100644) (index 70922d7..4473a66)
... ... in Vim's format are processed to produce HTML output.
30 30
31 31 #### Options #### #### Options ####
32 32
33 ##### `-m,--map FILE=URL` option
34
35 Associates a file path as found in `tags` file with a URL. This option can be
36 specified multiple times. By default base name of the input file is mapped to
37 an empty string (current URL in a browser). All other unmapped file names in
38 the `tags` file are mapped to an empty string and cause printing of a warning
39 which can be used to adjust invocation.
40
33 41 ##### `-o,--output path` option ##### `-o,--output path` option
34 42
35 43 Specifies name of the output file. The default behaviour is to derive it from Specifies name of the output file. The default behaviour is to derive it from
File vimd2h.py changed (mode: 100755) (index 7608d67..7a4e314)
... ... class Link(object):
71 71 self.link_plain = link_plain self.link_plain = link_plain
72 72
73 73 class VimDoc2HTML(object): class VimDoc2HTML(object):
74 def __init__(self, tags, version=None):
74 def __init__(self, tags, url_map, version=None):
75 75 self._urls = { } self._urls = { }
76 76 self._urlsCI = { } # lowercased tag -> set of cased versions self._urlsCI = { } # lowercased tag -> set of cased versions
77 77 self._urlsUnresolved = set() self._urlsUnresolved = set()
 
... ... class VimDoc2HTML(object):
80 80 m = RE_TAGLINE.match(line) m = RE_TAGLINE.match(line)
81 81 if m: if m:
82 82 tag, filename = m.group(1, 2) tag, filename = m.group(1, 2)
83 self.do_add_tag(filename, tag)
84 83
85 def do_add_tag(self, filename, tag):
86 part1 = '<a href="#' + \
87 urllib.quote_plus(tag) + '"'
84 if filename not in url_map:
85 url_map[filename] = '' # assume current URL
86 print('Unmapped filename: "%s"' % filename)
87
88 self.do_add_tag(url_map[filename], tag)
89
90 def do_add_tag(self, url, tag):
91 part1 = '<a href="{url}#{anchor}"'.format(url=url,
92 anchor=urllib.quote_plus(tag))
88 93 part2 = '>' + html_escape[tag] + '</a>' part2 = '>' + html_escape[tag] + '</a>'
89 94 link_pipe = part1 + ' class="l"' + part2 link_pipe = part1 + ' class="l"' + part2
90 95 classattr = ' class="d"' classattr = ' class="d"'
File vimdoc2html.py changed (mode: 100755) (index afddc6e..eee8de0)
... ... parser.add_argument('-o', '--output',
59 59 help="output HTML file") help="output HTML file")
60 60 parser.add_argument('-t', '--template', parser.add_argument('-t', '--template',
61 61 help="template file (overrides builtin template)") help="template file (overrides builtin template)")
62 parser.add_argument('-m', '--map', dest='url_map', action='append', default=[],
63 metavar='FILE=URL', help="maps tag's filename to a URL")
62 64 parser.add_argument('vimdoc', nargs=1, help='Vim documentation file') parser.add_argument('vimdoc', nargs=1, help='Vim documentation file')
63 65 args = parser.parse_args() args = parser.parse_args()
64 66 raw_output = args.raw raw_output = args.raw
65 67 src_filename = args.vimdoc[0] src_filename = args.vimdoc[0]
66 68 src_dir = path.dirname(src_filename) or '.' src_dir = path.dirname(src_filename) or '.'
69 src_basename = path.basename(src_filename)
70
71 url_map = { src_basename: '' }
72 for item in args.url_map:
73 filename, url = item.split('=', 1)
74 url_map[filename] = url
67 75
68 76 # generate tags file # generate tags file
69 77 subprocess.call([path.join(script_dir, 'helpztags'), src_dir]) subprocess.call([path.join(script_dir, 'helpztags'), src_dir])
 
... ... if args.template is not None:
84 92 template = template_file.read() template = template_file.read()
85 93
86 94 # produce formatted html # produce formatted html
87 html = vimd2h.VimDoc2HTML(tags).to_html(contents)
95 html = vimd2h.VimDoc2HTML(tags, url_map).to_html(contents)
88 96
89 97 # output result # output result
90 98 with io.open(html_path, 'w', encoding='utf-8') as html_file: with io.open(html_path, 'w', encoding='utf-8') as html_file:
 
... ... with io.open(html_path, 'w', encoding='utf-8') as html_file:
92 100 html_file.write(html) html_file.write(html)
93 101 else: else:
94 102 html_file.write( html_file.write(
95 template.format(title=path.basename(src_filename),
103 template.format(title=src_basename,
96 104 style=style, style=style,
97 105 html=html)) html=html))
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