Man pages are great, man readers are the problem

Formats: roff/mdoc vs HTML/Markdown

• Several comments argue roff/mdoc is already a “modern” semantic format compared to HTML, which is easy to parse but unpleasant to write, and Markdown, which is familiar but largely semantics‑free.
• Advocates of mdoc emphasize its explicit markup for flags, arguments, env vars, etc., which powers apropos/whatis queries, smart search, and hyperlinking. Converting to Markdown or plain HTML often discards this information.
• Others prefer authoring in Markdown/RST/AsciiDoc and generating man pages via tools (pandoc, Sphinx, Asciidoc, scdoc), but there is concern about:
  • Many incompatible Markdown dialects.
  • Loss of semantics and links.
  • Needing increasingly complex “markdown schema” and tooling that just re‑creates roff’s complexity.
• GNU info/texinfo is mentioned as an earlier attempt at richer, linked docs; technically good but hampered by poor standalone viewers and unfamiliar UI.

Readers and UX: terminals, editors, and GUIs

• Many suggestions to fix the reader, not the format:
  • Use man --html or web manpage mirrors; OpenBSD’s mandoc HTML is praised.
  • Emacs (man/info/woman), Vim/Neovim as MANPAGER, KDE Help Center, Dash/Zeal, pinfo, xman, and bat‑based pagers add links, search, highlighting, or nicer layout.
  • mandoc on BSD preserves semantics into less (ctags‑style jumps) and into HTML, including links directly to option definitions.
• Pain points with traditional man | less:
  • Line wrapping destroys indentation; no semantic “jump to flag” (people rely on regex searches like ^\s+-p).
  • Long pages (e.g., bash, tar) are hard to navigate; some print to PostScript/PDF (man -t) to see intended structure.
• Some highlight a skills gap: job control, less navigation, and info usage are not widely understood by newer users.

Content quality and examples

• Strong split:
  • Some praise manpages (especially BSD) as cohesive, dense, and sufficient when well‑written.
  • Others say manpages “suck”: too much dry option listing, too few examples and workflows, leading to tldr/cheat/bro pages, Stack Overflow, and now LLM wrappers.
• There is broad agreement that:
  • The framework is fine; the art of writing good documentation is the real bottleneck.
  • More examples, single‑page versions, and good printability would make man‑style docs much more useful.

Conventions and ecosystem

• Debate over relying on --help vs man:
  • --help is convenient but inconsistent, may require running the program, and often misuses stdout/stderr.
  • Manpages are more standardized across Unix systems, especially under distro policies.
• Underlying theme: the Unix/GNU/Linux documentation ecosystem is powerful but fragmented; attempts to “modernize” risk throwing away existing semantics unless they carefully preserve them.