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

[Guenter M. <mi...@us...>]

Hi Branden,

welcom to the Docutils developers list.

On 2023-08-12, G. Branden Robinson wrote:

> I just subscribed to this list.  I work on groff and would like to help
> improve rst2man's output.

This is good news.

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

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

> 2.  Ingo Schwarze has been the mandoc(1) (formerly "mdocml" project)
>     maintainer for many years now.  He is also a groff contributor and
>     committer and we have worked productively together since 2017 to
>     better establish what it means to have portable man pages.

> 3.  There is no such thing as a "standard extension" to man(7), nor even
>     a standard "core" of man(7)--nor of mdoc(7), for that matter.  That
>     is because these languages have never been standardized.  *roff
>     itself has never been standardized, either.

> 4.  `UR` and `UE` _are_ GNU extensions to man(7), two of several.  They
>     have been supported by groff since 2009, and by mandoc(1) for nearly
>     10 years.[1]

> Unless one is targeting old proprietary/commercial Unix systems, there
> is little reason not to use the dialect of man(7) presented in the
> groff_man(7) page, complete with extensions--with the possible exception
> of the brand-new `MR` macro, a groff 1.23.0 arrival.  

Fine.

> My impression is that nearly all man page viewing that is observable is
> done via groff or mandoc(1).  Heirloom Doctools troff is probably in
> third place, but it too supports groff's man(7) extensions, since it
> incorporates (an old version of) groff's an-ext.tmac file.

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

Thanks again

Günter