From owner-freebsd-arch@freebsd.org Sat Feb 13 15:09:05 2021 Return-Path: Delivered-To: freebsd-arch@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 16E1652FBB0 for ; Sat, 13 Feb 2021 15:09:05 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4DdDKX5ymXz4dSM for ; Sat, 13 Feb 2021 15:09:04 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: by mailman.nyi.freebsd.org (Postfix) id CCBD752F83C; Sat, 13 Feb 2021 15:09:04 +0000 (UTC) Delivered-To: arch@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id CC86952F7E9 for ; Sat, 13 Feb 2021 15:09:04 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from wnew3-smtp.messagingengine.com (wnew3-smtp.messagingengine.com [64.147.123.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4DdDKW6zSpz4dVM for ; Sat, 13 Feb 2021 15:09:03 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailnew.west.internal (Postfix) with ESMTP id E0AC5C9A for ; Sat, 13 Feb 2021 10:09:01 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Sat, 13 Feb 2021 10:09:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yuripv.dev; h= subject:from:to:references:message-id:date:mime-version :in-reply-to:content-type:content-transfer-encoding; s=fm1; bh=I JcRZ/CWHxSLYKn2outR8KQ0w6urUhQjzJ0Mj1Vduic=; b=HxlcyL3nPLl7GKYhQ 8EdXdLe8jUwrlZgB0uRBsY1yVzBgUYUvqBbUSenGqP6O1+O+pY/qhhaxodOP7Z0f fmE8mjQY7AiQ26slsuSlk2vSvsI0zlQGjWaFxb/D4KrZBZOa/qqHIMycQF3I/SSj y+0VZ1IaZv8FBQwrtQCiE3tW/Xf4TDIU1pdGvx5eYADQf2F2VnwHUKTqMum3BFeo 9J4z6Vlcf4tMhoTxZWvSLYJGHFLMGVj/S1F2qal2x5NZLUOjrfOTBOK5DlyI3YZL z6zh1cPmcOzFWhSB0zU71/78eByL/iOOy3JlVYhpb7zLD8eWQ3A2fH1eORrhQoyH z8eYg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm2; bh=IJcRZ/CWHxSLYKn2outR8KQ0w6urUhQjzJ0Mj1Vdu ic=; b=lWcLOvRkty+OagsCPqQ34xGzR7p8D8T3USsIa8OeFFMzyaAyqD/5xvrwC BIFTyNWMcEeCCIivbbAipGzLZAIf6cTD3wicavJHQhsmhzqEPFTEOYM1hVLYFG7l 8SHskEaJxswinvtNg0MFNHSljs65Tt/gnKl66C77xLp0uU63snqdMUB0elCRTCqj Y+2qAm7al7RKo+IWsGf5LtvZPwAWGiYIqRxuRlZ2clqKIUVVybK7jU/t1pIsATpq o3JoP6A3SQVTYXguNcJVxsa2rotZgj5g1wHB9ZV2MpZ/jIkf//nUufYoYKdI8Qog Yw13ts22cGWxsBng6wtL5fGS659uA== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrieefgdeikecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecunecujfgurhepuffhvfhfkffffgggjggtgfesthejre dttdefjeenucfhrhhomhepjghurhhiucfrrghnkhhovhcuoeihuhhrihhpvheshihurhhi phhvrdguvghvqeenucggtffrrghtthgvrhhnpeejkedtiedtteekueelueegteeiteduge fhjefhudejteefvdfgtefhlefgtdfhteenucffohhmrghinhepthifihhtthgvrhdrtgho mhdpfhhrvggvsghsugdrohhrghdpfhhorhdrvhgrnecukfhppeeluddrvdegtddruddvge drudefjeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhm peihuhhrihhpvheshihurhhiphhvrdguvghv X-ME-Proxy: Received: from [192.168.1.6] (unknown [91.240.124.137]) by mail.messagingengine.com (Postfix) with ESMTPA id 90CB11080059 for ; Sat, 13 Feb 2021 10:09:00 -0500 (EST) Subject: Re: adding a sysctl man section From: Yuri Pankov To: arch@FreeBSD.org References: <20210211001505.GF31099@funkthat.com> Message-ID: Date: Sat, 13 Feb 2021 18:08:58 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.7.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4DdDKW6zSpz4dVM X-Spamd-Bar: +++++++++ Authentication-Results: mx1.freebsd.org; dkim=pass header.d=yuripv.dev header.s=fm1 header.b=HxlcyL3n; dkim=pass header.d=messagingengine.com header.s=fm2 header.b=lWcLOvRk; dmarc=none; spf=pass (mx1.freebsd.org: domain of yuripv@yuripv.dev designates 64.147.123.17 as permitted sender) smtp.mailfrom=yuripv@yuripv.dev X-Spamd-Result: default: False [9.90 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; R_SPF_ALLOW(0.00)[+ip4:64.147.123.17]; TO_DN_NONE(0.00)[]; RCVD_COUNT_THREE(0.00)[4]; DKIM_TRACE(0.00)[yuripv.dev:+,messagingengine.com:+]; NEURAL_HAM_SHORT(-1.00)[-1.000]; FROM_EQ_ENVFROM(0.00)[]; RCVD_TLS_LAST(0.00)[]; RBL_DBL_DONT_QUERY_IPS(0.00)[64.147.123.17:from]; ASN(0.00)[asn:11403, ipnet:64.147.123.0/24, country:US]; MIME_TRACE(0.00)[0:+]; MID_RHS_MATCH_FROM(0.00)[]; RCVD_IN_DNSWL_LOW(-0.10)[64.147.123.17:from]; ARC_NA(0.00)[]; RECEIVED_SPAMHAUS_XBL(5.00)[91.240.124.137:received]; RECEIVED_SPAMHAUS_CSS(4.00)[91.240.124.137:received]; FREEFALL_USER(0.00)[yuripv]; FROM_HAS_DN(0.00)[]; R_DKIM_ALLOW(0.00)[yuripv.dev:s=fm1,messagingengine.com:s=fm2]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[arch@freebsd.org]; DMARC_NA(0.00)[yuripv.dev]; NEURAL_SPAM_MEDIUM(1.00)[1.000]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[64.147.123.17:from:127.0.2.255]; BAD_REP_POLICIES(0.10)[]; NEURAL_SPAM_LONG(1.00)[1.000]; GREYLIST(0.00)[pass,meta]; MAILMAN_DEST(0.00)[arch] X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 13 Feb 2021 15:09:05 -0000 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 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 ('#'?).