Date: Wed, 10 Feb 2021 18:10:36 -0800 From: John-Mark Gurney <jmg@funkthat.com> To: Warner Losh <imp@bsdimp.com> Cc: "freebsd-arch@freebsd.org" <arch@freebsd.org> Subject: Re: adding a sysctl man section Message-ID: <20210211021036.GG31099@funkthat.com> In-Reply-To: <CANCZdfrD3aUS9YQQkA9yZxvUDvBdbfmMcuteqPp8yeDHoA_grQ@mail.gmail.com> References: <20210211001505.GF31099@funkthat.com> <CANCZdfrD3aUS9YQQkA9yZxvUDvBdbfmMcuteqPp8yeDHoA_grQ@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Warner Losh wrote this message on Wed, Feb 10, 2021 at 18:37 -0700: > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney <jmg@funkthat.com> 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 think adding the sysctl to the man page is great. > > However, I have a concern about the links: > > % sysctl -a | wc > 38632 78349 1423715 Since the links are stored in inodes (because they should be small), we're looking at maybe a 5MB of additional storage, assuming we manage to get all 38k unique links... We already have 11k man pages + links, of which only 4k are uniq.. root@test:/usr/share/man # find . -type f | wc 11306 11306 286610 root@test:/usr/share/man # find . -type f -ls | awk '{ print $1 }' | sort -u | wc -l 4014 Also, it is doubtful that we'd even come close to having 50% coverage of those nodes in the coming years... > This suggests a lot of links if this idea were to be fully populated > (though maybe not 30k) If we follow delphij's suggestion of doing only the most relevant parent node, this would reduce the count, but would require extra code to handle looking up the parent until one is found... Each root sysctl node would then also linkly need their own page so that when someone looks up a completely undocumented sysctl, the have a place to start... > Also, how do you document things like the dev hierarchy which has a unit > number tossed into the middle? > > dev.uhub.1.%parent: usbus1 > dev.uhub.1.%pnpinfo: > dev.uhub.1.%location: > dev.uhub.1.%driver: uhub > dev.uhub.1.%desc: 0x1022 XHCI root HUB, class 9/0, rev 3.00/1.00, addr 1 > dev.uhub.0.disable_port_power: 0 > dev.uhub.0.disable_enumeration: 0 > dev.uhub.0.%domain: 0 > dev.uhub.0.%parent: usbus0 > dev.uhub.0.%pnpinfo: > dev.uhub.0.%location: > dev.uhub.0.%driver: uhub > > Also, all the nodes have the %parent, %pnp, %location, %driver and %desc > nodes. Those are provided by newbus, while everything else is dependent on > the driver... Well, likely a user would hopefully just look at dev.uhub... Also, every dev should have a man page, and hopefully our users are smart enough to be able to type: man uhub, or what ever dev name follows dev, but that uhub.4 doesn't exist is part of the problem... if uhub(4) existed, it should list all the sub sysctl nodes that it adds, and to handle the newbus generic nodes, link to a man page that describs them.. I did a quick grep and couldn't find anywhere where %parent was documented in the FreeBSD man pages... So yet more documentation that needs to be written... (and this means that your 38k number is likely way large since it includes lots of these lines which will be served by a single entry)... -- John-Mark Gurney Voice: +1 415 225 5579 "All that I will do, has been done, All that I have, has not."
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20210211021036.GG31099>