From nobody Thu Oct 27 15:18:57 2022 X-Original-To: freebsd-doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Myq8M0ZQ6z4gHc0 for ; Thu, 27 Oct 2022 15:18:59 +0000 (UTC) (envelope-from mhorne@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (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-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Myq8M03bsz3g1f; Thu, 27 Oct 2022 15:18:59 +0000 (UTC) (envelope-from mhorne@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1666883939; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=lZ72fcpfFYP2M9NdGpfPP+Bdd0cfLRKMHVzQlu455VI=; b=rDRvjdKYiX1SUQqivUaa8HN6kt3CBoXU2qxwldKOHrtngdFHqUl4ylkbfIHz1AR/KgDifk TFlkJLPK/+EM2qRFA+ghj4yu9h7vJiC9eVi/Ob4dfYH+AHWwdChB3nih2aJEfbTfkOHn1j bJ54qfXjFfGfW6Y3IqleIS0LOfvl25L0NJE4bEkjr7gMIr4MPhXFKLEP1WZbrMBFqOpJTp NxxPEVDdAAN8PifAgzYio+aopJCvHmHCvxa0+gpDmn6YIU+72sB8GcngTbIFxnUG9PNSrd nJ0oTiA89ObJVcbN/u1BdziEoQsC6gVLTG2+7v2EqHyVFYZ6b4T7Dgg6gKC/CQ== Received: from [192.168.1.151] (host-173-212-76-127.public.eastlink.ca [173.212.76.127]) (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 did not present a certificate) (Authenticated sender: mhorne) by smtp.freebsd.org (Postfix) with ESMTPSA id 4Myq8L4v6dzrvP; Thu, 27 Oct 2022 15:18:58 +0000 (UTC) (envelope-from mhorne@freebsd.org) Message-ID: Date: Thu, 27 Oct 2022 12:18:57 -0300 List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:102.0) Gecko/20100101 Thunderbird/102.4.0 Subject: Re: Documentation of /usr/src directory layout To: Pau Amma Cc: "freebsd-doc@FreeBSD.org" References: Content-Language: en-CA From: Mitchell Horne In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1666883939; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=lZ72fcpfFYP2M9NdGpfPP+Bdd0cfLRKMHVzQlu455VI=; b=qnKFp9ySgRNDEMgJHMEcaHjMencPyrqR8NUoRwEMvrhflB+aNLySag0LqTUjqLiEOeKZi5 FPbkqrR3sLSogSXkvcezutmz4x/ruBLmsdUKUGuUFyVu4QJAJuT2AbsnNOn8a3LZqnK89o lQTuYjLd4RMZ0g/bkcua0aw91nMJ9KjC1XsgRMTzXucwVoLFonJ4UycOS+14nmLUsKtWCb sep0f6Ym3+GYlFeVW8SF04fH4x+54/xHFPp9/mERLjejIp14xLlEv9LLmcvL7jG+GDIVKN LDG/Qeu/Vis9Wl7tN/OWJyWiYikI0fpivggU2PFi5S8+Yry/pmTex9fDYkppYQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1666883939; a=rsa-sha256; cv=none; b=uubMd6XBoFtEgq5Egk0ezBtHsM2ndKrIAKHadK62b9R1BeXh5FCRVwiF2UmV2ngZfyrZvd 5Rw0Y70XK+muLmXBKBonyCxpChgzSwxjitshfaV0IwzCDW8LwUPokfHmeJrz+MtJ9juy7D gY6GwbIompGxsguVazmDFp1wz4xKUIGkQv/afeIK4ixGoDIjynVFM0bGJMiRWNslaJKcG4 3wZ0uU2XrxDrCGQdR2kJzGM0EK7iyAOKHHrry/8PR2HlpbNC6SGRD1SXZQDufRZJWcXQY4 4eY60bZ+Ww+Cz1xlVk1Xp6cu/5en0Wts7L8umFjy9qEgTL86MPLFtGzM1PztLw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N On 10/26/22 23:26, Pau Amma wrote: > On 2022-10-26 16:07, Mitchell Horne wrote: >> Hello, >> >> Currently, hier(7) contains detailed but outdated [1] documentation of >> the directory structure under /usr/src. The src tree's README.md file >> duplicates much of this information by maintaining a distinctly >> incomplete table. > > Noting that (on 13.1 at least) README.md is a lightly markdownized > version of README. If they're not going to be kept consistent going > forward, one should be removed. (As mentioned elsethread, keeping > README.md makes sense given GitHub and others display it by default.) > Great note, I would not have noticed this. I'll make sure that this gets cleaned up. > Re removing that info from hier(7) instead of updating it, a possible > disadvantage I see to that is people without source losing access to it. > I'm not familiar with the audience: how likely is it that people without > source installed will have a need for (a more current version of) that > part of it? > This is the only "regression" I can think of with the new scheme. I can rationalize it by saying that nobody without a copy of the source tree should ever *need* to know about its layout/structure. If one *wants* to learn this information, it is reasonable that they must obtain a copy or browse it online. I cannot conceive of a meaningful use for having the directory map alone.