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)

1 files changed, 128 insertions, 160 deletions

diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7
index 5b8f19423c16..0ccc3679b91e 100644
--- a/share/man/man7/hier.7
+++ b/share/man/man7/hier.7
@@ -28,51 +28,51 @@
 .\"	@(#)hier.7	8.1 (Berkeley) 6/5/93
 .\" $FreeBSD$
 .\"
-.Dd May 30, 2023
+.Dd June 27, 2023
 .Dt HIER 7
 .Os
 .Sh NAME
 .Nm hier
 .Nd layout of file systems
 .Sh SYNOPSIS
-A sketch of the file system hierarchy.
+An overview of the file system hierarchy.
 .Sh DESCRIPTION
 .Bl -tag -width "/libexec/"
 .It Pa /
-root directory of the file system
+root directory
 .It Pa /bin/
-user utilities fundamental to both single-user and multi-user environments
+user utilities that are fundamental to single-user and multi-user modes
 .It Pa /boot/
-programs and configuration files used during operating system bootstrap
+programs and configuration files used during bootstrap of the operating system
 .Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
 .It Pa defaults/
-default bootstrapping configuration files; see
+default bootstrap configuration files; see
 .Xr loader.conf 5
 .It Pa dtb/
-Compiled flattened device tree (FDT) files; see
+compiled flattened device tree (FDT) files; see
 .Xr fdt 4
 and
 .Xr dtc 1
 .It Pa efi/
-Mount point for EFI System Partition (ESP) on UEFI systems
+mount point for the EFI System Partition (ESP) on UEFI systems
 .It Pa firmware/
-loadable kernel modules containing binary firmware for hardware that needs
-firmware downloaded to it to function
+loadable kernel modules containing binary firmware, for hardware to which
+firmware must be downloaded
 .It Pa kernel/
-pure kernel executable (the operating system loaded into memory
-at boot time) and kernel modules
+pure kernel executable (the operating system loaded into memory at boot time)
+and kernel modules
 .It Pa modules/
-third-party loadable kernel modules, such as the ones installed from
+third-party loadable kernel modules, such as those associated with
 .Xr ports 7
 .It Pa overlays/
-Compiled flattened device tree (FDT) overlays; see
+compiled flattened device tree (FDT) overlays; see
 .Xr fdt 4
 and
 .Xr dtc 1
 .It Pa zfs/
 .Xr zfs 8
-zpool cache files
+pool cache files
 .El
 .It Pa /compat/
 normally a link to
@@ -81,13 +81,12 @@ If not, then the
 .Pa /usr/compat
 comments apply
 .It Pa /dev/
-device special files managed by
+the normal mount point for
 .Xr devfs 5
 .Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
 .It Pa fd/
-file descriptor files;
-see
+file descriptor files; see
 .Xr fd 4
 .El
 .It Pa /home/
@@ -97,57 +96,51 @@ This is a symlink to
 .It Pa /etc/
 system configuration files and scripts
 .Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
 .It Pa bluetooth/
 bluetooth configuration files
 .It Pa defaults/
-default system configuration files;
-see
+default system configuration files; see
 .Xr rc 8
 .It Pa localtime
-local timezone information;
-see
+local timezone information; see
 .Xr ctime 3
 .It Pa mail/
-Sendmail control files
+.Xr sendmail 8
+control files
 .It Pa mtree/
-mtree configuration files;
-see
 .Xr mtree 8
+configuration files
 .It Pa pam.d/
-configuration files for the Pluggable Authentication Modules (PAM)
-library
+configuration files for the Pluggable Authentication Modules (PAM) library; see
+.Xr pam 3
 .It Pa periodic/
-scripts that are run daily, weekly, and monthly, via
+scripts that are run daily, weekly, or monthly by
 .Xr cron 8 ;
 see
 .Xr periodic 8
 .It Pa ppp/
-ppp configuration files;
-see
+PPP configuration files; see
 .Xr ppp 8
 .It Pa rc.d/
-system and daemon startup/control scripts;
-see
+system and daemon startup/control scripts; see
 .Xr rc 8
 .It Pa security/
-OpenBSM audit configuration files;
-see
+OpenBSM audit configuration files; see
 .Xr audit 8
 .It Pa ssh/
