> > 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 <e...@thyrsus.com> wrote: > 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> > > > >
