Use various macro packages in the same page (was: Re: Plan 9 man added a new macro for man page references)

[Alejandro Colomar (man-pages)]

Hi,

On 8/3/21 11:41 PM, Dave Kemper wrote:
> 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.

That also seems reasonable.

Something that I already had in mind some time ago came to my mind again 
with this.  I don't know much of groff, so it may not be possible, but 
I'll ask anyway.

Is it possible to use more than one macro package at the same time?  (As 
long as they are compatible, or you use compatible features, of course.)

I mean like using 2 C includes, <stdlib.h> and <stdint.h>, where you get 
the definitions of functions/macros from both and you can use them all. 
 With some exceptions, as for example including both <string.h> and 
<libgen.h> and using basename(3) wouldn't probably work; that's what I 
meant with compatible features.

Being able to use both mdoc(7) and man(7) in the same file would:

- Remove the need of man(7) for a new semantic .MR macro
- Easen the transition from man(7) to mdoc(7), as it could be done in 
many small steps, taking first what's most useful from mdoc(7).

I guess (but don't really know) that it's not possible currently, but is 
it something that groff(1) could add as an extension feature? 
Supporting something like `groff -man -mdoc ...`.

Thanks,

Alex



--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/