[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar (man-pages)
Subject: Use various macro packages in the same page (was: Re: Plan 9 man added a new macro for man page references)
Date: Wed, 4 Aug 2021 08:59:21 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.12.0


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

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



Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

[Prev in Thread] Current Thread [Next in Thread]