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)

1 files changed, 123 insertions, 84 deletions

diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7
index 8cd6ff338b5c..7d164b5683d6 100644
--- a/share/man/man7/hier.7
+++ b/share/man/man7/hier.7
@@ -28,12 +28,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 21, 2024
+.Dd April 18, 2024
 .Dt HIER 7
 .Os
 .Sh NAME
 .Nm hier
-.Nd layout of
+.Nd index of
 .Fx
 file system hierarchy
 .Sh DESCRIPTION
@@ -44,15 +44,18 @@ root directory of the file system
 .Fx
 copyright information
 .It Pa /bin/
-user utilities fundamental to both single and multi-user modes
+fundamental
+.Bx
+user utilities; see
+.Xr intro 1
 .It Pa /boot/
 programs and configurations used during
 .Fx
-bootstrap
+.Xr boot 8
 .Pp
 .Bl -tag -width "loader.conf.d/" -compact
 .It Pa defaults/
-default bootstrap configuration files; see
+default boot configuration files; see
 .Xr loader.conf 5
 .It Pa device.hints
 kernel variables for controlling drivers; see
@@ -65,14 +68,18 @@ and
 .Pp
 .Bl -tag -width "overlays/" -compact
 .It Pa overlays/
-compiled flattened device tree (FDT) overlays; these can be applied using the
+compiled
+.Xr fdt 4
+overlays; see
 .Va fdt_overlays
-setting in
+in
 .Xr loader.conf 5
 .El
 .Pp
 .It Pa efi/
-mount point for EFI System Partition (ESP) on UEFI systems
+the
+.Xr uefi 8
+EFI System Partition (ESP) mount point
 .It Pa firmware/
 loadable binary firmware kernel modules
 .It Pa fonts/
@@ -84,9 +91,8 @@ and
 beastie boot menu images; see
 .Xr loader_lua 8
 .It Pa kernel/
-pure kernel executable
-.Pq the operating system loaded into memory at boot time
-and kernel modules; see
+.Fx
+kernel and modules; see
 .Xr kldstat 8
 .It Pa kernel.old/
 alternative kernel and modules
@@ -97,7 +103,7 @@ boot loader configuration; see
 .Xr loader.conf 5
 configuration files
 .It Pa lua/
-scripts for kernel bootstrapping final stage; see
+scripts for the Lua boot loader; see
 .Xr loader_lua 8
 .It Pa modules/
 third-party loadable kernel modules, such as those installed with
@@ -119,7 +125,9 @@ default location for
 compatibility run-time
 .El
 .It Pa /dev/
-device special files managed by
+device nodes and special files; see
+.Xr intro 4
+and
 .Xr devfs 5
 .Pp
 .Bl -tag -width "loader.conf.d" -compact
@@ -129,12 +137,15 @@ first ATA storage device
 first partition on ada0
 .It Pa cd0
 first optical drive
+.It Pa cuaU0
+first USB serial port; see
+.Xr cu 1
 .It Pa da0
 first SCSI storage device
 .It Pa da0s1
 first partition on da0
 .It Pa dri/
-GPU character device node; see
+GPU character device nodes; see
 .Xr drm 7
 .It Pa drm/
 GPU
@@ -157,7 +168,8 @@ infinite loop that accepts anything and contains nothing
 .It Pa nvd0
 first NVMe storage device using NVMe namespaces
 .It Pa pts/
-pseduo-terminals
+pseduo-terminals; see
+.Xr pts 4
 .It Pa random
 source of weak randomness; see
 .Xr random 4
@@ -165,12 +177,20 @@ source of weak randomness; see
 first tape drive
 .It Pa usb/
 USB busses
+.It Pa vmm/
+active
+.Xr bhyve 8
+virtual machines
+.It Pa zvol/
+.Xr zfs 8
+volumes
 .El
 .It Pa /entropy
 provides initial state to RNG; see
 .Xr save-entropy 8
 .It Pa /etc/
-system wide configuration files and scripts
+base system configuration files and scripts; see
+.Xr intro 5
 .Pp
 .Bl -tag -width "freebsd-update.conf" -compact
 .It Pa auto_master
@@ -197,7 +217,7 @@ boot time device configuration
 configuration for
 .Xr dma 8
 .It Pa freebsd-update.conf
-configuration for the base system updater
+configuration for the base system updater; see
 .Xr freebsd-update 8
 .It Pa fstab
 static filesystem configuration; see
@@ -214,7 +234,7 @@ local timezone information; see
 .Xr ctime 3
 .It Pa jail.conf.d/
 .Xr jail 8
-startup scripts.
+startup scripts
 .It Pa login.conf
 login class capability database; see
 .Xr login.conf 5
@@ -275,7 +295,7 @@ DNS configuration; see
 .It Pa resolvconf.conf
 DNS configuration manager configuration, often generated by
 local-unbound; see
-.Xr local_unbound 8
+.Xr local-unbound 8
 or
 .Xr resolvconf 8
 .It Pa security/
@@ -300,11 +320,11 @@ client wifi configuration; see
 .El
 .It Pa /home/
 home directories for users; the typical home for an interactive user