-OpenSSH configuration files;
-see
+OpenSSH configuration files; see
 .Xr ssh 1
 .It Pa ssl/
 OpenSSL configuration files
 .El
 .It Pa /lib/
-critical system libraries needed for binaries in
+system libraries that are critical to binaries in
 .Pa /bin
 and
 .Pa /sbin
 .Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "nvmecontrol/" -compact
 .It Pa casper/
 service-specific
 .Xr libcasper 3
@@ -162,43 +155,41 @@ vendor-specific libraries to extend the
 utility
 .El
 .It Pa /libexec/
-critical system utilities needed for binaries in
+system utilities that are critical to binaries in
 .Pa /bin
 and
 .Pa /sbin
 .It Pa /media/
-contains subdirectories to be used as mount points
-for removable media such as CDs, USB drives, and
-floppy disks
+contains subdirectories that are mount points for removable media such as
+USB drives, CDs and DVDs
 .It Pa /mnt/
-empty directory commonly used by
-system administrators as a temporary mount point
+empty directory commonly used by system administrators as a temporary mount
+point
 .It Pa /net/
-automounted NFS shares;
-see
+automounted NFS shares; see
 .Xr auto_master 5
 .It Pa /nonexistent/
-a non-existent directory;
-by convention, it serves as a home directory
-for special user accounts
-that need no home directory;
-see also
+a non-existent directory; conventionally, a home directory for special user
+accounts that do not require a home directory.  See also
 .Pa /var/empty/
 .It Pa /proc/
-process file system;
-see
+process file system; see
 .Xr procfs 5
 .It Pa /rescue/
-statically linked programs for emergency recovery;
-see
+statically-linked programs for emergency recovery; see
 .Xr rescue 8
 .It Pa /root/
-root's HOME directory
+home directory of the root user
 .It Pa /sbin/
-system programs and administration utilities
-fundamental to both single-user and multi-user environments
+system programs and administration utilities that are fundamental to
+single-user and multi-user modes
 .It Pa /tmp/
-temporary files that are not guaranteed to persist across system reboots
+temporary files that may be removed by
+.Xr rc 8 ;
+see the
+.Va clear_tmp_enable
+variable of
+.Xr rc.conf 5
 .It Pa /usr/
 contains the majority of user utilities and applications
 .Pp
@@ -206,13 +197,11 @@ contains the majority of user utilities and applications
 .It Pa bin/
 common utilities, programming tools, and applications
 .It Pa compat/
-files needed to support binary compatibility with other operating systems;
-see
+files needed to support binary compatibility with other operating systems; see
 .Xr linux 4
 .It Pa freebsd-dist/
 distribution files
-.Pq like base.txz ;
-see
+.Pq like base.txz ; see
 .Xr release 7
 and
 .Xr bsdinstall 8
@@ -224,7 +213,6 @@ the layout is not standardized, but a typical interactive user
 .Dv beastie
 might receive their own directory under
 .Pa /usr/home/beastie
-.Pp
 .It Pa lib/
 shared and archive
 .Xr ar 1 Ns -type
@@ -248,15 +236,16 @@ miscellaneous utility data files
 .It Pa gcc/
 GCC configuration data
 .It Pa ldscripts/
-linker scripts;
-see
+linker scripts; see
 .Xr ld 1
 .It Pa pkgconfig/
-pc files
+.Xr pc 5 Pq Pa ports/devel/pkgconf
+files; collections of compiler flags, linker flags, and other information
+relevant to library use
 .El
 .Pp
 .It Pa libexec/
-system daemons & system utilities (executed by other programs)
+system daemons and system utilities that are executed by other programs
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa aout/
@@ -264,14 +253,12 @@ utilities to manipulate a.out executables
 .It Pa elf/
 utilities to manipulate ELF executables
 .It Pa lpr/
-utilities and filters for LP print system;
-see
+utilities and filters for LP print system; see
 .Xr lpr 1
 .It Pa sendmail/
 the
 .Xr sendmail 8
-binary;
-see
+binary; see
 .Xr mailwrapper 8
 .It Pa sm.bin/
 restricted shell for
@@ -292,8 +279,7 @@ the general layout sketched out by
 for
 .Pa /usr
 should be used.
-Exceptions are the
-ports documentation
+Exceptions are the ports documentation
 .Po in
 .Pa share/doc/<port>/ Ns Pc ,
 and
