Without wishing to bloat the manual page: LinuxKPI is an important aspect of many modern installations of FreeBSD. In the current edition of the page, the absence of compat is remarkable: … sys/ kernel source code amd64/ AMD64 architecture support arm/ ARM architecture support arm64/ ARMv8 architecture support cam/ cam(4) and ctl(4) cddl/ CDDL-licensed optional sources, including ZFS and DTrace ddb/ ddb(4) …
% pwd /usr/src/sys/cddl % bfs . -name "*fs*" -print ./boot/zfs ./boot/zfs/zfsimpl.h ./boot/zfs/skein_zfs.c ./boot/zfs/zfssubr.c ./compat/opensolaris/sys/cpuvar_defs.h ./compat/opensolaris/sys/vfs.h ./compat/opensolaris/sys/objfs.h ./compat/opensolaris/sys/refstr.h ./contrib/opensolaris/uts/common/sys/isa_defs.h ./contrib/opensolaris/uts/common/sys/sysevent/eventdefs.h % Whilst it's true that /usr/src/sys/cddl includes "CDDL-licensed optional sources, including ZFS and DTrace", this does not help the reader to contextualise OpenZFS in more modern FreeBSD. % pwd /usr/src/sys % bfs . -name "openzfs" -print ./contrib/openzfs % uclcmd get --file /boot/loader.conf zfs_load "YES" % uclcmd get --file /boot/loader.conf opensolaris_load null % (That's null in my case, in a more normal case opensolaris_load would be NO.)
<https://github.com/freebsd/freebsd-src/commits/main/share/man/man7/hier.7> <https://www.freebsd.org/cgi/man.cgi?query=hier&sektion=7&manpath=FreeBSD+14.0-current> for 14.0-CURRENT ☑ no longer includes sparc64/ ---- wulf@ <https://www.freebsd.org/cgi/man.cgi?query=hier&sektion=7&manpath=FreeBSD> more specifically <https://www.freebsd.org/cgi/man.cgi?query=hier&sektion=7&manpath=FreeBSD+13.0-RELEASE> includes sparc64/ Is this inconsistent with <https://www.freebsd.org/releases/13.0R/relnotes/#_sparc> > Removed support for the sparc64 architecture (SPARC 9). 58aa35d42975 – and if so, what change is required? TIA
(In reply to Graham Perrin from comment #2) > wulf@ Sorry! That should have been wosch@ for Wolfram Schneider. (I can not remove the previously added address.)
(In reply to Graham Perrin from comment #3) someone needs to merge a commit into stable/13 commit ca1e55df2451234feb9b2427d3ba60387db6626d Author: Warner Losh <imp@FreeBSD.org> Date: Wed Jan 5 14:38:05 2022 -0700 hier: Remove mips and sparc64 These have been removed from the kernel, so should be removed here. Sponsored by: Netflix
(In reply to Wolfram Schneider from comment #4) Partially MFC, mips is still supported in 13: https://www.freebsd.org/platforms/
/usr/home – not in the hierarchy. Is this an intentional omission?
(In reply to Graham Perrin from comment #0) In my opinion, maintaining a complete list of the directories under /usr/src in hier(7) is unproductive. It will always tend to be out of date or incomplete in some way, for little gain. The source of truth for this layout information is /usr/src/README.md; I think we should point readers there instead. I note that the information is duplicated again in the Developer's Handbook [1], and is differently outdated (stand/ is missing, at least). This further illustrates the problem. If folks find my take agreeable, I have the bandwidth and interest to take on the task of removing this information from hier(7) and augmenting README.md as necessary. [1] https://docs.freebsd.org/en/books/developers-handbook/introduction/#introduction-layout
(In reply to Mitchell Horne from comment #7) Glancing at these three pages: 1. <https://www.freebsd.org/cgi/man.cgi?query=hier&sektion=7&manpath=FreeBSD> 2. <https://www.carlavilla.es/hier.7> (preview) 3. <https://codeberg.org/FreeBSD/freebsd-src/src/branch/main/README.md#user-content-source-roadmap> … yes, I do like the idea of linking out to a source code-oriented page for /src * plus parallel or subsequent updates to development(7) <https://www.freebsd.org/cgi/man.cgi?query=development&sektion=7&manpath=FreeBSD> and to anything else that might refer to hier(7) for the required content. That said: I'm not a developer. I rarely refer to the source roadmap (it took me years to realise its relevance). Some people might, justifiably, want to retain a handy plain text representation, as is currently seen with man 7 hier … ---- In any case: thanks for offering for at least part of this type of work :-) Generally, a big +1 to things such as consolidation and deduplication.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=f0e4e021103c13ff3da4cdf1f9395754d069cbfb commit f0e4e021103c13ff3da4cdf1f9395754d069cbfb Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2022-11-01 15:15:18 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2022-11-01 15:20:55 +0000 hier(7): remove text describing /usr/src layout It poses a maintenance burden, since much of the information is duplicated in the src tree's README.md file. Readers who are interested enough in learning about the structure of the src tree can download it, or browse the README online. Have hier(7) just point them there instead. PR: 261349 Discussed with: freebsd-arch@, freebsd-doc@ lists Reviewed by: imp, emaste MFC after: 1 month Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D37135 README.md | 1 + share/man/man7/hier.7 | 127 ++------------------------------------------------ 2 files changed, 6 insertions(+), 122 deletions(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=552e24e4549a8fc272149e02bcd8210b64e2e967 commit 552e24e4549a8fc272149e02bcd8210b64e2e967 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2022-11-01 15:15:18 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2022-12-05 16:37:07 +0000 hier(7): remove text describing /usr/src layout It poses a maintenance burden, since much of the information is duplicated in the src tree's README.md file. Readers who are interested enough in learning about the structure of the src tree can download it, or browse the README online. Have hier(7) just point them there instead. PR: 261349 Discussed with: freebsd-arch@, freebsd-doc@ lists Reviewed by: imp, emaste MFC after: 1 month Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D37135 (cherry picked from commit f0e4e021103c13ff3da4cdf1f9395754d069cbfb) README.md | 1 + share/man/man7/hier.7 | 129 ++------------------------------------------------ 2 files changed, 5 insertions(+), 125 deletions(-)
A commit in branch stable/12 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=1be2773e631a5623eff634b855d2aac5786a63ad commit 1be2773e631a5623eff634b855d2aac5786a63ad Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2022-11-01 15:15:18 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2022-12-05 16:53:00 +0000 hier(7): remove text describing /usr/src layout It poses a maintenance burden, since much of the information is duplicated in the src tree's README.md file. Readers who are interested enough in learning about the structure of the src tree can download it, or browse the README online. Have hier(7) just point them there instead. PR: 261349 Discussed with: freebsd-arch@, freebsd-doc@ lists Reviewed by: imp, emaste MFC after: 1 month Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D37135 (cherry picked from commit f0e4e021103c13ff3da4cdf1f9395754d069cbfb) README.md | 1 + share/man/man7/hier.7 | 130 ++------------------------------------------------ 2 files changed, 6 insertions(+), 125 deletions(-)
% ls -hln /usr/share/doc total 1 drwxr-xr-x 2 0 0 6B 29 Jan 01:03 atf drwxr-xr-x 2 0 0 3B 29 Jan 01:03 IPv6 drwxr-xr-x 2 0 0 5B 29 Jan 01:06 kyua drwxr-xr-x 2 0 0 9B 29 Jan 01:03 legal drwxr-xr-x 3 0 0 5B 29 Jan 01:03 llvm drwxr-xr-x 2 0 0 4B 29 Jan 01:01 ncurses drwxr-xr-x 7 0 0 73B 29 Jan 01:06 ntp drwxr-xr-x 2 0 0 3B 29 Jan 01:03 pjdfstest % uname -KU 1400078 1400078 % That's quite different from the manual page description of what's in /usr/share/doc
<https://cgit.freebsd.org/src/commit/?id=c3b611e153e0480a354559f82fe5dc4c455bad4e> > hier(7): drop list of /usr/include subdirectories <https://cgit.freebsd.org/src/commit/?id=1bc55f58393ffd9714ebfd1ad4e9555cff76e8f6> > hier(7): drop list of /usr/share/doc subdirectories <https://cgit.freebsd.org/src/commit/?id=36db6b04962a01ff7b21592def02d4c570dac939> > hier(7): document /home/ and /usr/home/ – all MFC after one week. Thanks mhorne@
<https://cgit.freebsd.org/src/commit/?id=9a6a948128c9e2e39ea728e5f60b8bb82c9c1fca> > hier.7: update /home
After <https://github.com/freebsd/freebsd-src/pull/756> is merged or committed: * I'll update <https://reviews.freebsd.org/P572>, which I created to ease reading of the manual page (raw, in a suitably wide screen) * 'floppy disks' can go * 'zpool' can become 'pool' (compare with bug 257405) * deal with the ??? * be more specific for vi.recover/ * refer to vi(1) instead of ex(1) * update the description for /usr/share/misc/ – termcap.db is not ASCII text * review the description for /usr/share/sysroot/ (non-existent, here) * add links for referenced pages * reduce verbosity * …
<https://reviews.freebsd.org/paste/raw/572/> updated. PR 763 draft begun in GitHub.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=6469f9c595c609dd552ec198a16c471c87df7c57 commit 6469f9c595c609dd552ec198a16c471c87df7c57 Author: Graham Perrin <grahamperrin@FreeBSD.org> AuthorDate: 2023-06-10 08:41:35 +0000 Commit: Graham Perrin <grahamperrin@FreeBSD.org> CommitDate: 2023-06-10 08:41:35 +0000 hier(7): improvement, modernisation Consistent use of lowercase, spacing between sections, etc. Cease mentioning floppy disks. De-list /usr/share/misc/fonts/, which has been ??? (without a description) for twenty-seven years. Change zpool to pool. (zpool is a command.) Uppercase PPP for Point-to-Point Protocol. A few other changes to wording, including avoidance of the phrase pre-fab. Update the descriptions of: * /tmp/ * /usr/share/misc/ * /var/preserve/ * /var/tmp/ * /var/tmp/vi.recover/. Refer to vi(1) instead of ex(1). https://bugs.freebsd.org/261349 PR: 261349 Reviewed by: mhorne Approved by: mhorne Pull request: https://github.com/freebsd/freebsd-src/pull/763 share/man/man7/hier.7 | 301 ++++++++++++++++++++++---------------------------- 1 file changed, 135 insertions(+), 166 deletions(-)
(In reply to commit-hook from comment #17) For convenience <https://reviews.freebsd.org/P575> | <https://reviews.freebsd.org/paste/raw/575/> is copied from a wide terminal view of man -P more /usr/src/share/man/man7/hier.7 – with the first and last lines narrowed. No hard wrapping.
(In reply to Graham Perrin from comment #0) /usr/compat/ was documented in 2001 <https://cgit.freebsd.org/src/commit/?id=cf348169cb9a7f17eabe0a74e7aba6a5a80c5827>. I checked a few installations of the OS (two examples below), can not find this directory. Can anyone confirm that /usr/compat/ is no longer a part of the system? If so, is the commit identifiable? If it helps: 2015 bug 199942 involved manual creation of the directory. ---- root@fuji:~ # file /compat /compat: cannot open `/compat' (No such file or directory) root@fuji:~ # file /usr/compat /usr/compat: cannot open `/usr/compat' (No such file or directory) root@fuji:~ # file /sys/compat /sys/compat: directory root@fuji:~ # ls -hl /sys/compat total 54 drwxr-xr-x 2 grahamperrin wheel 16B May 27 20:21 cloudabi drwxr-xr-x 2 grahamperrin wheel 15B May 27 20:21 cloudabi32 drwxr-xr-x 2 grahamperrin wheel 15B May 27 20:21 cloudabi64 drwxr-xr-x 2 grahamperrin wheel 19B May 27 20:21 freebsd32 drwxr-xr-x 2 grahamperrin wheel 6B May 27 20:21 ia32 drwxr-xr-x 2 grahamperrin wheel 3B May 27 20:21 lindebugfs drwxr-xr-x 2 grahamperrin wheel 3B May 27 20:21 linprocfs drwxr-xr-x 2 grahamperrin wheel 3B May 27 20:21 linsysfs drwxr-xr-x 2 grahamperrin wheel 64B May 27 20:21 linux drwxr-xr-x 4 grahamperrin wheel 4B May 27 20:21 linuxkpi drwxr-xr-x 2 grahamperrin wheel 18B May 27 20:21 ndis drwxr-xr-x 2 grahamperrin wheel 4B May 27 20:21 x86bios root@fuji:~ # uname -aKU FreeBSD fuji 13.2-RELEASE FreeBSD 13.2-RELEASE releng/13.2-n254617-525ecfdad597 GENERIC amd64 1302001 1302001 root@fuji:~ # ---- % file /compat /compat: directory % ls -hl /compat total 1 drwxr-xr-x 10 root wheel 15B 31 Dec 12:16 linux drwxr-xr-x 21 root wheel 21B 4 Jul 2021 ubuntu % file /usr/compat /usr/compat: cannot open `/usr/compat' (No such file or directory) % file /sys/compat /sys/compat: directory % ls -hl /sys/compat total 1 drwxr-xr-x 2 grahamperrin wheel 19B 10 Jun 08:55 freebsd32 drwxr-xr-x 2 grahamperrin wheel 6B 30 May 20:07 ia32 drwxr-xr-x 2 grahamperrin wheel 3B 13 May 18:21 lindebugfs drwxr-xr-x 2 grahamperrin wheel 3B 30 May 20:07 linprocfs drwxr-xr-x 2 grahamperrin wheel 5B 13 May 18:21 linsysfs drwxr-xr-x 2 grahamperrin wheel 64B 30 May 20:07 linux drwxr-xr-x 4 grahamperrin wheel 4B 13 May 05:26 linuxkpi drwxr-xr-x 2 grahamperrin wheel 4B 13 May 05:26 x86bios % uname -aKU FreeBSD mowa219-gjp4-8570p-freebsd 14.0-CURRENT FreeBSD 14.0-CURRENT #5 main-n263447-267411d164d4-dirty: Thu Jun 8 14:26:44 BST 2023 grahamperrin@mowa219-gjp4-8570p-freebsd:/usr/obj/usr/src/amd64.amd64/sys/GENERIC amd64 1400090 1400090 %
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=5ca7f02946940ff698741d4da4a30b554cb0f592 commit 5ca7f02946940ff698741d4da4a30b554cb0f592 Author: Graham Perrin <grahamperrin@FreeBSD.org> AuthorDate: 2023-06-10 13:08:35 +0000 Commit: Graham Perrin <grahamperrin@FreeBSD.org> CommitDate: 2023-06-10 13:08:35 +0000 hier(7): typo (critial) https://bugs.freebsd.org/261349 PR: 261349 Reported by: Mike Karels <mike@karels.net> Fixes: 6469f9c595c6 hier(7): improvement, modernisation share/man/man7/hier.7 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
(In reply to Graham Perrin from comment #19) It is not part of the BSD.usr.dist mtree file, so installation will not create this directory. I think its description can be removed. It is not documented by linux(4) either, unlike /compat/ sub-directories.
A couple of additional comments relative to the latest version: /media contains no subdirectories by default. It is probably also worth mentioning that /tmp may be re-created (empty) at boot time, e.g. tmpfs. This is independent of clear_tmp_enable. /usr/freebsd-dist is not installed; it is present on the ISO though.
Created attachment 242723 [details] 2023-06-10 20:09 email (In reply to commit-hook from comment #17) <https://lists.freebsd.org/archives/dev-commits-src-main/2023-June/016217.html> was cc'd to three lists, including src-committers. My response (attached) cc'd src-committers alone. Sorry; I didn't realise that it's not amongst the lists at <https://lists.freebsd.org/>.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=b374a3921d97bdb20b103aaeb91988c3d355ea71 commit b374a3921d97bdb20b103aaeb91988c3d355ea71 Author: Graham Perrin <grahamperrin@FreeBSD.org> AuthorDate: 2023-06-27 19:22:32 +0000 Commit: Graham Perrin <grahamperrin@FreeBSD.org> CommitDate: 2023-06-27 19:22:32 +0000 hier(7): fix inline markup for a variable I mistakenly preceded macro Va with macro It in https://github.com/freebsd/freebsd-src/pull/763/commits/8ff26f2cb5c0d69cce319e1ac1f792ea4245445a https://bugs.freebsd.org/261349 PR: 261349 Approved by: emaste, imp, mhorne Fixes: 6469f9c hier(7): improvement, modernisation share/man/man7/hier.7 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
(In reply to Mike Karels from comment #22) If we're to delist /usr/freebsd-dist, then other things that _might_ be delisted (I'm in two minds) include: /boot/overlays/ /usr/tests/
(In reply to Graham Perrin from comment #25) Is /usr/freebsd-dist ever installed? I don't think so, it's just on the ISO images. /usr/tests is optional, but the man page is probably installed in any case. /boot/overlays sounds wrong; I don't see one of those. I have /boot/msdos/overlays on an ARM, but that isn't really part of the standard hierarchy.
(In reply to Mike Karels from comment #26) > … /usr/tests is optional, but the man page is probably installed > in any case. … According to <https://man.freebsd.org/cgi/man.cgi?query=tests&sektion=7&manpath=freebsd-release#HISTORY>, the FreeBSD Test Suite was installed by default in FreeBSD 11.0. Maybe it became optional with a later release. With or without a hier(7) listing for /usr/tests/, apropos tests finds tests(7) and (yes) I do find the manual page installed in the absence of the suite, which is fine.
(In reply to Graham Perrin from comment #25, in reply to Mike Karels from comment #26) I'm no longer in two minds about /boot/overlays/ – re: <https://github.com/freebsd/freebsd-src/commit/db180ae55c99fa3330e57ad1b76c9d4b30584e25>, it _is_ useful to have the listing, regardless of whether the directory is present in a standard installation of the OS.
(In reply to Graham Perrin from comment #28) overlays is not in /boot, but in /boot/dtb. I think it is unused, but I could be wrong. My RPi4 has /boot/msdos/dtb and /boot/msdos/overlays, but as indicated by the name, that is not part of the standard BSD filesystem hierarchy.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=acdf666147eea8bf8626d3733087861493d90e23 commit acdf666147eea8bf8626d3733087861493d90e23 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-06-28 16:21:28 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-06-28 16:22:30 +0000 hier(7): tweak /media description It comes as an empty directory by default. While here, use a serial (Oxford) comma, per the FDP Primer. PR: 261349 Reported by: karels Reviewed by: grahamperrin, karels Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40774 share/man/man7/hier.7 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
(In reply to Graham Perrin from comment #27) /usr/tests absolutely should stay, for the same reasons that /usr/src or /usr/ports should.
(In reply to Mitchell Horne from comment #31) I didn't quite finish writing the comment. I've proposed an adjusted description for /boot/dtb/overlays in D40785. FYI the source of truth for the default is DTBODIR in bsd.own.mk. Aside from this, is there anything else remaining that must be done before we can consider this bug 'fixed'?
(In reply to Mitchell Horne from comment #32) > remaining Without looking closely: the compat stuff requires attention (I see an unanswered question).
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=651d1efd96a692a141a4c61d54d6a41ee2c0d851 commit 651d1efd96a692a141a4c61d54d6a41ee2c0d851 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-06-29 16:53:52 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-06-29 16:55:17 +0000 hier(7): adjust overlays/ subdirectory Device tree overlays are installed in /boot/dtb/overlays by default. Adjust the comment to mention fdt_overlays and loader.conf, but do not repeat what is said in the parent directory's description. PR: 261349 Reviewed by: grahamperrin, kevans MFC after: 3 days Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40785 share/man/man7/hier.7 | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-)
(In reply to Graham Perrin from comment #33) Thanks, I am handling that one for /compat/. The only other thing I can spot is that /etc/ has gained some directories that could be added to this page. I don't plan to handle that immediately.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=5e7308a7bcb6675de6049afd4a5dd9d6795057b2 commit 5e7308a7bcb6675de6049afd4a5dd9d6795057b2 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-07-06 14:11:21 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-07-06 14:26:21 +0000 hier(7): remove entry for non-existent /usr/compat This is historical (?), but today /compat is the default according to linux(4). The only remaining reference to /usr/compat in the src tree is under tools/test/stress2. Add a next-level entry for /compat/linux. PR: 261349 Reviewed by: grahamperrin, karels, dchagin MFC after: 3 days Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40876 share/man/man7/hier.7 | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-)
I guess, we also want merges for most (not all) of the commits that were not marked MFC. Re: comment 5, there should be at least one exception.
(In reply to Graham Perrin from comment #37) The commits of mine that are not yet in stable/13 need to wait for your changes to be merged first to avoid conflicts. I can handle them all at once, or let you MFC your own changes, whichever you prefer. Warner's change from comment #4 is obsolete after I removed the /usr/src layout from hier(7), so the point about mips is moot.
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=ac2e58110f63bd28cac516685fbb38086071b47b commit ac2e58110f63bd28cac516685fbb38086071b47b Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-06-28 16:21:28 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-07-07 19:13:02 +0000 hier(7): tweak /media description It comes as an empty directory by default. While here, use a serial (Oxford) comma, per the FDP Primer. PR: 261349 Reported by: karels Reviewed by: grahamperrin, karels Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40774 (cherry picked from commit acdf666147eea8bf8626d3733087861493d90e23) share/man/man7/hier.7 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=7ff4d84527204590ea169bf41ee9628990d78cee commit 7ff4d84527204590ea169bf41ee9628990d78cee Author: Graham Perrin <grahamperrin@FreeBSD.org> AuthorDate: 2023-06-10 08:41:35 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-07-07 19:13:02 +0000 hier(7): improvement, modernisation Consistent use of lowercase, spacing between sections, etc. Cease mentioning floppy disks. De-list /usr/share/misc/fonts/, which has been ??? (without a description) for twenty-seven years. Change zpool to pool. (zpool is a command.) Uppercase PPP for Point-to-Point Protocol. A few other changes to wording, including avoidance of the phrase pre-fab. Update the descriptions of: * /tmp/ * /usr/share/misc/ * /var/preserve/ * /var/tmp/ * /var/tmp/vi.recover/. Refer to vi(1) instead of ex(1). https://bugs.freebsd.org/261349 PR: 261349 Reviewed by: mhorne Approved by: mhorne Pull request: https://github.com/freebsd/freebsd-src/pull/763 (cherry picked from commit 6469f9c595c609dd552ec198a16c471c87df7c57) (cherry picked from commit 5ca7f02946940ff698741d4da4a30b554cb0f592) (cherry picked from commit b374a3921d97bdb20b103aaeb91988c3d355ea71) share/man/man7/hier.7 | 288 ++++++++++++++++++++++---------------------------- 1 file changed, 128 insertions(+), 160 deletions(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=e3a1fe9acad96afbcecae1cd7f677ae64a93f89d commit e3a1fe9acad96afbcecae1cd7f677ae64a93f89d Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-06-29 16:53:52 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-07-07 19:13:02 +0000 hier(7): adjust overlays/ subdirectory Device tree overlays are installed in /boot/dtb/overlays by default. Adjust the comment to mention fdt_overlays and loader.conf, but do not repeat what is said in the parent directory's description. PR: 261349 Reviewed by: grahamperrin, kevans MFC after: 3 days Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40785 (cherry picked from commit 651d1efd96a692a141a4c61d54d6a41ee2c0d851) share/man/man7/hier.7 | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-)
A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=18ca9e6c5ff1fd08448d3c53debc8d4dac92a32e commit 18ca9e6c5ff1fd08448d3c53debc8d4dac92a32e Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-07-06 14:11:21 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-07-09 16:09:07 +0000 hier(7): remove entry for non-existent /usr/compat This is historical (?), but today /compat is the default according to linux(4). The only remaining reference to /usr/compat in the src tree is under tools/test/stress2. Add a next-level entry for /compat/linux. PR: 261349 Reviewed by: grahamperrin, karels, dchagin MFC after: 3 days Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40876 (cherry picked from commit 5e7308a7bcb6675de6049afd4a5dd9d6795057b2) share/man/man7/hier.7 | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-)
I've been working on modernizing hier(7) too. Freebsd teaches you how to use it, you install it and then the first MOTD says to look at hier(7). I use it since a childhood, and I didn't go into an IT career or school. I started reading % man hier. It searches very well, it's an index to the system. I can use freebsd because of it. Why unlist active parts of the system? My hier.7 is 177 lines longer than 13.2R and I've removed a few things that don't exist anymore and shortened several descriptions, but I did make /usr/local have two paragraphs instead of one. I'm still undecided about trying to fill it more. Is this the correct thread to share a unified diff for feedback to people who are working on maintaining hier.7? Even if it just shows you a direction native users are going with it. At the bottom man hier explains that it's documenting the standard install, but a well maintained installation has a customized version. Shouldn't that mean it's desirable to describe the base system as completely as possible? As briefly for each piece, but as many pieces as we can? I've been filling it in for weeks. The system manual is the least bloated form of documentation available/possible. Coverage isn't adding bloat. The opposite is my humble opinion, if it doesn't have enough accessibility and coverage, then the concept of documentation becomes bloated with another layer, the handbook has been moved to ports and requires a pdf or webbrowser. Man is fundamental.
Thanks, (In reply to Alexander Ziaee from comment #43) > … diff … For legibility, I prefer rendered (without markup). <https://reviews.freebsd.org/paste/raw/572/> is not recently updated, but you get the idea.
Created attachment 244338 [details] hier.7 rendered I can see that we've diverged slightly in some ways mdoc.7 and style.mdoc.5 are silent about, but hopefully you can overlook (or appreciate!) them and the additional content upstreamed in some form. If nothing else, this is what I'm doing, because "This manual page documents the default FreeBSD file system layout". To me that implies no intentional omission in the spirit of this document. There are some things I listed with no description because I didn't have a good description yet. Since the 14 alpha was released, I feel the need to share this in it's present state so that as much of it as everyone is willing to use can be available for new users in the release. Particularly: zapped synopsis because it isn't a synopsis describing the command line options. /var/log/messages absolutely must be listed guys, even you don't like my description and pick another, people new to unix-style systems do try freebsd all the time. If nobody tells you, it can take a very long time to realize there is a syslog everything is writing to. They are told to read man hier immediately upon logging in, so the inclusion of /var/log/messages in this document is quite serious. I used the term "BSD heritage" to describe the ancient artifacts in games and inetd, I think this is sets appropriate expectations for what they are if someone doesn't know. I know it's non-traditional to put the year in front of the release in history, but I'm 27 and that small addition makes young people realize something profound. Thank you for your time.
Created attachment 244339 [details] hier.7 ascii rendered Please excuse the previous incorrectly exported attachment.
Created attachment 244340 [details] hier.7 utf8 rendered Sorry for the noise. When I try to view the post-upload attachment created with % mandoc -T ascii hier.7 > hier.txt it doesn't look right. Therefore, here is the same document rendered with UTF8.
(In reply to Alexander Ziaee from comment #43) Hi Alexander, Thanks for your work and interest in hier(7) improvements. This is the right place to enter the discussion. You seem to be asking why we have removed some portions of the document. You can read the justification for each of the individual changes linked by 'See Also' above. In general I agree that the goal of the hier(7) page is to provide a complete overview of the standard FreeBSD filesystem hierarchy, and this page is an excellent resource for learning about the system. However, it is important that we aim for 'useful completeness' rather than 100% completeness. The reason is that every entry in this page adds to the maintenance burden. The existence of this PR is evidence that the maintenance burden of this page is bigger than the ability of the community to maintain it. So, to address the root of the problem, some of the updates to this page have removed information that was partially outdated and considered to be of secondary interest to most users; the best example is the contents of /usr/src. I will gladly review further contributions you have to hier(7). The rendered output is helpful to read, but to see what has been modified we also need a diff. To ease the review process, please submit this as a GitHub Pull Request, or to Phabricator (reviews.freebsd.org). You can tag me (@mhorne) as a reviewer on either site. Thanks!
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=9dfe484e126d0e477a0d79b3f7a2350af9f5e025 commit 9dfe484e126d0e477a0d79b3f7a2350af9f5e025 Author: Alexander Ziaee <concussious@runbox.com> AuthorDate: 2024-03-20 17:40:57 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2024-04-18 17:54:29 +0000 hier.7: polish entry to system manual Entries reworded to improve grammar or add keywords: - document description: substitute layout for index for first-glance - /etc/freebsd/update.conf - /usr/share/vi/ Entries that have been wordshuffled for brevity or consistency: - /{bin,libexec,nonexistent,sbin,tmp}/ - /boot/dtb/overlays/ - /boot/{defaults,efi,kernel,lua}/ - /usr/libexec/ - /var/{db,games,lib,log/{bsdisks.log,spool/,tmp/}} - /usr/share/sysroot/VERSION/MACHINE.MACHINE_ARCH/ (unfold a little) - /usr/local/share/doc/freebsd/ (unfold a little) Entries that have macro or linking adjustments: - /{boot,boot/efi,dev,etc,home,sbin,usr/bin}/ (overview or intro pages) - /media/ (bsdisks is from ports, but afaik pulled by every desktop) - /usr/share/{lib/,lib/dtrace/,libdata/games/,man/}/ (intro pages) - /var/log/messages (syslog(3) -> syslogd(8)) Entries that have been added: - /dev/{cuaU0,vmm,zvol}/ - /usr/share/{atf,bhyve}/ - /usr/share/libexec/hyperv/ (thanks @rtprio) - /local/<subdirectories>/ - /var/log/debug.log (thanks @pauamma) - /var/spool/{lock,lpd} Please forgive my earlier mistakes fixed in this commit: - /{dev,/usr/share/{calendar,misc}} : accidentally reverted description - /etc/local-unbound.conf/ (wrong link) - /usr/{freebsd-dist,lib32,libdata},/var/log/{dmesg.today,lpd-errs} (typos) - /{usr/libdata/gcc/,var/log/bsdisks.log} (removed, unnecessary) PR: 261349 Reviewed by: mhorne MFC after: 1 week Pull Request: https://github.com/freebsd/freebsd-src/pull/1131 share/man/man7/hier.7 | 207 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 123 insertions(+), 84 deletions(-)
With this most recent change, and all that preceded it, I am going to consider the modernization effort complete. There may be small tweaks or fixes still required, but this PR can be closed. Thanks to everyone who contributed. The MFC to stable branches will happen next week.
A commit in branch stable/14 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=63b747823bead05837f6893a2f2d38b516bc1e49 commit 63b747823bead05837f6893a2f2d38b516bc1e49 Author: Alexander Ziaee <concussious@runbox.com> AuthorDate: 2024-03-20 17:40:57 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2024-05-01 18:43:20 +0000 hier.7: polish entry to system manual Entries reworded to improve grammar or add keywords: - document description: substitute layout for index for first-glance - /etc/freebsd/update.conf - /usr/share/vi/ Entries that have been wordshuffled for brevity or consistency: - /{bin,libexec,nonexistent,sbin,tmp}/ - /boot/dtb/overlays/ - /boot/{defaults,efi,kernel,lua}/ - /usr/libexec/ - /var/{db,games,lib,log/{bsdisks.log,spool/,tmp/}} - /usr/share/sysroot/VERSION/MACHINE.MACHINE_ARCH/ (unfold a little) - /usr/local/share/doc/freebsd/ (unfold a little) Entries that have macro or linking adjustments: - /{boot,boot/efi,dev,etc,home,sbin,usr/bin}/ (overview or intro pages) - /media/ (bsdisks is from ports, but afaik pulled by every desktop) - /usr/share/{lib/,lib/dtrace/,libdata/games/,man/}/ (intro pages) - /var/log/messages (syslog(3) -> syslogd(8)) Entries that have been added: - /dev/{cuaU0,vmm,zvol}/ - /usr/share/{atf,bhyve}/ - /usr/share/libexec/hyperv/ (thanks @rtprio) - /local/<subdirectories>/ - /var/log/debug.log (thanks @pauamma) - /var/spool/{lock,lpd} Please forgive my earlier mistakes fixed in this commit: - /{dev,/usr/share/{calendar,misc}} : accidentally reverted description - /etc/local-unbound.conf/ (wrong link) - /usr/{freebsd-dist,lib32,libdata},/var/log/{dmesg.today,lpd-errs} (typos) - /{usr/libdata/gcc/,var/log/bsdisks.log} (removed, unnecessary) PR: 261349 Reviewed by: mhorne MFC after: 1 week Pull Request: https://github.com/freebsd/freebsd-src/pull/1131 (cherry picked from commit 9dfe484e126d0e477a0d79b3f7a2350af9f5e025) share/man/man7/hier.7 | 207 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 123 insertions(+), 84 deletions(-)