-.Dv beastie
+.Va beastie
 would be
 .Pa /home/beastie/
 .It Pa /lib/
-system libraries that are critical to binaries in
+system libraries critical to binaries in
 .Pa /bin
 and
 .Pa /sbin
@@ -320,16 +340,18 @@ vendor-specific libraries to extend the
 utility
 .El
 .It Pa /libexec/
-system utilities that are critical to binaries in
+system utilities critical to binaries in
 .Pa /bin
 and
 .Pa /sbin
 .It Pa /media/
 mount points for removable storage media such as CDs, DVDs,
 and USB drives; see
-.Xr automount 8
+.Xr automount 8 ,
 or
 .Xr bsdisks 8
+if a using a desktop environment from
+.Xr ports 7
 .It Pa /mnt/
 empty directory commonly used by
 system administrators as a temporary mount point
@@ -338,8 +360,7 @@ 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
+by convention, it serves as a home directory for user accounts
 that need no home directory; see also
 .Pa /var/empty/
 .It Pa /proc/
@@ -351,33 +372,37 @@ statically linked programs for emergency recovery; see
 .It Pa /root/
 home directory of the root user
 .It Pa /sbin/
-system programs and administration utilities
-fundamental to both single and multi-user modes
+fundamental
+.Bx
+system administration utilities; see
+.Xr intro 8
 .It Pa /tmp/
-temporary files that may be removed by
-.Xr rc 8 ;
-see the
+temporary files commonly removed between system reboots;
+see
 .Va clear_tmp_enable
-variable of
+in
 .Xr rc.conf 5
 .It Pa /usr/
 contains the majority of user utilities and applications
 .Pp
 .Bl -tag -width "freebsd-dist/" -compact
 .It Pa bin/
-common utilities, programming tools, and applications
+common utilities, programming tools, and applications; see
+.Xr intro 1
 .It Pa freebsd-dist/
 distribution files
-.Pq like base.txz ; see
+.Pq like base.txz ;
+see
 .Xr release 7
 and
 .Xr bsdinstall 8
 .It Pa include/
 standard C include header files
 .It Pa lib/
-shared and archive
+shared and
 .Xr ar 1 Ns -type
-libraries
+libraries; see
+.Xr intro 3
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa clang/
@@ -388,7 +413,8 @@ shared libraries for compatibility
 .It Pa debug/
 standalone debug data for the kernel and base system libraries and binaries
 .It Pa dtrace/
-DTrace library scripts
+.Xr dtrace 1
+library scripts
 .It Pa engines/
 OpenSSL
 .Pq Cryptography/SSL toolkit
@@ -401,7 +427,7 @@ shared libraries for internationalization
 .El
 .Pp
 .It Pa lib32/
-32-bit comparability libraries
+32-bit compatibility libraries
 .It Pa libdata/
 miscellaneous utility data files
 .Pp
@@ -414,8 +440,9 @@ collections of compiler and linker flags for the
 .Xr pkgconf 1
 development tool
 .El
+.Pp
 .It Pa libexec/
-system daemons and utilities that are executed by other programs
+system daemons and utilities executed by programs
 .Pp
 .Bl -tag -width "bsdinstall/" -compact
 .It Pa bsdconfig/
@@ -432,7 +459,7 @@ profiles for
 utilities called by
 .Xr fwget 8
 .It Pa hyperv/
-???
+scripts for communicating with the Hyper-V hypervisor
 .It Pa lpr/
 utilities and filters for the line printer system; see
 .Xr lpr 1
@@ -451,26 +478,36 @@ Z file system utilities
 .El
 .Pp
 .It Pa local/
-default destination for local executables, libraries, etc, installed by
+local executables, libraries, etc, installed by
 .Xr pkg 7
 or
 .Xr ports 7
 .Pp
-within
-.Pa local/ ,
-the general layout sketched out by
-.Nm
-for
-.Pa /usr
-should be used ; exceptions are the ports documentation
-.Po in
-.Pa share/doc/<port>/ Ns Pc ,
-and
-.Pa /usr/local/etc
-.Po mimics
-.Pa /etc Ns Pc
-.Pp
 .Bl -tag -width Fl -compact
+.It Pa bin/
+local user utilities, see
+.Xr intro 1
+.It Pa etc/
+local program configurations
+.It Pa include/
+local library headers
+.It Pa lib/
+local libraries
+.It Pa lib32/
+local 32-bit compatability libraries
+.It Pa libdata/
+local utility data files
+.It Pa libexec/
+utilities executed by local utilities
+.It Pa man/
+local manual pages; see
+.Xr man 1
+.It Pa sbin/
+local administration utilities
+.It Pa share/
+local architecture-independent files
+.It Pa share/doc/
+local documentation
 .It Pa share/doc/freebsd/
 articles, books, FAQ, and handbooks available from the
 .Fx
@@ -487,13 +524,20 @@ from source; see
 ports collection; see
 .Xr ports 7
 .It Pa sbin/
