Re: style: .MR

[G. Branden Robinson]

At 2022-02-07T22:08:34+0000, Humm wrote:
> > Thus if you wanted to talk in a section 2 or 3 page about some C
> > function name that has a man page to which you'd already referred, you
> > would write, for example.
> > 
> >  The
> >  .MR gmtime\c
> >  () function converts the calendar time
> >  .I timep
> >  to broken-down time representation,
> 
> Why not accept an empty second argument and puncuation?
> 
>       .MR gmtime "" ()

That looks too much like cleverness to me, but I suppose there is a
certain amount of subjectivity to these things.

I've done my level best in current groff documentation to get rid of the
mystique around `\c`.

> I don’t get why you wouldn’t just use -mdoc and leave -man as it is.

As I said years ago on this list when I embarked on improving man(7)
(mostly _not_ with new features, but with bug fixes), if mdoc(7) were
going to eat man(7)'s lunch, it would have happened by now.  It's had 30
years.

I find mdoc's lexicon too large, its tendency to accumulate unbounded
lists of internally maintained identifiers dispiriting, and its design
feature whereby every macro carries two independent bits indicating its
"parsed-ness" and "callability" impenetrable.

Further, high-quality dead tree typography is an explicit anti-goal of
its development.  All mandoc(1) cares about is the terminal and static
HTML.  groff's overall mission does not permit the abandonment of
typesetting.

Nevertheless I won't deny its advantages where it has them.  I've fixed
bugs and brought a couple of new features to groff's mdoc(7)
implementation too.

> On most systems, there is -mdoc, and on the other ones, there likely
> won’t be a -man implementing such new macros.

This will be attributable to laziness or hostility, and not due to
licensing concerns.  Systems still assuming (or imposing) the
six-argument limit on macro calls will be misrendering many pages
_today_.  (Hmm, I never did write down that this is a reason to quote
multi-word (sub)section headings in arguments to `SH` and `SS`.)

> Making cross references links is nice, but I could totally live with
> not having that at all with -man.

I don't expect many epiphanies--I simply want to deliver a better
experience for those who are open to it.

> (That doesn’t seem like a better imagination though.)

Just last month I was spending some sweat generating a table of contents
for the new 380+ compiled groff-man-pages.pdf document--I'd had my face
in the 1970s Unix manuals recently-- when Deri James emailed me out of
the blue with a shockingly short patch enabling PDF bookmarks in man(7).

All of a sudden I didn't need to bother.  In any reasonable PDF viewer a
table of contents is available in tree form, resizable, depth-foldable,
hyperlinked, and not a page number in sight.  That's improvement.

Granted, we pay a price with several more annoying diagnostics "can't
output node in transparent throughput!  OMG!".  But at least I finally
understand that hopelessly inscrutable message.  Enough that I am
prepared to try to kill Savannah #61407 in the formatter if necessary.

How's that[1] coming, Deri?  :D

Regards,
Branden

[1] https://savannah.gnu.org/bugs/?61407

signature.asc
Description: PGP signature