Re: Modernising UNIX manpages.

[JM Marcastel]

> On 21 Apr 2021, at 18:56, Eric S. Raymond <esr@thyrsus.com> wrote:
> 
> 1. Sorry, Markdown is a *terrible* choice.  Which dialect? It's simply not 
> standardized enough.
> It's also semantically rather weak, especially near tables.

I was expecting that one :-)

Let me put differently. Markdown is the style. YAML is the structure. Combine 
them and you have a human friendly and modern (structured) markup language 
(sorry Goldfarb).

Want I call Markdown is Pandoc markdown — and CommonMark since John MacFarlane 
is behind both and the standard is maturing fast. (BTW Pandoc does a good job 
at tables).

Rather than putting YAML into Markdown, as is commonly the case — typically for 
static site generators, put Markdown in YAML. That gives you structure (and 
since JSON is a subset of YAML, you already have an interchange format that can 
be easily manipulated in any program). All that remains to be done is to build 
a *schema* for manpages using that construct. This approach is coming of age in 
the API world (RESTful APIs in particular). Setting up a formal structure in 
YAML is easy. Beyond being manpage-compatible I easily imagine translators to 
generate the input for GNU’s `gengetopt` or for KornShell’s embarked (and 
excellent though a little obscur)  `getopts` auto generated man pages (already 
at the time in a variety of formats (try options —nroff, —html, —api on any 
KornShell script using getopts or on the ksh binary itself).

As mentioned in my original discussion 
<https://github.com/marcastel/marcastel/discussions/7>, I have a clear idea on 
how to deliver a proof of concept (with Pandoc (Haskell) and Glow (Go)). Though 
in my mind target utility would be written in C (or Go). Pandoc exposes an 
abstract syntax tree of both YAML and Markdown. Glow saves us from having to 
write a ncurses interface by already providing on-terminal display of essential 
Markdown markup (including tables). What I am missing is exactly what triggered 
reactions against Markdown: the structure, the constraints… where we mark the 
line between free form layout in Markdown (e.g. cross referencing manpages in 
text) and structure imposed through our YAML skeleton.

A side by side comparison of the current manpage markup and the to-be markup. 
How to maintain backward compatibility while providing new features (tables, 
modernise the display with clickable hyperlinks 
<https://iterm2.com/documentation-escape-codes.html>, images 
<https://iterm2.com/documentation-images.html>, and other goodies on 
VTE-capable <https://wiki.gnome.org/Apps/Terminal/VTE> terminals). Etc.

IMHO Markdown and YAML are the way to go, but should another format be better 
suited I have no objection. Despite my humble participation in such initiatives 
as ISO 8613 (in the late 80s already!), I am convinced we should steer away 
from DocBook and the likes (even ASCIIdoc is too…. technical). Yesterday’s 
manpages were managed centrally by highly knowledgeable persons. Tomorrow's 
manpages should solve the MANPATH hell, one should be able to easily correct or 
amend them, and they should always be up to date, both on the terminal and 
online. People of all skills and origins should be able to contribute. For this 
we need the Tim Berners Lee HTML-attitude… simple (but not simplistic) markup.