Re: Plan 9 man added a new macro for man page references

[Dave Kemper]

On 8/3/21, Ingo Schwarze <schwarze@usta.de> wrote:
> When maintaining a programming or markup language, sparingly and
> cautiously adding new syntax to fill isolated gaps in the feature set
> often makes sense.
>
> When a language is designed from the ground up with one programming
> paradigm in mind - physical markup in the case of man(7) - redesigning
> it for a completely different programming paradigm while in maintenance
> mode seems like a questionable idea to me.

Those seem sound as general principles, but I think what's under
discussion here falls more solidly under the former paragraph above
than the latter.  The proposal is the addition of a single macro,
hardly a paradigm-shifting move.  And part of man's paradigm, from the
start, was viewing documentation in a terminal.  A user viewing one
page might learn that the information she needs is on a different page
-- a situation also present from day one.  The proposal before us is
merely simplifying the process of getting to that new page.  This is
advantageous to the user, but hardly a paradigm shift of the markup
language.

Though HTML was not one of man's original output choices, man pages
have also been rendered that way for decades now, and this is not
going away any time soon.  Links are an integral part of HTML, and any
information within the man page source to assist or improve that sure
seems like a step forward.

I can understand the reluctance to undertake the huge task of moving
an entire documentation set from one markup language to another, even
if the new language already includes this functionality.  But the
fairly simple extension to the man language proposed in this thread:

 - breaks no existing pages; man pages that fail to use it simply lack
these cross links, as they have since the '70s
 - adds useful functionality to those pages that do choose to use it
 - brings groff's man implementation into parity with another roff's
man implementation that already implements it

So there seems little downside to making the feature available in
groff even if some individual projects decline to use it.