Re: Modernising UNIX manpages.

[Larry Kollar]

JM Marcastel <don@marcastel.com> wrote:

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

My apologies at being a month late to the party.

One thing you might want to take a look at, is how DITA integrates Markdown
into a structured XML environment. In a nutshell, DITA categorizes information
into several types; concept, task, reference, troubleshooting, or generic topic.
If the Markdown topic’s top-level heading has a tag like `{.reference}` then it
renders the topic as a reference. Look up “Lightweight DITA” for details.

You could do something similar, using something like `{.man7}` to assign the
section. Then you might do some validation, to make sure the headers are right,
before producing the manpage.

The big caveat is that Markdown is about as minimalist as it gets. Anything you
want to uplift to, be it HTML, DITA, or manpages, is going to require some 
cleanup
and “this particular italics really means…” structuring. While mdoc is a better
candidate in the long run for writing manpages, the original man macros are a
bit closer to Markdown as far as simplicity. 

Good luck!

— Larry
Unix Text Processing (UTP Revival): now at 
https://github.com/larrykollar/Unix-Text-Processing 
<https://github.com/larrykollar/Unix-Text-Processing>