Re: Modernising UNIX manpages.

[John Gardner]

>
> I would like to investigate the possibility of using Markdown as an
> alternate format for UNIX man-pages.


You picked the worst possible markup imaginable. Not just for man pages,
but for any technical documentation, *period*. If you're interested in
"modernising", I suggest rewriting man pages to use mdoc(7).

Markdown has one feature: readability. That's literally it.

On Thu, 22 Apr 2021 at 02:57, Eric S. Raymond <esr@thyrsus.com> wrote:

> 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>
>
>
>
>