From owner-freebsd-arch@freebsd.org  Thu Feb 11 07:55:26 2021
Return-Path: <owner-freebsd-arch@freebsd.org>
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 0C7F053DEE7
 for <freebsd-arch@mailman.nyi.freebsd.org>;
 Thu, 11 Feb 2021 07:55:26 +0000 (UTC)
 (envelope-from lutz@iks-jena.de)
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 4Dbpp55m8jz4sn4
 for <freebsd-arch@freebsd.org>; Thu, 11 Feb 2021 07:55:25 +0000 (UTC)
 (envelope-from lutz@iks-jena.de)
Received: by mailman.nyi.freebsd.org (Postfix)
 id C5AEB53DEE5; Thu, 11 Feb 2021 07:55:25 +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 C573753DEE4
 for <arch@mailman.nyi.freebsd.org>; Thu, 11 Feb 2021 07:55:25 +0000 (UTC)
 (envelope-from lutz@iks-jena.de)
Received: from annwfn.iks-jena.de (annwfn.iks-jena.de [IPv6:2001:4bd8::19])
 (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
 (Client did not present a certificate)
 by mx1.freebsd.org (Postfix) with ESMTPS id 4Dbpp53sMYz4sc8
 for <arch@freebsd.org>; Thu, 11 Feb 2021 07:55:25 +0000 (UTC)
 (envelope-from lutz@iks-jena.de)
X-SMTP-Sender: IPv6:2001:4bd8:0:666:248:54ff:fe12:ee3f
Received: from belenus.iks-jena.de (belenus.iks-jena.de
 [IPv6:2001:4bd8:0:666:248:54ff:fe12:ee3f])
 by annwfn.iks-jena.de (8.15.2/8.15.2) with ESMTPS id 11B7svIr007019
 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT);
 Thu, 11 Feb 2021 08:54:57 +0100
X-MSA-Host: belenus.iks-jena.de
Received: (from lutz@localhost)
 by belenus.iks-jena.de (8.14.3/8.14.1/Submit) id 11B7suwW007957;
 Thu, 11 Feb 2021 08:54:56 +0100
Date: Thu, 11 Feb 2021 08:54:56 +0100
From: Lutz Donnerhacke <lutz@donnerhacke.de>
To: Warner Losh <imp@bsdimp.com>
Cc: "freebsd-arch@freebsd.org" <arch@freebsd.org>
Subject: Re: adding a sysctl man section
Message-ID: <20210211075456.GA7928@belenus.iks-jena.de>
References: <20210211001505.GF31099@funkthat.com>
 <CANCZdfrD3aUS9YQQkA9yZxvUDvBdbfmMcuteqPp8yeDHoA_grQ@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CANCZdfrD3aUS9YQQkA9yZxvUDvBdbfmMcuteqPp8yeDHoA_grQ@mail.gmail.com>
X-message-flag: Please send plain text messages only. Thank you.
User-Agent: Mutt/1.5.17 (2007-11-01)
X-Rspamd-Queue-Id: 4Dbpp53sMYz4sc8
X-Spamd-Bar: ----
Authentication-Results: mx1.freebsd.org;
	none
X-Spamd-Result: default: False [-4.00 / 15.00];
	 REPLY(-4.00)[]
X-BeenThere: freebsd-arch@freebsd.org
X-Mailman-Version: 2.1.34
Precedence: list
List-Id: Discussion related to FreeBSD architecture <freebsd-arch.freebsd.org>
List-Unsubscribe: <https://lists.freebsd.org/mailman/options/freebsd-arch>,
 <mailto:freebsd-arch-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-arch/>
List-Post: <mailto:freebsd-arch@freebsd.org>
List-Help: <mailto:freebsd-arch-request@freebsd.org?subject=help>
List-Subscribe: <https://lists.freebsd.org/mailman/listinfo/freebsd-arch>,
 <mailto:freebsd-arch-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Thu, 11 Feb 2021 07:55:26 -0000

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@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.

> 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:

Device driver man pages (like ixl) tend to document a # instead of the
number. So this would be dev.uhub.#.%parent ... in the man page.