@@ -303,27 +289,25 @@ and
 .It Pa obj/
 architecture-specific target tree produced by building
 .Fx
-from source;
-see
+from source; see
 .Xr build 7
 .It Pa ports/
 .Fx
 ports collection; see
 .Xr ports 7
 .It Pa sbin/
-system daemons & system utilities (executed by users)
+system daemons and system utilities that are executed by users
 .It Pa share/
 architecture-independent files
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa calendar/
-a variety of pre-fab calendar files;
-see
+system-wide calendar files; see
 .Xr calendar 1
 .It Pa dict/
-word lists;
-see
+word lists; see
 .Xr look 1
+.Pp
 .Bl -tag -width Fl -compact
 .It Pa freebsd
 .Fx Ns -specific
@@ -331,6 +315,7 @@ terms, proper names, and jargon
 .It Pa web2
 words from Webster's Second International
 .El
+.Pp
 .It Pa doc/
 miscellaneous documentation
 .It Pa examples/
@@ -338,9 +323,10 @@ various examples for users and programmers
 .It Pa firmware/
 firmware images loaded by userland programs
 .It Pa games/
-ASCII text files used by various games
+used by various games
 .It Pa keys/
 known trusted and revoked keys
+.Pp
 .Bl -tag -width Fl -compact
 .It Pa pkg/
 fingerprints for
@@ -348,25 +334,23 @@ fingerprints for
 and
 .Xr pkg 8
 .El
+.Pp
 .It Pa locale/
-localization files;
-see
+localization files; see
 .Xr setlocale 3
 .It Pa man/
 manual pages
 .It Pa misc/
-miscellaneous system-wide ASCII text files
+miscellaneous system-wide files
+.Pp
 .Bl -tag -width Fl -compact
-.It Pa fonts/
-???
 .It Pa termcap
-terminal characteristics database;
-see
+terminal characteristics database; see
 .Xr termcap 5
 .El
+.Pp
 .It Pa mk/
-templates for make;
-see
+templates for make; see
 .Xr make 1
 .It Pa nls/
 national language support files
@@ -382,6 +366,7 @@ example
 (dot) files for new accounts
 .It Pa snmp/
 MIBs, example files and tree definitions for the SNMP daemon
+.Pp
 .Bl -tag -width Fl -compact
 .It Pa defs/
 tree definition files for use with
@@ -389,20 +374,19 @@ tree definition files for use with
 .It Pa mibs/
 MIB files
 .El
+.Pp
 .It Pa syscons/
-files used by syscons;
-see
 .Xr syscons 4
+files
+.Pp
 .Bl -tag -width Fl -compact
 .It Pa fonts/
-console fonts;
-see
+console fonts; see
 .Xr vidcontrol 1
 and
 .Xr vidfont 1
 .It Pa keymaps/
-console keyboard maps;
-see
+console keyboard maps; see
 .Xr kbdcontrol 1
 and
 .Xr kbdmap 1
@@ -410,36 +394,33 @@ and
 console screen maps
 .El
 .It Pa tabset/
-tab description files for a variety of terminals; used in
-the termcap file;
+tab description files for a variety of terminals; used in the termcap file;
 see
 .Xr termcap 5
 .It Pa vi/
 localization support and utilities for
 .Xr vi 1
 .It Pa vt/
-files used by vt;
-see
 .Xr vt 4
+files
+.Pp
 .Bl -tag -width Fl -compact
 .It Pa fonts/
-console fonts;
-see
+console fonts; see
 .Xr vidcontrol 1
 and
 .Xr vidfont 1
 .It Pa keymaps/
-console keyboard maps;
-see
+console keyboard maps; see
 .Xr kbdcontrol 1
 and
 .Xr kbdmap 1
 .\" .It Pa scrnmaps/
 .\" console screen maps
 .El
+.Pp
 .It Pa zoneinfo/
-timezone configuration information;
-see
+timezone configuration information; see
 .Xr tzfile 5
 .El
 .Pp
@@ -452,41 +433,39 @@ The layout of the source tree is described by the top-level
 file.
 .Pp
 .It Pa tests/
-The
+the
 .Fx
 test suite; see
 .Xr tests 7
 .El
 .It Pa /var/
-multi-purpose log, temporary, transient, and spool files
+log, temporary, transient, and spool files
 .Pp
