[Top][All Lists]

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

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

From: Alejandro Colomar (man-pages)
Subject: Re: Plan 9 man added a new macro for man page references
Date: Wed, 4 Aug 2021 11:44:32 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.12.0

Hi, Branden!

On 8/4/21 10:57 AM, G. Branden Robinson wrote:

I pretty much share Dave Kemper's perspective on this, to which I would
add, if mdoc were going to bury man(7) in the backyard, it's had 30
years to do so.  Waiting longer is not going to clear man(7)'s problems
off of our plate.  Those which are remediable with a good cost/benefit
tradeoff should be implemented.

Maybe the next generation will finally Sphinx its way to documentation
format supremacy, the way Git arrived late to the revision control wars
and nonetheless proceeded to eat most of the mindshare of its rivals.

If that's what happens, that's okay; I'll adapt.  But in the meantime,
people are _trying_ to write good documentation in man(7), and I want to
help them.  You do too--you process their patch submissions every day.

I'm stubborn about several things, like escaping hyphens, but I don't
have a good answer for people who ask where inter-page linking support
is.  It should be there.  And it can be supplied without bloating the
language[2] or breaking existing pages.



Anyway, .MR wouldn't be so much about content semantics, but more about inter-man-pages relationships, which seems inherent to man-pages. So yes, it probably deserves addition to man(7).

[1] "Tag" may be a _broad_ semantic category, but of itself it tells you
     absolutely nothing about presentation.

That's funny, there's no [1].  :)

     The other hole in man(7) functionality that pains me, and which I
     see people deploying ersatz simulacra thereof, is the list.[3]  Our
     own page groff(7) sins voluptuously in this respect to produce
     lengthy references of escape sequences, request names, and built-in
     registers.  Fixing it will require a major overhaul.  I'm not sure
     what I want to do about this yet.  mdoc has tackled the
     problem--with a frighteningly complex interface.  I question the
     wisdom of "porting" mdoc's "Bl" to man(7) under any name.

One thing I'll ask, if I may:

If you port it with the same exact features, could it come with the same exact name? Well, .BL to keep uppercase man(7) conventions. That would reduce brain load. :)



Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

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