Re: ripgrep author seems happy with groff_man_style(7)

[onf]

On Tue Nov 5, 2024 at 12:10 AM CET, Alexis wrote:
> > I was reacting to the first sentence, which you've left out 
> > above. My comprehension of it was that when I say it takes
> > several hours, I must mean man rather than mdoc, to which I
> > was saying: no, it takes a while with both packages. I might
> > have misunderstood you, though.
>
> Oh, i see. No, all i was trying to do was confirm that you'd been 
> working with man(7), not mdoc(7) (because most of the time, when i 
> encounter people complaining about the challenges of writing man 
> pages, they are indeed using man(7)). i wasn't trying to imply 
> anything other than that, and certainly not wanting/trying to 
> imply that it's _only_ man(7) that takes several hours to learn.

I don't think I was complaining about the difficulties of writing
manpages, though. (Especially because I have never even tried writing
one so far, the most I did was edit some.) I wrote to Branden:
> I don't think it's as simple as you present it. I totally understand
> why people don't want to spend several hours understanding troff
> syntax just to be able to document the flags and key bindings of
> their program in manpage format.

Learning any new (non-trivial[1]) language takes time, and if the
only motivation one has is to format the contents of their program's
--help more nicely, I am not surprised many opt to use a generator
in an attempt to limit the time spent and make the document more
approachable for others. The former might not come out true, but
the latter does.

I get your point, though, in that mdoc macros are easier to learn,
because they describe the structure of the document rather than its
looks, which makes them much more intuitive than man.

> [...]
> The particular bee i have in my bonnet, in this context, is my 
> overall experience of the 'dark theme' crowd. i've regularly see 
> outrage when a dark-theme-preferrer is presented with something 
> with what's effectively a light theme, and an expectation that a 
> dark theme will be provided as an alternative, but i've seen 
> little evidence of dark-theme-preferrers seeking to provide a 
> light theme for when the situation is reversed - with the overall 
> effect being "dark themes are objectively better for everyone, you 
> just have poor taste or don't know what you _really_ need". 
> [...]

I have seen similar behavior online as well, particularly on Reddit
where similar "tribal thinking" is commonplace.

Personally, I dislike any "themes" that are imposed on me by someone
else. For instance, while many websites use "modern" dark themes,
I would be much happier if those websites were usable in Lynx and
I could use them with the same color and font settings I have
everywhere else, rather than being presented with huge letters
because the authors thought it's a good idea to set regular text
in size 15.[2]

In short, I think appearance should always be configurable.
(Which becomes very easy when the program in question is running
in terminal, at least as far as colors and fonts are concerned.)

> > I understood it's more of an introductory text rather than a 
> > full reference, I guess I just didn't get it's meant more as a
> > "teaser" (for a lack of better word) than a full introduction.
> > [...]
>
> 'Teaser' is also a reasonable word. Of course, i didn't use the 
> word 'introduction' in the title; the phrase i actually used in 
> the title is "a quickstart guide", which to me suggests "getting 
> you started [with the basics]". But still, i appreciate knowing 
> the impression that the document gave you, and yeah, i'll make the 
> changes i mentioned in my previous email.

Oh well, I guess I missed the quickstart part.. (:

> > > Yes, but this document is about mdoc(7), not about the 
> > > specifics of exit statuses, so i'll just remove the second
> > > sentence.
> >
> > I know it's not about exit statuses. What I was trying to say is
> > that if such a sentence appeared in an actual manpage, it would 
> > be technically incorrect, because a program cannot return -1 on 
> > Unix, so it shouldn't appear in an example of how to write a
> > manpage either.
>
> Sure; as i said, i'll remove that text. When i was putting that 
> piece together, i was primarily focused on trying to demonstrate 
> how mdoc(7) _macros_ are used to write man pages, not "this is how 
> to write a man page in general, using mdoc(7)". Yet the title i 
> used for the document was "Writing man pages with mdoc(7)". :-P So 
> i need to change that title, and perhaps i should just use lorem 
> ipsum in the contents of the example man page ....

I don't think replacing it with lorem ipsum would be reasonable...

All I was trying to suggest (and perhaps I should have been more
direct about it) was that you replace the -1 with something that
a program might actually exit with on error, such as 1 (which is
the standard, as the Ex macro shows). I believe any n: 0<n<128
should be safe to use (not sure about the higher values since
some are used on signal-triggered exits etc.).

~ onf

[1] With gemtext being an example of a relatively well specified
    trivial markup language:
    https://geminiprotocol.net/docs/gemtext-specification.gmi

[2] Many would actually be somewhat usable if they didn't rely on
    Cloudflare's surveilance JavaScripts for "DDoS protection"
    which prevents anyone not using a "modern" (read: easy to track)
    browser from accessing the site.