pseudo-heading (right-aligned tag)

neovim / tree-sitter-vimdoc

Tree-sitter parser for Vim help files

Apache License 2.0

106 stars 13 forks source link

pseudo-heading (right-aligned tag) #110

Open justinmk opened 1 year ago

justinmk commented 1 year ago

Problem

vim :help (including :help api) has many "pseudo headers" that look like:

range({spec})                                            *vim.version.range()*
    Parses a semver |version-range| "spec" and returns a range object:  
    ...

Expected behavior

Treat right-aligned tags as h3? This is necessary so that "flow" layout doesn't join the lines. In the above example,

the range({spec})... line should be a h3 heading.
the Parses a semver... line should start a new block.

clason commented 1 year ago

Maybe h4 would be a better fit?

justinmk commented 1 year ago

maybe, depends on whether these headings are usually nested below h2 or h3? h3 is pretty uncommon so I was thinking that it's too granular to treat these as h4.

clason commented 1 year ago

Wait, you think there's consistent hierarchy in how these are used in the docs? :D

I guess my thinking was more if there's an h3, then h4 will lead to better hierarchy, and if there is not, it's still correct (even if a heading is skipped).

clason commented 1 year ago

(To be clear, if the gen_help_html script requires h3 specifically, my comment is moot.)