-.Bl -tag -width "defaults/" -compact
+.Bl -tag -width "preserve/" -compact
 .It Pa account/
 system accounting files
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa acct
-execution accounting file;
-see
+execution accounting file; see
 .Xr acct 5
 .El
 .Pp
 .It Pa at/
-timed command scheduling files;
-see
+timed command scheduling files; see
 .Xr at 1
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa jobs/
-directory containing job files
+job files
 .It Pa spool/
-directory containing output spool files
+output spool files
 .El
 .Pp
 .It Pa backups/
 miscellaneous backup files
 .It Pa cache/
-miscellaneous cached files
+miscellaneous cache files
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa pkg/
@@ -495,34 +474,33 @@ cached packages for
 .El
 .Pp
 .It Pa crash/
-default directory to store kernel crash dumps; see
+default directory for kernel crash dumps; see
 .Xr crash 8
 and
 .Xr savecore 8
 .It Pa cron/
-files used by cron;
-see
 .Xr cron 8
+files
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa tabs/
-crontab files;
-see
 .Xr crontab 5
+files
 .El
 .Pp
 .It Pa db/
-miscellaneous automatically generated system-specific database files
-.Bl -tag -width Fl -compact
+miscellaneous automatically-generated system-specific database files
+.Pp
+.Bl -tag -width "freebsd-update/" -compact
 .It Pa freebsd-update/
+temporary files and downloads for
 .Xr freebsd-update 8
-work directory for temporary files and downloaded updates
 .El
+.Pp
 .It Pa empty/
-empty directory for use by programs that need a specifically empty directory.
-Used for instance by
+for use by programs that require an empty directory.
+Uses include privilege separation by
 .Xr sshd 8
-for privilege separation
 .It Pa games/
 miscellaneous game status and score files
 .It Pa heimdal/
@@ -531,33 +509,26 @@ Kerberos server databases; see
 .It Pa log/
 miscellaneous system log files
 .Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "utx.lastlogin" -compact
 .It Pa utx.lastlogin
-last login log;
-see
+last login log; see
 .Xr getutxent 3
 .It Pa utx.log
-login/logout log;
-see
+login/logout log; see
 .Xr getutxent 3
 .El
 .Pp
 .It Pa mail/
 user mailbox files
 .It Pa msgs/
-system messages database;
-see
+system messages database; see
 .Xr msgs 1
 .It Pa preserve/
-temporary home of files preserved after an accidental death
-of an editor;
-see
-.Xr ex 1
+unused, present for historical reasons
 .It Pa quotas/
 file system quota information files
 .It Pa run/
-system information files describing various info about
-system since it was booted
+files containing information about the operating system since it was booted
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa bhyve/
@@ -570,14 +541,12 @@ writable by the
 group for command connection sockets; see
 .Xr ppp 8
 .It Pa utx.active
-database of current users;
-see
+database of current users; see
 .Xr getutxent 3
 .El
 .Pp
 .It Pa rwho/
-rwho data files;
-see
+rwho data files; see
 .Xr rwhod 8 ,
 .Xr rwho 1 ,
 and
@@ -585,29 +554,28 @@ and
 .It Pa spool/
 miscellaneous printer and mail system spooling directories
 .Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "clientmqueue/" -compact
 .It Pa clientmqueue/
-undelivered submission mail queue;
-see
+undelivered submission mail queue; see
 .Xr sendmail 8
 .It Pa ftp/
-ftp root directory;
-see
+ftp root directory; see
 .Xr ftpd 8
 .It Pa mqueue/
-undelivered mail queue;
-see
+undelivered mail queue; see
 .Xr sendmail 8
 .It Pa output/
 line printer spooling directories
 .El
 .Pp
 .It Pa tmp/
-temporary files that are kept between system reboots
+temporary files that are not removed by
+.Xr rc 8
 .Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "vi.recover/" -compact
 .It Pa vi.recover/
-the directory where recovery files are stored
+.Xr vi 1
+recovery files
 .El
 .Pp
 .It Pa yp/
@@ -618,8 +586,8 @@ the NIS maps; see
 .Sh NOTES
 This manual page documents the default
 .Fx
-file system layout, but
-the actual hierarchy on a given system is defined at the system
+file system layout.
+The actual hierarchy on a given system is defined at the system
 administrator's discretion.
 A well-maintained installation will include a customized version of
 this document.