> 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
mbian...@foveal.com
http://www.AutoAuditorium.com
http://www.FovealMounts.com
