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

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Hi everybody,

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

On 2023-08-10 12:32:39, Dmitry Shachnev wrote:
> On Thu, Aug 10, 2023 at 10:41:03AM -0000, Guenter Milde via
> Docutils-develop wrote:
> > On 2023-08-09, Dmitry Shachnev wrote:
> > > On Tue, Aug 08, 2023 at 07:58:28AM -0000, Guenter Milde via
> > > Docutils-develop wrote:
> >
> > >> > Another possibility would be using the `.UR` / `.UE` macros to
> > >> > produce hyperlinks. They are described in groff_man(7) man
> > >> > page.
> > ...
> > >> How would this be handled by other (t)roff converters?
> >
> > > What other implementations do we want to support?
> >
> > I remember discussions about the BSD versions but don't remember the
> > outcome.  Engelbert is our specialist for the man writer.
> 
> FreeBSD's and OpenBSD's man(7) mention the .UR / .UE macros:
> 
>      UR  Begin a uniform resource identifier block.  This is a
>          non-standard GNU extension.  It has the following syntax:
> 
>            .UR uri
>            link description to be shown
>            .UE

This page is elsewhere available as mandoc_man(7), which reveals its
origin.  There are some things to know about the material quoted above.

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.

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.  On many of those
same proprietary/commercial Unix systems, mdoc(7) will not be available
at all; that macro package was developed by the UC Berkeley Computing
Science Research Group for release in 4.3BSD-Reno (1990), whereas
proprietary/commercial Unices were in the Unix System V line of descent.

groff and mandoc(1) are both of course available for any flavor of Unix,
but such proprietary/commercial Unices as still survive often exhibit
diffidence about incorporating them.  On the bright side, Solaris 11
replaced its proprietary troff with groff, HP-UX has been packaging
groff as an add-on for years (providing 1.23.0 packages within days of
upstream release), and Mike Fulton of IBM has been in touch with groff's
mailing list to help us address portability issues to AIX/z/OS.  (There
appear to be no serious problems, thanks to the presence of an extensive
POSIX-like layer, much as we can say for Cygwin and MSYS2 on Windows.)

The gr...@gn... mailing list is the Internet's water cooler for nearly
all public discussion of roff/nroff/troff/groff, leaving aside social
media outlets like Reddit and StackExchange which serve as Q&A forums.

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.

> Although, they also say "Use the mdoc(7) language, instead", and
> mdoc(7) does not mention these macros.

mdoc(7) uses a _completely different lexicon_ of macro names.  There is
literally no overlap between the two.  mdoc(7) names are spelled with an
initial capital letter and lowercase second letter; man(7) names are
spelled with two capital letters.  These are what you might call mere
conventions, but they have been rigidly held to.  The only exception
known to me is now-dead commercial Unix system, DEC Ultrix; it had `Ds`
and `De` macros for setting "displays", a concept man(7) and mdoc(7)
don't otherwise use.

mdoc(7)'s macro repertoire is many times the size of man(7)'s, and it
also has a unique approach among all *roff macro packages known to me
regarding macro argument handling.

In a footnote, I'll quote explanation of this in the groff_mdoc(7) page
in the groff 1.23.0 release.[2]

At any rate, a man page cannot mix man(7) and mdoc(7) macro names and
hope to render correctly.

> The same for .EX / .EE which we started using recently.

By one measure, `EX` and `EE` are of the same vintage as `UR` and `UE`;
they have been supported in groff releases for 14 years, and by
mandoc(1) for over 11 years.[3]  About a year ago, Ingo even conceded
their utility.[4]  :)

By another measure, `EX` and `EE` are 37 years old, since they appeared
in Ninth Edition Unix man(7).[5]

groff's man(7) extension macros are very permissively licensed.  No page
author that is concerned about their document remaining portable is
subject to any legal restriction on copying and using them.[6]

If there's anything I can shed light on, please ask.

Regards,
Branden

[1] https://cvsweb.bsd.lv/mandoc/man.c?sortby=date (revision 1.120)

[2] [UTF-8 follows]

    Most of mdoc’s general text and manual domain macros parse their
    argument lists for callable macro names.  This means that an
    argument in the list matching a general text or manual domain macro
    name (and defined to be callable) will be called with the remaining
    arguments when it is encountered.  In such cases, the argument,
    although the name of a macro, is not preceded by a dot.  Macro calls
    can thus be nested.  This approach to macro argument processing is a
    unique characteristic of the mdoc package, not a general feature of
    roff syntax.

    For example, the option macro, .Op, may call the flag and argument
    macros, .Fl and .Ar, to specify an optional flag with an argument.
          .Op Fl s Ar bytes      → [-s bytes]
    To prevent a word from being interpreted as a macro name, precede it
    with the dummy character.
          .Op \&Fl s \&Ar bytes  → [Fl s Ar bytes]

    In this document, macros whose argument lists are parsed for
    callable arguments are referred to as parsed, and those that may be
    called from an argument list are referred to as callable.  This
    usage is a technical faux pas, since all mdoc macros are in fact
    interpreted (unless prevented with ‘\&’), but as it is cumbersome to
    constantly refer to macros as “being able to call other macros”, we
    employ the term “parsed” instead.  Except where explicitly stated,
    all mdoc macros are parsed and callable.

    In the following, we term an mdoc macro that starts a line (with a
    leading dot) a command if a distinction from those appearing as
    arguments of other macros is necessary.

[3] https://cvsweb.bsd.lv/mandoc/man.c?sortby=date (revision 1.116)
[4] https://lists.gnu.org/archive/html/groff/2022-08/msg00081.html
[5] https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html
[6] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an-ext.tmac?h=1.23.0