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

[Alejandro Colomar (man-pages)]

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.
>
> Regards,
> Branden

Agreed.

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.  :)


Thanks,

Alex



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