freebsd-version.1: corrections and suggested improvements

bin/freebsd-version/freebsd-version.1

@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 1, 2021
+.Dd July 6, 2024
 .Dt FREEBSD-VERSION 1
 .Os
 .Sh NAME
@@ -37,10 +37,10 @@
 The
 .Nm
 utility makes a best effort to determine the version and patch level
-of the installed kernel and / or userland.
+of the kernel and / or userland.
 .Pp
-The following options are available:
+.Ss Options
 .Bl -tag -width Fl
 .It Fl k
 Print the version and patch level of the installed kernel.
 Unlike
@@ -56,9 +56,7 @@
 this is unaffected by environment variables.
 .It Fl u
 Print the version and patch level of the installed userland.
-These are hardcoded into
-.Nm
-during the build.
+The same information will be printed if no option is specified.
 .It Fl j Ar jail
 Print the version and patch level of the installed userland in the
 given jail specified by
@@ -68,25 +66,30 @@
 This option can be specified multiple times.
 .El
 .Pp
-If several of the above options are specified,
-.Nm
-will print the installed kernel version first, then the running kernel
-version, next the userland version, and finally the userland version
-of the specified jails, on separate lines.
-If neither is specified, it will print the userland version only.
+If multiple options are specified, information will be in a preset
+order (regardless of user-specified order):
+.Pp
+.Bl -dash -compact
+.It
+installed kernel
+.It
+running kernel
+.It
+userland
+.It
+jail userland.
+.El
 .Sh IMPLEMENTATION NOTES
-The
 .Nm
-utility should provide the correct answer in the vast majority of
-cases, including on systems kept up-to-date using
-.Xr freebsd-update 8 ,
-which does not update the kernel version unless the kernel itself was
-affected by the latest patch.
+should provide the correct answer in the vast majority of cases,
+including those where
+.Xr freebsd-update 8 
+changes the patch level of the kernel but not userland (or vice versa).
 .Pp
-To determine the name (and hence the location) of a custom kernel, the
+To determine the name (and hence the location) of a custom kernel,
 .Nm
-utility will attempt to parse
+will attempt to parse
 .Pa /boot/defaults/loader.conf
 and
 .Pa /boot/loader.conf ,
 looking for definitions of the
@@ -97,8 +100,12 @@
 .Dq kernel .
 It may however fail to locate the correct kernel if either or both of
 these variables are defined in a non-standard location, such as in
 .Pa /boot/loader.rc .
+.Pp
+Userland information is hardcoded into
+.Nm
+at build time.
 .Sh ENVIRONMENT
 .Bl -tag -width ROOT
 .It Ev ROOT
 Path to the root of the filesystem in which to look for
@@ -106,25 +113,27 @@
 and the kernel.
 .El
 .Sh EXAMPLES
-To determine the version of the currently running userland:
+Show userland information alone, without specifying option
+.Fl u :
 .Bd -literal -offset indent
-/bin/freebsd-version -u
+freebsd-version
 .Ed
 .Pp
 To inspect a system being repaired using a live system:
 .Bd -literal -offset indent
 mount -rt ufs /dev/ada0p2 /mnt
 env ROOT=/mnt /mnt/bin/freebsd-version -ku
 .Ed
 .Sh SEE ALSO
 .Xr uname 1 ,
+.Xr freebsd-update 8 ,
 .Xr loader.conf 5
 .Sh HISTORY
 The
 .Nm
-command appeared in
+utility first appeared in
 .Fx 10.0 .
 .Sh AUTHORS
 The
 .Nm
 utility and this manual page were written by