[groff] Re: Modernising UNIX manpages.

[Mike Bianchi]

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

For what it is worth ...

This is a very old story and I might not have all the details correct,
but the basic message fits here.

And the basic message is:
        Once you have a stylized markdown for man-pages that produces a
        stylized output of groff, mandoc and/or html

        create back-converters to turn changed output into the source form.

The story is from the mid 1970s.  A friend worked on a project that used
a "data dictionary" (https://en.wikipedia.org/wiki/Data_dictionary) and
a specification language (spelling out the functionality of the code in
stylized English) to drive translator programs that produced:
        IBM IMS (Information Management System) database specification language
 and    COBAL code and functions for accessing the databases.

The inputs AND outputs were _so_ stylized that making changes in any of the
outputs were translated back into the input specification language
and data dictionary with reverse-translator programs.
The translation paths thus became a circle.
Changes could be made in any of the output forms and reflected back into the
other input forms.  All the input forms were human-readable.

Someone who could only read the data dictionary could change the code in a
predictable way.  Likewise for someone who was IMS-knowledgeable.

Over time the project became very stable.  Changes were reliable.  When bugs
were found the bug-fixes were often in the translators.
Thus finding one bug would often fix many more un-found bugs.

IFF such a thing could be accomplished for the man-pages, then maintaining
them would be something that could be passed along down the generations.
((I am 73 years old.  I grew up with nroff/troff/groff.
I think I have written my last man-page.))

I imagine pairs of translators, like maybe:
        markdown <-> mandoc
        mandoc   <-> groff
        groff    <-> html

The <-> translators might be macro packages (for groff, or may mom) or
could be written in a Python, Ruby, or something else.
It would have to be a team effort with team consensus.

                                                                Mike

On Wed, Apr 21, 2021 at 05:46:58AM +0200, JM Marcastel wrote:
> 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
>

--
 Mike Bianchi
 Foveal Systems

 973 822-2085

 MBianchi@Foveal.com
 http://www.AutoAuditorium.com
 http://www.FovealMounts.com