Enhancement idea: Automatically make the text fluid and responsive for better readability

[sebastiancarlos]

I'm not sure if this is possible, but it would be nice if the text could be reformatted to remove the fixed line widths
and therefore introduce this amazing work of documentation into the user-friendly world of fluid and responsive text layouts.

I'm not sure it this is possible, as the documentation contains several examples and diagrams that are akin to ASCII art in complexity. But I suspect that this is possible by automatically detecting exceptions using clever scripting or known formatting tools like fmt. I suspect that par might be even more appropriate for this task.

If an exploit like this is successful, it could be desirable to set this fluid text as the default on the site, while allowing the user to see the original too if they so desire.

This is not just a nice-to-have feature; it is a necessity in a world where information is power. As a citizen of a world in shambles that can only be save by technological ingenuity that surely includes the democratization of the best text editor ever, it's not a question of if such a enhancement will be done, the real question is "when" and "by whom".

Godspeed.

[c4rlo]

There was another website, https://vim.help, which presented the Vim docs with various layout changes that I think may have included reflowing the text as you describe. Its GitHub repo is https://github.com/cheap-glitch/vim.help. However, the website itself is apparently offline now (see also cheap-glitch/vim.help#12).

[ychin]

A good reference is to look at Neovim's online documentation tool (https://neovim.io/doc/user/) which supports a "flow mode" / "new mode", which gives you reflowable layouts for the whole page, but requires you to author it with certain restrictions. The guide for writing documentation in that format can be found at https://neovim.io/doc/user/develop.html#dev-doc under "Documentation format". It's a selective toggle and only some files have it turned on (the list is located in gen_help_html.lua). For some examples of documentation using flow mode, see api.html and ui.html. It requires specifically authoring your docs files to fit this more restricted format though.

The way the tool works is that it uses tree-sitter (of course, since if you have a hammer, may as well use it :P) to parse the Vim documentation, and then the tool generates the documentation. This works both for the flow mode and "old-style" pre-formatted documentation and it is how they parse the syntax information for highlighting and whatnot. Because of this more rigid approach, a lot of existing Vim documentation don't really work and they went and re-formatted a lot of the Vim documentation files to make them fit a more uniform scheme (for example, look at https://vimhelp.org/arabic.txt.html and https://neo.vimhelp.org/arabic.txt.html to see how the former is quite poorly structured and Neovim's version had it formatted more like the other Vim docs).

My 2c is that if you want to do this, it would require a fair bit of work to iron out the edge cases. The Vim documentation are quite unstructured, and not really well designed to be parsed by a standard logic. Neovim is trying to do that with their tool but even then it falters a bit with more complicated formatting. You can see that with their api.html file where they just turn anything that they couldn't resolve into a preformatted code block, which works, but makes texts like |bufnr()| not a clickable link anymore. I actually spent a bit of time to see if I could fit MacVim's documentation to their system but eventually felt that it was too much effort and required a fair bit of changes (basically everything has to be a bulleted list).

I do think there are probably other ways to address this if you don't really need the docs to fit a tight grammar though (e.g. just have some heuristics to decide what part is reflowable texts, what part could be rendered using a table, and what parts just use preformatted). Probably still a fair bit of special edge case handling would be needed and some routine upkeep to handle upstream Vim introducing new docs that would break your handling. Looking at vim.help seems like it just had some simple regex matching (e.g. for tables it's just indentation) and I guess that worked well enough? It does need to maintain a custom corrections file to handle special case, and seems like (from archive) it only ported the user manual and not the other parts of the documentation, presumably because those other parts have a lot more hard-to-parse pre-formatted information.