Re: ripgrep author seems happy with groff_man_style(7)

[onf]

Hi,

On Tue Jan 21, 2025 at 8:19 PM CET, G. Branden Robinson wrote:
> At 2025-01-21T16:05:18+0100, onf wrote:
> [...]
> > Don't get me wrong, it's nice that one can link to a specific
> > (sub)section of an HTML manpage, but that's completely missing the
> > point of the feature I was actually talking about, which is the
> > ability to jump to the definition of a term in the manpage.
>
> https://knowyourmeme.com/memes/theyre-the-same-picture

They are not. There is a difference between generating anchors for SH
and generating anchors for flags, constants, etc. The latter cannot be
done automatically in man(7).

> [...]
> > I agree it would be nice if one could link to subsections and, more
> > importantly, terms within other manpages. As a matter of fact though,
> > man(7) can't even tag terms within the same page.
>
> It's the same problem with the same solution, as I conceive it. [...]

How are you going to add automatic tagging for e.g. environmental
variables in a language that has no concept of them, exactly?

> > I've spent some time writing mdoc(7) lately while working on a
> > reference for neatroff, and I guess I just don't get why anyone is
> > using man(7) anymore.
>
> I have some reasons. [...]

Perhaps you should consider listing them. It would certainly contribute
more to the topic than spending over two pages rambling about your views
on mdoc's history.

> > I'm not saying mdoc is perfect; it certainly doesn't afford me
> > the level of control I am used to from writing plain *roff, but it
> > pays off in the language's descriptiveness, relative ease of use,
>
> I think (1) its macro lexicon is too large; (2) its DWIM-ish
> interpretation of isolated punctuation arguments, combined with its
> unique in-package macro interpreter, make it a poor base camp from which
> to make further forays into *roff document formatting;

Its interpretation of punctuation can be easily disabled by the
addition of \&.

> and (3) its
> community has too many Kool-Aid drinkers.  You're unusual in that you
> led a paragraph with an acknowledgement of its imperfection.

I take offence at being likened to people from the Jim Jones cult.

The reason I favor mdoc is because it's semantic and easier to both read
and write.

> With man(7), that concession can be taken as read.  :)  Nobody's madly
> in love with it, but one can learn--I think without much difficulty--how
> to get things done.

Without much difficulty? Perhaps for people who already know *roff.
The abundance of man(7) generators shows many people have different
opinion. If the language was simple for an outsider to understand,
nobody would have spent time writing them.

> > and especially the terms/tags, which are incredibly practical.
>
> About that I have nothing bad to say (though I haven't actually
> _exercised_ this feature aggressively).  It's a good feature and that's
> why I want to recapitulate it in man(7).

Except in man(7) it will either require added effort from manpage
writers or be much less useful.

> > I can imagine the language being much more approachable for people
> > lacking knowledge of *roff, too.
>
> Yes, they can acquire a sort of anti-knowledge they'll have to forget if
> they ever use any other *roff macro package.  Ah well.  That ship sailed
> 35 years ago.

Not really. Given how mdoc hides most of *roff, it can simply be taken
as its own markup language which was only incidentally implemented as
roff macros.

> [humongous digression follows]
> [...]and--so my psychic powers reveal--[...]

I think this could be taken as a summary of the entire tangent.

> How we got here, why mdoc looks the way it does in some respects--much
> of that is not a happy story.  It would have been better for everyone,
> in my opinion, for the BSDs to say, "hey, there's a basically free *roff
> implementation that we _already distribute_ that has a man(7)
> implementation.  AT&T/USL will not be able to take that away from us.
> Let's make man(7) better, like Sun did.[4]"  But, that's an alternate
> timeline.  [...]

You seem to be entirely ignorant of the value of semantic macros.

> Now then--all of that said, I have no particular beef with the mdoc(7)
> language or the mandoc(1) formatter.  They are here, they exist, and,
> quite fortunately, Ingo is someone I can work easily with and who seems
> to reason about engineering decisions much in the same way I do.  So I
> aim to continue maintaining groff's mdoc(7) implementation as well as I
> am able--which, as with every other aspect of groff--may fall short of
> adequacy in the eyes of some.  There's a lot of work to do and limited
> time, notably once one subtracts that spent composing emails like this.
> But no one put a gun to my head and made me write it.

I will just note that what you wrote was entirely your decision;
I didn't ask you about mdoc's history at all. I merely wondered why
people use man, which you haven't answered yet. All I've read (or
inferred) is that you don't see any value in mdoc and would prefer
if the BSD people used man(7) with groff.

> > >         Because mdoc(7) culture is rigidly prescriptive, its section
> > >         headings are tightly controlled, and I expect that this
> > >         problem only threatens when subsections are used (and
> > >         referenced).
> > 
> > Although mdoc(7) says something to the effect of:
> >   For a list of conventional manual sections, see MANUAL STRUCTURE.
> >   These sections should be used unless it's absolutely necessary
> >   that custom sections be used.
> > 
> > ...in reality it itself uses non-standard section headings:
> >   Name
> >   Description
> >   Manual Structure
> >   Macro Overview
> >   Macro Reference
> >   Macro Syntax
> >   Compatibility
> >   See Also
> >   History
> >   Authors
>
> Yes, some--not all--of those are unconventional.  I wouldn't say "not
> standard" because we have no standard to which to point.  Just
> conventions, some of which have been codified in style guides.

I know not all are unconventional. I just gave you a list of all the
section headings it has.

> > I think the point is more about sticking to conventional section names
> > if possible than about forbidding non-standard ones.
>
> I think I have seen Ingo do the latter, but I could be mistaken.
> [...]

Fair enough. I have learned to ignore suckless-style evangelism for
some sort of One true way in software that must always be followed.
That is not to say one cannot see some software as superior to another,
though.

~ onf