diff options
Diffstat (limited to 'scripts')
| -rwxr-xr-x | scripts/gen_eval_files.lua | 32 | ||||
| -rw-r--r-- | scripts/gen_help_html.lua | 14 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.py | 47 |
3 files changed, 69 insertions, 24 deletions
diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua index f8d69ce313..1afe3d5f46 100755 --- a/scripts/gen_eval_files.lua +++ b/scripts/gen_eval_files.lua @@ -213,17 +213,20 @@ end --- Convert vimdoc references to markdown literals --- Convert vimdoc codeblocks to markdown codeblocks +--- +--- Ensure code blocks have one empty line before the start fence and after the closing fence. +--- --- @param x string --- @return string local function norm_text(x) return ( x:gsub('|([^ ]+)|', '`%1`') - :gsub('>lua', '\n```lua') - :gsub('>vim', '\n```vim') - :gsub('\n<$', '\n```') - :gsub('\n<\n', '\n```\n') - :gsub('%s+>\n', '\n```\n') - :gsub('\n<%s+\n?', '\n```\n') + :gsub('\n*>lua', '\n\n```lua') + :gsub('\n*>vim', '\n\n```vim') + :gsub('\n+<$', '\n```') + :gsub('\n+<\n+', '\n```\n\n') + :gsub('%s+>\n+', '\n```\n') + :gsub('\n+<%s+\n?', '\n```\n') ) end @@ -552,26 +555,19 @@ end local function scope_more_doc(o) if vim.list_contains({ - 'previewwindow', - 'scroll', - 'winfixheight', - 'winfixwidth', - }, o.full_name) - then - return ' |special-local-window-option|' - end - - if - vim.list_contains({ 'bufhidden', 'buftype', 'filetype', 'modified', + 'previewwindow', 'readonly', + 'scroll', 'syntax', + 'winfixheight', + 'winfixwidth', }, o.full_name) then - return ' |special-local-buffer-option|' + return ' |local-noglobal|' end return '' diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 5e06830336..c8e004e2ab 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -574,14 +574,15 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return '' end local el = in_heading and 'span' or 'code' - local s = ('%s<%s id="%s" class="%s">%s</%s>'):format(ws(), el, url_encode(tagname), cssclass, trimmed, el) + local encoded_tagname = url_encode(tagname) + local s = ('%s<%s id="%s" class="%s"><a href="#%s">%s</a></%s>'):format(ws(), el, encoded_tagname, cssclass, encoded_tagname, trimmed, el) if opt.old then s = fix_tab_after_conceal(s, node_text(root:next_sibling())) end if in_heading and prev ~= 'tag' then -- Don't set "id", let the heading use the tag as its "id" (used by search engines). - s = ('%s<%s class="%s">%s</%s>'):format(ws(), el, cssclass, trimmed, el) + s = ('%s<%s class="%s"><a href="#%s">%s</a></%s>'):format(ws(), el, cssclass, encoded_tagname, trimmed, el) -- Start the <span> container for tags in a heading. -- This makes "justify-content:space-between" right-align the tags. -- <h2>foo bar<span>tag1 tag2</span></h2> @@ -963,6 +964,7 @@ local function gen_css(fname) margin-bottom: 0; } + /* TODO: should this rule be deleted? help tags are rendered as <code> or <span>, not <a> */ a.help-tag, a.help-tag:focus, a.help-tag:hover { color: inherit; text-decoration: none; @@ -977,6 +979,14 @@ local function gen_css(fname) margin-right: 0; float: right; } + .help-tag a, + .help-tag-right a { + color: inherit; + } + .help-tag a:not(:hover), + .help-tag-right a:not(:hover) { + text-decoration: none; + } h1 .help-tag, h2 .help-tag, h3 .help-tag { font-size: smaller; } diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index dfad1f000c..ed156e1422 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -440,7 +440,7 @@ def is_blank(text): return '' == clean_lines(text) -def get_text(n, preformatted=False): +def get_text(n): """Recursively concatenates all text in a node tree.""" text = '' if n.nodeType == n.TEXT_NODE: @@ -449,11 +449,13 @@ def get_text(n, preformatted=False): for node in n.childNodes: text += get_text(node) return '`{}`'.format(text) + if n.nodeName == 'sp': # space, used in "programlisting" nodes + return ' ' for node in n.childNodes: if node.nodeType == node.TEXT_NODE: text += node.data elif node.nodeType == node.ELEMENT_NODE: - text += get_text(node, preformatted) + text += get_text(node) return text @@ -571,7 +573,7 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation, # text += (int(not space_preceding) * ' ') if n.nodeName == 'preformatted': - o = get_text(n, preformatted=True) + o = get_text(n) ensure_nl = '' if o[-1] == '\n' else '\n' if o[0:4] == 'lua\n': text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1]) @@ -581,7 +583,14 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation, text += o[4:-1] else: text += '>{}{}\n<'.format(ensure_nl, o) - + elif n.nodeName == 'programlisting': # codeblock (```) + o = get_text(n) + text += '>' + if 'filename' in n.attributes: + filename = n.attributes['filename'].value + text += filename.lstrip('.') + + text += '\n{}\n<'.format(textwrap.indent(o, ' ' * 4)) elif is_inline(n): text = doc_wrap(get_text(n), prefix=prefix, indent=indent, width=width) elif n.nodeName == 'verbatim': @@ -758,6 +767,27 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F return chunks, xrefs +def is_program_listing(para): + """ + Return True if `para` contains a "programlisting" (i.e. a Markdown code + block ```). + + Sometimes a <para> element will have only a single "programlisting" child + node, but othertimes it will have extra whitespace around the + "programlisting" node. + + @param para XML <para> node + @return True if <para> is a programlisting + """ + + # Remove any child text nodes that are only whitespace + children = [ + n for n in para.childNodes + if n.nodeType != n.TEXT_NODE or n.data.strip() != '' + ] + + return len(children) == 1 and children[0].nodeName == 'programlisting' + def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent='', fmt_vimhelp=False): """Renders (nested) Doxygen <para> nodes as Vim :help text. @@ -786,6 +816,15 @@ def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent= for child in parent.childNodes: para, _ = para_as_map(child, indent, width, fmt_vimhelp) + # 'programlisting' blocks are Markdown code blocks. Do not include + # these as a separate paragraph, but append to the last non-empty line + # in the text + if is_program_listing(child): + while rendered_blocks and rendered_blocks[-1] == '': + rendered_blocks.pop() + rendered_blocks[-1] += ' ' + para['text'] + continue + # Generate text from the gathered items. chunks = [para['text']] if len(para['note']) > 0: |