Re: Modernising UNIX manpages.

[Eric S. Raymond]

JM Marcastel <don@marcastel.com>:
> Dear all,
> 
> I would like to investigate the possibility of using Markdown as an alternate 
> format for UNIX man-pages.
> (Cf. https://github.com/marcastel/marcastel/discussions/7)
> 
> Rather than re-inventing the wheel I would ideally like this to become part 
> of an existing tool (mandoc, groff, …).
> 
> I would like to devote time to this in the second semester of 2021 and would 
> appreciate sharing this.
> 
> I believe the first step is to provide a proof of concept what demonstrates 
> the expected outcome and that desired command line interface.
> 
> I have a clear idea on how to build that POC once the requirements have been 
> set.
> 
> Has this already been studied? Would this be an initiative you would support?
> 
> Best regards,
> JM Marcastel

I've studied the problem of moving man pages to a less Paleolithic format very 
closely.  I've even
written a program that automates the process pretty effectively - doclifter.

Here's what I know.

1. Sorry, Markdown is a *terrible* choice.  Which dialect? It's simply not 
standardized enough.
It's also semantically rather weak, especially near tables.

2. DocBook-XML is excellent at capturing the kinds of semantics you
wamt for very sophisticated querying.  It also renders to very good HTML, better
that you can make from a weaker markup. But it has one serious flaw - it's 
sufficiently
heavyweight to be unpleasant for human editors.

3. Presently I master my manual pages in asciidoc.  It can be rendered to 
XML-DocBook,
is much easier to write, and is enough stronger and more standardized than 
Markdown
to be a clearly better choice. Its only serious drawback reklative to 
XML-DocBbook
is that you lose the ability to do structured markuo of command synopses.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>