-system daemons and utilities meant for user execution
+system daemons and utilities meant for user execution; see
+.Xr intro 8
 .It Pa share/
 architecture-independent files
 .Pp
 .Bl -tag -width Fl -compact
+.It Pa atf/
+scripts for the Automated Testing Framework; see
+.Xr ATF 7
+.It Pa bhyve/
+.Xr bhyve 8
+keyboard mappings
 .It Pa calendar/
-a variety of pre-fab calendar files; see
+system-wide calendar files; see
 .Xr calendar 1
 .It Pa certs/
 TLS certificates for
@@ -522,7 +566,8 @@ firmware images loaded by userland programs
 .It Pa games/
 ASCII text files used by
 .Bx
-heritage games
+heritage games, see
+.Xr intro 6
 .It Pa keys/
 known trusted and revoked keys
 .Pp
@@ -538,9 +583,10 @@ and
 localization files; see
 .Xr setlocale 3
 .It Pa man/
-system manual pages
+system manual pages; see
+.Xr man 1
 .It Pa misc/
-miscellaneous system-wide ASCII text files
+miscellaneous system-wide files
 .Pp
 .Bl -tag -width Fl -compact
 .It Pa ascii
@@ -606,7 +652,7 @@ console screen maps
 files necessary for the -sysroot compiler/linker argument to build non-native
 binaries
 .Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width "VERSION/" -compact
 .It Pa VERSION/
 files for
 .Fx
@@ -616,9 +662,7 @@ by convention,
 matches
 .Xr uname 1
 .Fl r
-.Pp
-.Bl -tag -width Fl -compact
-.It Pa MACHINE.MACHINE_ARCH/
+.It Pa VERSION/MACHINE.MACHINE_ARCH/
 represent the binary ABI for these files;
 .Dq MACHINE
 matches
@@ -629,15 +673,15 @@ matches
 .Xr uname 1
 .Fl p
 .El
-.El
 .Pp
 .It Pa tabset/
 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
+localization support and utilities for the
 .Xr vi 1
+editor
 .It Pa vt/
 files used by the system console; see
 .Xr vt 4
@@ -735,7 +779,7 @@ crontab files; see
 .El
 .Pp
 .It Pa db/
-miscellaneous automatically-generated system-specific database files
+autogenerated system-specific database files
 .Pp
 .Bl -tag -width "freebsd-update/" -compact
 .It Pa etcupdate/
@@ -754,14 +798,14 @@ used for instance by
 .Xr sshd 8
 for privilege separation
 .It Pa games/
-miscellaneous game status and score files for
+status and score files for
 .Bx
 heritage games
 .It Pa heimdal/
 Kerberos server databases; see
 .Xr kdc 8
 .It Pa lib/
-holds state information for applications ported from linux
+state information for ported Linux applications
 .It Pa log/
 system log files
 .Pp
@@ -770,8 +814,7 @@ system log files
 .Xr Xserver 1
 log, if
 .Xr X 7
-is installed
-rotates to
+is installed rotates to
 .Pa Xorg.0.log.old
 .It Pa aculog
 serial line access log; see
@@ -780,11 +823,6 @@ serial line access log; see
 system authentication log
 .It Pa bsdinstall_log
 system installation log
-.It Pa bsdisks.log
-FreeDesktop.org automounter log, if a desktop environment is using
-.Xr bsdisks 8 ,
-from
-.Xr ports 7
 .It Pa cron
 scheduled task log; see
 .Xr cron 8
@@ -796,20 +834,19 @@ default log for system daemons
 .It Pa devd.log
 default log for device state change daemon
 .It Pa dmesg.today
-system message buffer log
-Rotates to
+system message buffer log, rotates to
 .Pa dmesg.yesterday
 .It Pa debug.log
-???
+undiscarded debug syslog messages
 .It Pa lpd-errs
-logs for the line printer daemon; see
+logs for the line printer spooler daemon; see
 .Xr lpd 8
 .It Pa maillog
 .Xr sendmail 8
 log, rotates and compresses to maillog.0.bz2
 .It Pa messages
 general system log; see
-.Xr syslog 3
+.Xr syslogd 8
 .It Pa mount.today
 currently loaded
 .Xr fstab 5 ,
@@ -879,7 +916,7 @@ information about other systems on the local network; see
 and
 .Xr ruptime 1
 .It Pa spool/
-miscellaneous printer and mail system spooling directories
+printer and mail system spooling directories
 .Pp
 .Bl -tag -width "clientmqueue/" -compact
 .It Pa clientmqueue/
@@ -894,7 +931,10 @@ undelivered mail queue for
 Mail Agent; see
 .Xr dma 8
 .It Pa lock/
-???
+serial device locks; see
+.Xr uucplock 3
+.It Pa lpd/
+line printer spooler daemon spool
 .It Pa ftp/
 ftp root directory; see
 .Xr ftpd 8
@@ -906,8 +946,7 @@ line printer spooling directories
 .El
 .Pp
 .It Pa tmp/
-temporary files that are not removed between system reboots by
-.Xr rc 8
+temporary files not removed between system reboots
 .Pp
 .Bl -tag -width "vi.recover/" -compact
 .It Pa vi.recover/