Re: ripgrep author seems happy with groff_man_style(7)

[onf]

On Mon Nov 4, 2024 at 1:45 AM CET, Alexis wrote:
> "onf" <onf@disroot.org> writes:
>
> >> i certainly agree that, for people not regularly creating new 
> >> man pages from scratch, having to learn roff and a macro library 
> >> probably feels like unnecessary work. 
> >
> > I had mostly based this on the original quotation of Andrew 
> > Gallant, but personally it took me a while just to get acquainted
> > with the general syntax of troff, understanding how macros and
> > escapes work, etc., even before I learned any macros. So no, I
> > think it applies generally.
>
> Sorry, i'm not sure what you're saying "no" to here? i wrote:
> [...]

To include the full quote of your original message:

On Sun Nov 3, 2024 at 8:39 AM CET, Alexis wrote:
> > It's not that documentation isn't important, merely that it's               
> >                  
> > not so incredibly important to spend several hours on such a minor          
> >                  
> > task. This also becomes a problem in that manpages aren't maintained        
> >                  
> > as well as the software because few people understand the syntax.
>                                                                               
>                  
> By which i presume you mean, the man(7) language rather than the              
>                  
> mdoc(7) language; more on this below.                                         
>                  
>                                                                               
>                  
> i certainly agree that, for people not regularly creating new man             
>                  
> pages from scratch, having to learn roff and a macro library                  
>                  
> probably feels like unnecessary work.

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.

> > While you can absolutely get a list of manpages containing a 
> > specific term of a specific type with apropos (like the example
> > you gave), what I was getting at is that you can't say to your
> > pager "jump to the flag -e". [...]
>
> Well, what i was trying (poorly!) to get at is that if you've got 
> semantic markup rather than presentational markup, one can use 
> that fact for the sort of functionality you describe: a program 
> could find the documentation for that flag by searching the source 
> for '.Op Fl e', which would be more reliable than having to make 
> guesses / use heuristics.

Agreed. I was mostly complaining such a thing hasn't been done yet
despite mdoc existing since the 90s (iirc). I'm afraid the approach
you describe likely wouldn't be sufficient, though, because there is
little correspondence between source line numbers and output line
numbers.

Such a thing would have to be somehow integrated with mandoc/troff
itself. The simplest solution I can think of is mdoc inserting the
ECMA-48 Privacy Message escape sequence[1], which allows the
insertion of hidden text into the output (all terminal emulators
ignore it, afaik), after each formatting element with terminal
output.

A program could then search the formatted output and report the
output line numbers containing the desired elements, which could
be jumped to with less's g command. A better (but more difficult)
solution would be to integrate this with the pager's search itself,
possibly by extending less's search facilities.

> Indeed, right now, there isn't much difference from the end-user's 
> perspective. But i feel that the use semantic markup would 
> significantly facilitate the development of functionality, 
> including in man page viewers, that end-users _would_ notice 
> (which i feel the 'apropos' example i provided gives something of 
> a taste of).

I would agree if there wasn't several decades of mdoc usage on the
BSD side without the development of such features.

> > I feel like ideally, though, the authors should write sentence 
> > case and the macros should take care of capitalization if it's 
> > desirable (with .stringup or similar)... Clearly mdoc's semantic
> > approach has its limits :)
>
> To me, one of the main points of separating semantics from 
> presentation - particularly as we've learned through the 
> experience of the Web - is to facilitate end-users having some 
> control over how the content is presented to them, because there 
> isn't always a single form of presentation that meets all the 
> needs of every person. Whilst there might be typographic rules 
> that are widely agreed upon, there are also things that are very 
> much subjective and user-specific, and as such, i strongly feel 
> that certain forms of presentation shouldn't be forced on the 
> user.

I agree wholeheartedly, which is exactly why I suggested that Sh
arguments are entered in sentence case and uppercased only if
that's desired.

> For example: i struggle with text on a black background, and thus 
> strongly prefer 'light' themes - including in my full-screen 
> terminal, which is black-on-white. Yes, even at night. :-P But 
> there are people for whom this is anathema, [...]

Like me. :)

> and who instead want black backgrounds - possibly with some
> low-contrast foreground colour, such as dark blue. But this
> combination is unreadable to me.

Dark blue on black background IS undreadable. The standard terminal
color combination is light gray on black. I myself use white on
black and low screen brightness.

> >> To try to demystify it for others, i wrote this quickstart 
> >> guide: 
> >> https://github.com/flexibeast/guides/blob/master/mdoc-quickstart.md
> >
> > Cool, that's a really nice tutorial! I will try to give some
> > constructive suggestions/criticism...
>
> Thank you! Most of these i'll take on board. :-) As a general 
> point - the guide is intended to be merely be an _introduction_ to 
> mdoc, to give people some sense of how it works; it's certainly 
> not intended to be a general text for writing man pages with 
> mdoc. But the document doesn't actually say this, so i'll add a 
> note to this effect.

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.

I guess my personal approach to introductions is closer to
"reference of the essentials that assumes little prior knowledge",
which is why I suggested the addition of tbl. So fair enough.

> > When you write an example exit status section, I would expect to 
> > hear about the Ex macro, which is often preferable to writing it
> by hand.
>
> The 'Ex' macro you're referring to here is man(7)-specific; the 
> 'Ex' macro in mdoc(7) is for exit status.

I was in fact referring to mdoc's Ex macro. To quote mdoc(7):
  Ex -std [utility ...]
       Insert a standard sentence regarding command exit values of 0 on
       success and >0 on failure.  This is most often used in section 1, 6,
       and 8 manual pages.

       If utility is not specified, the document's name set by Nm is used.
       Multiple utility arguments are treated as separate utilities.

       See also Rv.

> > And by the way, there is technically no such thing as exit 
> > status -1, it becomes 255.[3]
>
> 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.

> Thanks for the feedback!

Happy to help :)

~ onf

[1] ESC ^ text... ESC \
    See https://www.x.org/docs/xterm/ctlseqs.pdf, page 4, and
    the (freely available) ECMA-48 standard, 4th ed., page 54.