Re: Modernising UNIX manpages.

[Marc Chantreux]

hello,

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

I used POD (perldoc) for decades and i'm very fan of pandoc for many
years now (i use it for many things from bills to papers) so i was
i the same mood years ago and started to use sdoc. Someone shared with
me about the bad quality of its output so i learned the basics of roff
to fully understand.

Then i realized that once you discover mandoc, you really have no need
of another tool. I mean: instructions like

     .Sh NAME
     .Nm progname

are:

* easy to learn and write
* push semantic into the document
* is grepable (easy to index/search)

There is no way you'll manage requests like .In, .Fn .Vt, .Ft, .Fn, .Op
with commonmark. I would bet on pandoc (the only one markdown dialect
accceptable to me) but you will need a custom filter there. There is
also an ms writer that could be a start to write a mandoc one.

*But* if there is a tool that just read a code written in (name your prefered
langage) and write the mandoc output (eventually use comments for the
other parts), i really would give this tool a try.

> I would like to devote time to this in the second semester of 2021 and
> would appreciate sharing this.

thanks for that! if you do something around pandoc, i definitely have a
look on it.

> I believe the first step is to provide a proof of concept what
> demonstrates the expected outcome and that desired command line
> interface.

if i would like to start a project like yours nowadays, i definitely
would start by code2mdoc because it's the only part i would use
(as i said: i don't know why i would use an external tool for the rest
because there is not much caracters to spare).

good luck for this project
marc