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>
index | next in thread | previous in thread | raw e-mail
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. Warnerhome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfrNOzEjqzC0WbNMcEo_44qmUZ7ievVbxB4Zj1a-2_JFGQ>