Any example of "vimdoc's endless quirks" ?

sisrfeng commented 1 year ago

I've changed my syntax/help.vim a lot, and I'm curious on the quirks. (If this is off-topic, please forgive me )

clason commented 1 year ago

Not an actionable issue; questions are better asked on Matrix.

justinmk commented 1 year ago

The quirks are endless, so they can be found everywhere. Most egregious are the pervasive assumptions of (1) fixed-width rendering and (2) any errors are "just highlighting errors, so no big deal".

Examples:

the structure of functions in :help builtin assume fixed-width rendering, or an implicit header-like behavior of the right-aligned *tag*:

eventhandler()                       *eventhandler()*
    Returns 1 when inside an event handler.  That is that Vim got
    interrupted while waiting for the user to type a character,

completely ad-hoc "tables" found everywhere, or ascii art. No consistent rules.

sisrfeng commented 1 year ago

I hate the syntex of vimdoc. Since people like me may come here, I hope more people see my suggestion on "A Modern NeoVimdoc" https://github.com/neovim/neovim/issues/18017

Relevant thoughts (written in Chinese): https://www.zhihu.com/question/522622970/answer/2396053988

neovim / tree-sitter-vimdoc

Any example of "vimdoc's endless quirks" ? #101