Date: Sat, 13 Feb 2021 09:54:32 -0700 From: Warner Losh <imp@bsdimp.com> To: Yuri Pankov <yuripv@yuripv.dev> Cc: "freebsd-arch@freebsd.org" <arch@freebsd.org> Subject: Re: adding a sysctl man section Message-ID: <CANCZdfrNOzEjqzC0WbNMcEo_44qmUZ7ievVbxB4Zj1a-2_JFGQ@mail.gmail.com> In-Reply-To: <fe230f0b-1482-bcaa-3fc3-4f7e541471b1@yuripv.dev> References: <20210211001505.GF31099@funkthat.com> <ac9c8891-43f9-9279-0147-2dcb0260c0ed@yuripv.dev> <fe230f0b-1482-bcaa-3fc3-4f7e541471b1@yuripv.dev>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, Feb 13, 2021 at 8:09 AM Yuri Pankov <yuripv@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? 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfrNOzEjqzC0WbNMcEo_44qmUZ7ievVbxB4Zj1a-2_JFGQ>