Re: git: 6469f9c595c6 - main - hier(7): improvement, modernisation
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 10 Jun 2023 18:32:02 UTC
> The branch main has been updated by grahamperrin: > > 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). Many split lines and full break have been undone and I question one unneeded comma. I also question wither the whole of this commit adds value, or removes it as much of it simply rewords things that mean exactly the same thing. > 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(-) > > diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 > index 18b72fa03ecb..39159e51b7b8 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 10, 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. No meaningful change. > .Sh DESCRIPTION > .Bl -tag -width "/libexec/" > .It Pa / > -root directory of the file system > +root directory Why so tearse here? > .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 Again no meaningful change > .It Pa /boot/ > -programs and configuration files used during operating system bootstrap > +programs and configuration files used during bootstrap of the operating system No meaningful change > .Pp > -.Bl -tag -width "defaults/" -compact > +.Bl -tag -width "nvmecontrol/" -compact > .It Pa defaults/ > -default bootstrapping configuration files; see > +default bootstrap configuration files; see No meaningful change > .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 Why is comma needed before for? And if it is needed the lines should be split there: +loadable kernel modules containing binary firmware, +for hardware to which firmware must be downloaded I see no change in meaning. > .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 No meaningful change. > .It Pa modules/ > -third-party loadable kernel modules, such as the ones installed from > +third-party loadable kernel modules, such as those associated with No meaningful change. > .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 +zfs pool cache files IMHO, would be more correct. > .El > .It Pa /compat/ > normally a link to > @@ -81,75 +81,67 @@ If not, then the > .Pa /usr/compat > comments apply > .It Pa /dev/ > -device special files managed by > +the normal mount point for No value added, and and removes details about what is in the directory. > .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 It is desirable to start a new line at full stops, I believe ; is considered a full stop. Though there are other parts of this file that hve this "; see" format. > .Xr fd 4 > .El > .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 I believe and is the proper conjuntion here, they are run at all 3 times, not at 1 of the 3. > .Xr cron 8 ; > see > .Xr periodic 8 > .It Pa ppp/ > -ppp configuration files; > -see > +PPP configuration files; see Mixed emotions. The command is "ppp" that uses these configuration files, the protocol is often capatilized as PPP. > .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 /home/ > -users' HOME directories; > -the layout is not standardized, but a typical interactive user > +users' home directories; whilst the layout is not standardized, the typical home for an interactive user This needs line breaks. +users' home directories; +whilst the layout is not standardized, +the typical home for an interactive user > .Dv beastie > -might receive their own directory > -.Pa /home/beastie > +would be > +.Pa /home/beastie/ I see no value added. j > .It Pa /lib/ > -critical system libraries needed for binaries in > +system libraries that are critial to binaries in Again, no functional information changed. > .Pa /bin > and > .Pa /sbin > .Pp > -.Bl -tag -width "defaults/" -compact > +.Bl -tag -width "nvmecontrol/" -compact > .It Pa casper/ > service-specific > .Xr libcasper 3 > @@ -164,43 +156,41 @@ vendor-specific libraries to extend the > utility > .El > .It Pa /libexec/ > -critical system utilities needed for binaries in > +system utilities that are critial to binaries in Ditto > .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 Ditto > .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 Needlessly makes long lines. > .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 No functional change, makes ong lines. > .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 No functional change > .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 Ditto > .It Pa /tmp/ > -temporary files that are not guaranteed to persist across system reboots > +temporary files that may be removed by I see this as a degrade in the information, though adding info about clear_tmp_enable is good, loss of the "not guaranteed to persist" is not. > +.Xr rc 8 ; > +see the > +.It Va clear_tmp_enable > +variable of > +.Xr rc.conf 5 > .It Pa /usr/ > contains the majority of user utilities and applications > .Pp > @@ -208,19 +198,16 @@ 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 > .It Pa include/ > standard C include files > -.Pp > .It Pa lib/ > shared and archive > .Xr ar 1 Ns -type > @@ -244,17 +231,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/ > .Xr pc 5 Pq Pa ports/devel/pkgconf > -files: collections of compiler flags, linker flags, and other > -information relevant to library use > +files; collections of compiler flags, linker flags, and other information > +relevant to library use Line filling in man pages is usually not desired. Stopping here... regards, Rod > .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/ > @@ -262,14 +248,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 > @@ -290,8 +274,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 > @@ -301,27 +284,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 > @@ -329,6 +310,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/ > @@ -336,9 +318,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 > @@ -346,25 +329,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 > @@ -380,6 +361,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 > @@ -387,29 +369,30 @@ 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 > .It Pa scrnmaps/ > console screen maps > .El > +.Pp > .It Pa sysroot/ > files necessary for the -sysroot compiler/linker argument to build non-native > -binaries. > +binaries > +.Pp > .Bl -tag -width Fl -compact > .It Pa VERSION/ > files for > @@ -420,6 +403,7 @@ By convention, > matches > .Xr uname 1 > .Fl r . > +.Pp > .Bl -tag -width Fl -compact > .It Pa MACHINE.MACHINE_ARCH/ > represent the binary ABI for these files. > @@ -433,37 +417,35 @@ matches > .Fl p . > .El > .El > +.Pp > .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 > @@ -476,41 +458,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/ > @@ -519,34 +499,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/ > @@ -555,33 +534,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/ > @@ -594,14 +566,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 > @@ -609,29 +579,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/ > @@ -642,8 +611,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. > -- Rod Grimes rgrimes@freebsd.org