adding a sysctl man section

[Yuri Pankov]

Yuri Pankov wrote:
> John-Mark Gurney wrote:
>> Inspired by: https://twitter.com/michaeldexter/status/1359614809365311490
>>
>> I realized that we could/should create a new sysctl section.  My initial
>> thought was section s, but I'd be open for other recommendations.
>>
>> Then, any page that describes a sysctl, would add an MLINK to it:
>> MLINK+= xhci.4 hw.usb.xhci.debug.s
>>
>> This section would be added to the default search, and then users
>> would simply be able to type: man <sysctl> and get directed to the
>> page that has information about it.
>>
>> Any objections?
> 
> I like the idea of documenting the sysctls, not the implementation idea
> though -- MLINKS are clutter, and we already have the tooling to drop
> them entirely, in base at least (that's something for another time
> though), as all the metadata we need is in man pages and stored in
> makewhatis (mandocdb) database.
> 
> I have put up simple PoC introducing new mdoc macro (.Sl, could be .Ctl
> or anything else not taken, doesn't matter much) specifically for
> sysctls, and implementing Sl keyword search as last resort in man(1).
> The idea is that .Sl would have the special meaning only when found in
> SYNOPSIS section (not implemented yet, trivial), and could (should) be
> extended to provide type, r/o flag, alias flag for when we want sysctl
> to be searchable, but not displayed (e.g. for ioscheduler items Warner
> mentioned), and anything else I missed.
> 
> The downside here is the addition of new macro, I guess we would have to
> somehow standardize it so that reading FreeBSD man pages on other
> systems would render at least something sensible; I don't think it's
> that big problem though.
> 
> Code is here: https://reviews.freebsd.org/D28642, there isn't lot to
> comment on yet, but it's already somewhat working with the xhci.4 man
> page modified to include .Sl:
[...]

Or, if adding new macro is really undesirable, we could do with what we
already have and have special meaning for .Va/.Vt in "SYSCTL VARIABLES"
section depending on that section being consistent throughout the tree.
 The idea stays the same though -- don't use MLINKS, rather embed
metadata in man pages and let existing man tools do the rest.

One thing I missed are the variables with unit numbers, these should be
trivial as well once we agree on wildcard symbols to use ('#'?).