Re: adding a sysctl man section

On Sat, Feb 13, 2021 at 8:09 AM Yuri Pankov <[email protected]> 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?

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.

Warner
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-arch
To unsubscribe, send any mail to "[email protected]"