Re: Modernising UNIX manpages.

[JM Marcastel]

> On 22 Apr 2021, at 09:35, Marc Chantreux <eiro@phear.org> wrote:
> 
> *But* if there is a tool that just read a code written in (name your preferred
> langage) and write the mandoc output (eventually use comments for the
> other parts), i really would give this tool a try.


Perhaps Markdown is not the appropriate markup. But neither is mdoc (at least 
in my current understanding of its scope and capabilities).

Choosing an alternate syntax is not simply about enhancing the user’s on-screen 
experience with images, tables, and other goodies now possible on terminals.
Though the snapshot below would obviously bring new documentary capabilities to 
manpages.

If all that can be done in mdoc, then fine, I am willing to give a try… even if 
a little frustrated by an antiquated markup syntax.

A great achievement, in my view, would be to bring into UNIX manpages some of 
the achievements of Texinfo. Unsorted:
- Content structure (not simply outlining)
- Efficient cross-referencing
- Lists and tables
- Special displays (floats, images, footnotes)

And of course, a fantastic info tool that knows how to take advantage at build 
time of all the contextual information we have about the document to help you 
navigate.
We are not simply piping a man page through a pager, we are navigating the 
documents.

Once we have that extra data available, somewhere (mandb?) we can further 
enhance the pertinence of our manpages.
Extra utilities taking further advantage of this (consolidate, aggregation, 
dependency graphs,...).

The start of all this, is the markup.

Don’t you think it is about time to do, if not a quantum leap, at least some 
modernisation ?
(Re)make UNIX manpages the “indispensable masterpiece for system users and 
developers” (to paraphrase Dash <https://kapeli.com/dash>)

P.S. The snapshot below cost me approximately 10mn (Markdown abstract tree + 
script to base64 encode the image and wrap it in a ANSI escape code for the 
terminal).
And this is by no means dedicated, since the same Markdown can be used to 
generate HTML, PDF, and more.
How long would it take to incorporate such functionality with mdoc ?