From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E7746C3DA6D for ; Mon, 12 Dec 2022 13:41:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232884AbiLLNlE (ORCPT ); Mon, 12 Dec 2022 08:41:04 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36516 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232880AbiLLNkg (ORCPT ); Mon, 12 Dec 2022 08:40:36 -0500 Received: from stravinsky.debian.org (stravinsky.debian.org [IPv6:2001:41b8:202:deb::311:108]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6C1B813F36 for ; Mon, 12 Dec 2022 05:39:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debian.org; s=smtpauto.stravinsky; h=X-Debian-User:In-Reply-To:Content-Type:MIME-Version: References:Message-ID:Subject:Cc:To:From:Date:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=Qzj49BaUQ02jcbBW1Uq2DbmX40CdS4QPTqEzH8o65V0=; b=e8ujUCMjlNTLkUYRM6ghKVTBSW JwQ6kPRWrs46nQb2SNZLVFVq0olRi1++/1Nf7TH4QfuseVqTEIemnh6Z4ydU0l4IazVtJLxDtnRS6 CLqlHPNibRVdtH1wqsqJCyr93d4lnCZkQkVyMT6KNDabet+BkE1RePHoDJckC3wF53ATTOmTtQWvy cxhips9iWeY4Cgp50p2R9dEGE4PotH3lLq4SdBf0w9HFOrdLj2/UYJdKBu01teCorhjKMscrKkPxz sq//67phLyHq9XP5N6wQDmjFDRi8gnNpIUov2tCHTkfZibankVoGpujb2uPO/lL+eNrHdCQtwgn3P e7YX8beQ==; Received: from authenticated user by stravinsky.debian.org with esmtpsa (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (Exim 4.94.2) (envelope-from ) id 1p4j28-000foJ-JU; Mon, 12 Dec 2022 13:39:52 +0000 Received: from ns1.rosewood.vpn.ucam.org ([172.20.153.2] helo=riva.ucam.org) by riva.rosewood.vpn.ucam.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1p4j26-0040FM-KA; Mon, 12 Dec 2022 13:39:50 +0000 Date: Mon, 12 Dec 2022 13:39:45 +0000 From: Colin Watson To: Alejandro Colomar Cc: Ingo Schwarze , "G. Branden Robinson" , linux-man , groff@gnu.org, Michael Haardt , Andries Brouwer , Michael Kerrisk , Douglas McIlroy , "Andries E. Brouwer" Subject: Re: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty) Message-ID: Mail-Followup-To: Alejandro Colomar , Ingo Schwarze , "G. Branden Robinson" , linux-man , groff@gnu.org, Michael Haardt , Andries Brouwer , Michael Kerrisk , Douglas McIlroy , "Andries E. Brouwer" References: <20220906191320.447t5awx3rcb5d5b@illithid> <20220906204245.hzhq2s7yha6zzgrh@illithid> <30e80fe0-f0ce-d6cd-ee40-28692e5a5f82@gmail.com> <5c1e8620-e4ff-c79a-1d4e-11f797276726@gmail.com> <20221116234049.GA1229865@if> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Debian-User: cjwatson Precedence: bulk List-ID: X-Mailing-List: linux-man@vger.kernel.org [Sorry for the delay; a succession of business travel, holidays, and Covid have together eaten up much of my time recently.] On Thu, Nov 17, 2022 at 01:28:12AM +0100, Alejandro Colomar wrote: > On 11/17/22 01:06, G. Branden Robinson wrote: > > I think the adoption of the term (sub)chapter has a potential benefit in > > that it removes a terminological collision with (sub)sections as > > subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss). > > > > If this terminological reform is adopted, I think it should be done > > across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4) > > man-db. If we can't speak with one voice on this then I think it's > > better not to undertake that reform at all, to avoid frustrating the > > discoverabilty of man pages. > > > > Possibly the biggest barrier to this is the mnemonic and documentation > > of the man(1) '-s' option. In man-db man, '-C' and '-c' are both > > already in use. > > That can be documented as a historical detail in the documentation of the > option itself, which makes sense, as to avoid programmers that have heard of > sections to try to grep section and find nothing. > > > Probably a good idea to loop Colin Watson in on this proposal of yours, > > which is strictly speaking severable from the below. > > Yes, especially since part of the discussion is in linux-man@ (I'm not sure > if he reads it; I think not) and not in groff@ (which he reads, AFAIK). So, > I'll merge the 2 discussions about this by forwarding the 2 most interesting > other emails below. I'm not subscribed to linux-man@, and while I am technically subscribed to groff@ I read it very infrequently these days, so thanks for explicitly copying me in. > So, does it make sense to all of us to start using the term chapter for > divisions of the man-pages single volume, so that the manual pages in Linux > are organized from now on in chapters 1 to 9 instead of sections 1 to 9? I find myself relatively agnostic on this whole discussion. There are good reasons for reform, and also some good reasons to wonder whether the grass will in fact be greener on the other side (given the necessity to keep many bits of "section" terminology around in things like man(1)'s option handling and the man-db configuration file more or less indefinitely). I'm not going to veto it, but I also have no great enthusiasm for the upheaval. If the community consensus is for it to happen, then I'd ask that somebody who is enthusiastic about it put the work into the various necessary updates to man-db's code and documentation and send an appropriate merge request. -- Colin Watson (he/him) [cjwatson@debian.org]