Date: Sat, 13 Feb 2021 11:59:04 +0300 From: Yuri Pankov <yuripv@yuripv.dev> To: arch@FreeBSD.org Subject: Re: adding a sysctl man section Message-ID: <ac9c8891-43f9-9279-0147-2dcb0260c0ed@yuripv.dev> In-Reply-To: <20210211001505.GF31099@funkthat.com> References: <20210211001505.GF31099@funkthat.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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: $ man -d hw.usb.xhci.debug -- Using architecture: amd64:amd64 -- Using pager: less -ins -- Using manual sections: 1:8:2:3:3lua:n:4:5:6:7:9:l -- Searching PATH for man directories -- Adding /usr/share/man to manpath -- Adding /usr/local/man to manpath -- Adding default manpath entries -- Adding /usr/share/openssl/man to manpath -- Parsing config file: /usr/local/etc/man.d/perl5.conf -- Adding /usr/local/lib/perl5/site_perl/man to manpath -- Adding /usr/local/lib/perl5/5.32/perl/man to manpath -- Using manual path: /usr/share/man:/usr/local/man:/usr/share/openssl/man:/usr/local/lib/perl5/site_perl/man:/usr/local/lib/perl5/5.32/perl/man -- Using locale paths: . -- Using standard page width -- Searching for hw.usb.xhci.debug -- Found a usable page, displaying that -- Command: /usr/bin/zcat /usr/share/man/man4/xhci.4.gz | mandoc | less -ins
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?ac9c8891-43f9-9279-0147-2dcb0260c0ed>