adding a sysctl man section

[Yuri Pankov]

Warner Losh wrote:
> On Sat, Feb 13, 2021 at 8:09 AM Yuri Pankov <yuripv at yuripv.dev> wrote:
> 
>> 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 ('#'?).
>>
> 
> Can you do one man page each way so we can (a) see the markup and (b) see
> what the other tools do?

No changes other than properly defining the variables in their
respective sections should be needed, see below, but I'd say those
should be done anyway.

> I rather like this idea. I like the idea of looking for the sysctl 'fred'
> and being able to know that this is a kern.cam.da.0.fred vs hw.mpr.fred vs
> dev.mpr.0.fred vs vfs.foofs.fred without crazy gymnastics for dealing with
> thousands of additions to the tree.
> 
> I tend to agree on symlinks, btw, but that implementation detail we should
> table until we work out if similar means can achieve similar or better
> results.

I have updated the review at https://reviews.freebsd.org/D28642
implementing the .Va idea which turned out to be much better and easier
than introducing new macro.  The requirements are that all tunables
should be in their respective sections, loader ones in "LOADER TUNABLES"
and sysctl ones in "SYSCTL VARIABLES" (names should be exact as already
found in a lot of man pages, diff fixes ixl.4 as an example).  Usage is
e.g. `man hw.usb.xhci.debug` or fixed `man hw.ixl.rx_itr`.

This does not yet implement the special handling for wildcards as those
differ between man pages (ones that I found are '%s' for string, '%d' or
'#' for numbers), but should be easy to do as well once agreed on format.

At the moment, this works for ~300 sysctl names out of ~14000 found on
my system.