From owner-freebsd-arch@freebsd.org Sat Feb 13 16:54:45 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 3D8C3531D76 for ; Sat, 13 Feb 2021 16:54:45 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mailman.nyi.freebsd.org (mailman.nyi.freebsd.org [IPv6:2610:1c1:1:606c::50:13]) by mx1.freebsd.org (Postfix) with ESMTP id 4DdGgS6TMbz4k7W for ; Sat, 13 Feb 2021 16:54:44 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mailman.nyi.freebsd.org (Postfix) id DE40F532098; Sat, 13 Feb 2021 16:54:44 +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 DE0B0531E45 for ; Sat, 13 Feb 2021 16:54:44 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-qk1-x729.google.com (mail-qk1-x729.google.com [IPv6:2607:f8b0:4864:20::729]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DdGgS5nCpz4k9V for ; Sat, 13 Feb 2021 16:54:44 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mail-qk1-x729.google.com with SMTP id w19so2657738qki.13 for ; Sat, 13 Feb 2021 08:54:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdimp-com.20150623.gappssmtp.com; s=20150623; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=53N4uKE24NychRVMSyU2PAFt8pHEzbbfsG7wu8xmc6g=; b=JJr4V+9uMvJzZh+FW5NwdiGE7tAbVFFcFfXz5+6qPp71PkeMY8LuiTa0+mCHSJBYzN rXo5gIiE3hSTwxXvLx/spMjNji4ciIlX0t98vXfHEjUh9vBgixcG33kueFo0sZhgdU30 qGF3wBAMHMNFpL7GDEOs+9595IfyTngOhk4iCSZCD5GVjdeOslH2Tt8w4MPkaYleyefk zff0ykJK3/bTApt1J+bBpQ5DVYos4kkM1NPfxXrTXTReA8IXOgrM4n229FJk6HF32Foh DJ0uqlbt9XMqBHPbZZfV11xRwbYVmCdX1EinXRSjg9d3EOxMtGb80K5ho1aepof8iJm+ K1Ow== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=53N4uKE24NychRVMSyU2PAFt8pHEzbbfsG7wu8xmc6g=; b=a+hBCkEneW9a9iu+p0sxMpgnZFgi/6FixsZni8dFkUM31Yt3KnMp4q9WXNpEUTvnis CgaZHmbQSnDWRQwVcqFAbgFqecUd8MGnkH8Saq0cJmkbj2PugLb8WaMJKAvhtURfjL+S X8zZ4qDlPXYqM3phRzE6e67nVRjNjZmoLR3l6U+Hm+wsQKmQyB/ScQP9H3YUAH7fBkiB uoImLw2S5WiwKSXuTQCJ4kFgf3TSgM4l27BhDOAGMmLoskaUcMikkNN9krfuKKawIsaX YVRZr7WyPEZieJ7w42D0yNEl8TUFvEaSnLqIvSca8//i7RZ5VHY+mpKDCioOYzGQ3Kxn NJcQ== X-Gm-Message-State: AOAM533j4lEdhXDDjwupFtmPPKdZnKd+Y56c7G8ZnsM0RICQQwrdJAI9 SWXYNhzWBrvuLzpBGUQ19SO3rr6BxFWz88RynG0igc61m4boBQ== X-Google-Smtp-Source: ABdhPJz21n4tVU3wYKLbvUA0AEO4njfzuT4iF8pjwRbwwfveJILSUihrR4S2gcJBukW6x4c8O6O+D9NyVGE0I8lGdU0= X-Received: by 2002:a05:620a:12d1:: with SMTP id e17mr7712427qkl.89.1613235283569; Sat, 13 Feb 2021 08:54:43 -0800 (PST) MIME-Version: 1.0 References: <20210211001505.GF31099@funkthat.com> In-Reply-To: From: Warner Losh Date: Sat, 13 Feb 2021 09:54:32 -0700 Message-ID: Subject: Re: adding a sysctl man section To: Yuri Pankov Cc: "freebsd-arch@freebsd.org" X-Rspamd-Queue-Id: 4DdGgS5nCpz4k9V X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; none X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[] Content-Type: text/plain; charset="UTF-8" X-Content-Filtered-By: Mailman/MimeDel 2.1.34 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 16:54:45 -0000 On Sat, Feb 13, 2021 at 8:09 AM Yuri Pankov 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 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. Warner