💾 Archived View for idiomdrottning.org › the-dystopia-of-web-only-documentation captured on 2024-05-12 at 15:20:45. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-12-28)
-=-=-=-=-=-=-
Once upon a midnight dreary in December 2023 I came across this 2014 post by ESR about his plans to move FSF documentation to the web, with the final two steps being
Some time ago I added to Linux man(1) the capability to recognize HTML pages in the man hierachy and kick them over to the user’s Web browser. All Linux and *BSD distributions now ship this code.
and
Kill off info. [...] Where we’re probably going is that (a) info will die, to be replaced by HTML browsed from within Emacs, and (b) Texinfo will be replaced by a modern lightweight format that can render to both print and HTML; most likely asciidoc.
I’m glad this didn’t happen (especially with the benefit of ten years of hindsight knowing the web is 1000000% pure garbage, even though the web was bad back then too).
Having HTML/web-based ways to read man pages and Texinfo documentation is awesome, yes. If those ways are in addition to the traditional ones.
Texinfo in particular is structured, semantic, accessible, and has a glorious legacy of being one of the very first public hypertexts.
Rather than killing it, I’d want to:
As much as I hate the web, being able to search up documentation on the web and read it right there is a good thing. Not as much in practice, but as a just-in-case if the web somehow becomes good again. For that matter, using Gemini for this might make a lot more sense.
Having a light-weight source language designed with Texinfo in mind would make writing it a lot quicker and easier. A good source language for Texinfo would have all the stuff it needs while getting out of the way for everyday stuff like paragraphs. The converted could help autogenerate tables-of-contents and stuff or prompt for missing metadata fields.
Or even improve them or make new and better ones. That’s one of the main benefits of a format like Texinfo, it’s so structured, so ordered, no popups or tracking or wasm, just documentation.
Re: [Groff] man pages (tangential to Future Redux)