Re: [docutils:feature-requests] Re: #72 rst2man: Show reference targets

"G. Branden Robinson" <[email protected]> Sun, 13 Aug 2023 05:11:07 -0500
Newsgroups	gmane.text.docutils.devel
Message-ID	<20230813101107.m6fo7bim6sqvatlh@illithid>
At 2023-08-13T09:30:40-0000, Guenter Milde via Docutils-develop wrote:
> Hi Branden,
> 
> welcom to the Docutils developers list.

Thank you!  Glad to be here.

> On 2023-08-12, G. Branden Robinson wrote:
> > 1.  mandoc(1)'s documentation takes a fairly partisan attitude
> >     toward *roff macro languages; it endorses only mdoc(7),
> >     deprecates man(7), and makes no attempt to support anything
> >     else.
> 
> If I got it right, "mandoc" tries to provide a "semantic markup" layer
> for man pages.

I don't believe that is correct.  First, there are a couple of things
called "mandoc".  It is one way to spell a groff(1) (or troff(1), or
nroff(1)) command-line option and argument combination, as in

groff -mandoc foo.1 bar.2

for example.  This loads a macro file called "andoc.tmac", which uses
some *roff language features to relieve man(1) programs from having to
read man page sources to determine which macro language, man(7) or
mdoc(7), the pages use.  This feature dates back to 1991.

https://git.savannah.gnu.org/cgit/groff.git/tree/ChangeLog.115#n3526

Around 2008, Kristaps Dzonsons of OpenBSD started the "mdocml" project,
an effort to replace the groff (and any other troff) formatter for the
purpose of man page rendering.  In 2009, this project made the decision
to name its formatter program "mandoc", and apparently later that year
Ingo Schwarze decided to rename the entire project after the command.

https://mandoc.bsd.lv/devhistory.html

mandoc, in either meaning, is not a macro language specification or a
semantic markup layer.

mdoc(7), which in its present form originates in 4.3BSD-Reno (1990),[1]
is an alternative to the man(7) macro language for *roff.  mdoc(7)'s
emphasis is indeed on semantic markup.

However, mdoc(7) is not purely semantic, and man(7) is not purely
presentational.

> Docutils aims to provide an alternative easy-to-read semantic markup
> language for man page sources which works on a wide range of systems.

Acknowledged.

> Sticking to the subset supported by groff, mandoc, and Heirloom
> Doctools seems to be a reasonable aproach then.

Cool.  That baseline will avoid some headaches and ugliness.  I can help
with translation to either macro package, but as "rst2man" has "man" in
its name, and the man(7) and mdoc(7) lexicons cannot be mixed in a
single document, is it fair to say that Docutils would like to improve
its production of output in the man(7) language where feasible?

An "rst2mdoc" is, of course, conceivable.

Thank you for putting me in the picture.

Regards,
Branden

[1] Ingo clarified the history recently for me.  The mdoc(7) in
    4.3BSD-Reno is actually the third version of the macro language (not
    counting a few extensions later added by the groff and mdocml/mandoc
    projects).  The second version is known as "old mdoc" and while
    groff, at least, still carries support for it, I don't know if any
    pages in that form of the language survive anywhere.  The first
    version of mdoc, is, apparently, completely lost.

[2] https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/share/tmac/tmac.doc.old
signature.asc (application/pgp-signature, 833 B)