JM Marcastel <d...@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>
