Re: ripgrep author seems happy with groff_man_style(7)

[Alexis]

"onf" <onf@disroot.org> writes:

> Speaking of which, I noticed just recently that all of groff's 
> manpages
> don't use all caps for subheadings (.SH)... which is about the 
> first
> time I've seen manpage subheadings that weren't in all caps.
In my mdoc(7) ports of documentation in the skaware ecosystem 
(e.g. s6-man-pages, https://git.sr.ht/~flexibeast/s6-man-pages), 
i've used sentence case with Ss, the mdoc(7) equivalent of SH. 

> 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 can imagine manpages would be much more usable if 
> cross-references
> and subheadings etc. weren't just a matter of formatting, but 
> actually
> meant something to the viewer.
This is one of the reasons i'm an advocate for people using 
mdoc(7) for man pages - as is done on the *BSDs - rather than 
man(7). Where man(7) is primarily presentational markup, mdoc(7) 
is primarily _semantic_ markup. This allows the use of the macros 
as search keys for apropos(1); the example i usually provide is:
 $ apropos Ev=PATH

to get a list of man pages which mention the PATH environment 
variable.
Although there are indeed more mdoc(7) macros to keep in mind 
compared to man(7), i find them easier to remember than the 
association-by-convention required for man(7) formatting 
macros. Ev, 'Environment variable', is one example; others include 
'Ss' ('Subsection header'), 'Xr' ('Cross-reference'), 'Fn' 
('Function name') and 'Fa' ('Function argument').
Porting the documentation for s6 was the first time i'd ever 
created man pages. Initially i assumed man pages _had_ to be 
written in man(7), and as someone who was long ago sold on the 
benefits of separating semantics from presentation, i found the 
idea of having to memorise associations between particular 
intended semantics and particular presentational markup to be 
.... discouraging. i don't know how i stumbled across mdoc(7), but 
once i did, and discovered that it could be used for man pages on 
Linux via groff, i focused on learning and using mdoc(7).
To try to demystify it for others, i wrote this quickstart guide: 
https://github.com/flexibeast/guides/blob/master/mdoc-quickstart.md

Alexis.