adding a sysctl man section

[John-Mark Gurney]

Lutz Donnerhacke wrote this message on Thu, Feb 11, 2021 at 08:54 +0100:
> On Wed, Feb 10, 2021 at 06:37:00PM -0700, Warner Losh wrote:
> > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney <jmg at funkthat.com> wrote:
> > > 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'd oppose, it will clutter the filesystem for a "man -k" (or similar)
> shortcut.

Can you expand exactly how/why this would happen?  I assume you mean
clutter the output from "man -k", but as "man -k" uses a db for it's
data, it'd only slightly expand that db, but it wouldn't clutter the
file system anymore, unless I'm missing something...

So, in one test case, this is what you'd see (or maybe section 9,
which I'm find with):
# man -k xhci
xhci, hw.usb.xhci.ctlquirk, hw.usb.xhci.ctlstep, hw.usb.xhci.debug, hw.usb.xhci.dma32, hw.usb.xhci.streams, hw.usb.xhci.use_polling, hw.usb.xhci.xhci_port_route(4, s) - USB eXtensible Host Controller driver

yes, if you do a search for a generic term like debug, you'll end up
a lot more extra output, BUT, "man -k debug" already outputs a wall
of text that you're likely to need to filter anyways, so I don't see
a major difference/problem here.

I will say I'm a bit surprised there isn't an option to apropos to allow
only displaying the first matching man page to shorten the lines a bit,
but we already have this problem for some man pages:
# find . -type f -ls | awk '{ print $1 }' | sort | uniq -c | sort | tail -n 5
  95 409059
  98 405230
 102 408573
 116 397987
 118 396855

409059 is nv(9)
405230 is snmpmod(3)
408573 is bhnd(9)
397987 is libusb(3)
396855 is curs_sp_funcs(3X)

for example.
# man -k libnv
nvlist_create, nvlist_clone, nvlist_destroy, nvlist_dump, nvlist_empty, nvlist_error, nvlist_exists, nvlist_fdump, nvlist_flags, nvlist_free, nvlist_next, nvlist_pack, nvlist_recv, nvlist_send, nvlist_set_error, nvlist_size, nvlist_unpack, nvlist_xfer, nvlist_add_binary, nvlist_add_bool, nvlist_add_bool_array, nvlist_add_descriptor, nvlist_add_descriptor_array, nvlist_add_null, nvlist_add_number, nvlist_add_number_array, nvlist_add_nvlist, nvlist_add_nvlist_array, nvlist_add_string, nvlist_add_string_array, nvlist_add_stringf, nvlist_add_stringv, nvlist_append_bool_array, nvlist_append_descriptor_array, nvlist_append_number_array, nvlist_append_nvlist_array, nvlist_append_string_array, nvlist_exists_binary, nvlist_exists_bool, nvlist_exists_bool_array, nvlist_exists_descriptor, nvlist_exists_descriptor_array, nvlist_exists_null, nvlist_exists_number, nvlist_exists_number_array, nvlist_exists_nvlist, nvlist_exists_nvlist_array, nvlist_exists_string, nvlist_exists_type, nvlist_free_binary, nvlist_free_bool, nvlist_free_bool_array, nvlist_free_descriptor, nvlist_free_descriptor_array, nvlist_free_null, nvlist_free_number, nvlist_free_number_array, nvlist_free_nvlist, nvlist_free_nvlist_array, nvlist_free_string, nvlist_free_string_array, nvlist_free_type, nvlist_get_binary, nvlist_get_bool, nvlist_get_bool_array, nvlist_get_descriptor, nvlist_get_descriptor_array, nvlist_get_number, nvlist_get_number_array, nvlist_get_nvlist, nvlist_get_nvlist_array, nvlist_get_parent, nvlist_get_string, nvlist_get_string_array, nvlist_move_binary, nvlist_move_descriptor, nvlist_move_descriptor_array, nvlist_move_nvlist, nvlist_move_nvlist_array, nvlist_move_string, nvlist_move_string_array, nvlist_take_binary, nvlist_take_bool, nvlist_take_bool_array, nvlist_take_descriptor, nvlist_take_descriptor_array, nvlist_take_number, nvlist_take_number_array, nvlist_take_nvlist, nvlist_take_nvlist_array, nvlist_take_string, nvlist_take_string_array, libnv, nv, nvlist, nvlist_in_array, nvlist_add, nvlist_append, nvlist_get, nvlist_move, nvlist_take(9) - library for name/value pairs

-- 
  John-Mark Gurney				Voice: +1 415 225 5579

     "All that I will do, has been done, All that I have, has not."