On 10/10/25 09:29, Alexander Ziaee wrote:
On 2025-10-10 09:37 -04:00 EDT, [email protected] wrote:
Alexander Ziaee wrote:
The branch main has been updated by ziaee:
URL:
https://cgit.FreeBSD.org/src/commit/?id=d8a4843cb76ec1b7da8d5defafb7eef9a6cc1c21
commit d8a4843cb76ec1b7da8d5defafb7eef9a6cc1c21
Author: Alexander Ziaee <[email protected]>
AuthorDate: 2025-10-09 14:55:14 +0000
Commit: Alexander Ziaee <[email protected]>
CommitDate: 2025-10-09 21:06:50 +0000
umass.4: Modernize driver loading instructions
+ consolidate kernel configuration in SYNOPSIS
+ explain driver autoloading in DESCRIPTION
+ s/port/interface/ because of internal USBs
+ fix flow of remaining example
MFC after: 1 day
---
share/man/man4/umass.4 | 56 +++++++++++++++++++++-----------------------------
1 file changed, 23 insertions(+), 33 deletions(-)
diff --git a/share/man/man4/umass.4 b/share/man/man4/umass.4
index db4e6f0890f2..8c6b03a3afea 100644
--- a/share/man/man4/umass.4
+++ b/share/man/man4/umass.4
@@ -25,44 +25,44 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd October 2, 2025
+.Dd October 9, 2025
.Dt UMASS 4
.Os
.Sh NAME
.Nm umass
.Nd USB Mass Storage Devices driver
.Sh SYNOPSIS
-To compile this driver into the kernel,
-place the following line in your
-kernel configuration file:
-.Bd -ragged -offset indent
+.Cd "device da"
.Cd "device scbus"
+.Cd "device pass"
.Cd "device usb"
.Cd "device umass"
-.Ed
.Pp
-Alternatively, to load the driver as a
-module at boot time, place the following line in
+In
.Xr loader.conf 5 :
-.Bd -literal -offset indent
-umass_load="YES"
-.Ed
+.Cd umass_load
This now renders as the following - expected?
In loader.conf(5):
umass_load
I checked your previous similar changes and it seems to be inconsistent,
some include ="YES" (e.g. 52eb7e394a7) and some do not.
It's been requested that we don't include the operand. Overall throughout the
manual pages using this syntax (which are many more than I've touched
actually), there is a mix. I don't think the operand helps it, and it's
difficult sometimes when the operand isn't straightforward.
Suggestions are welcome.
Also I don't think .Cd is applicable here, shouldn't it rather be .Va
(seems more appropriate) or even literal text?
From mdoc(7):
Cd line
Kernel configuration declaration.
Va [type] identifier ...
A variable name.
The line is telling the loader to load the kernel module into the kernel. Thus
it is a kernel configuration declaration. This lets people search the manual by
kernel configuration, like so:
Your interpretation doesn't line up with the rest of Cd's description:
"This denotes strings accepted by config(8)."
That's further supported by the OpenBSD-ish example. Cd here would be
something like:
.Cd device umass
Because that is the config(8) description that you would put into a kernel
config(5). What we put in loader.conf is more akin to an environment variable,
and loader itself loads the module.
Thanks,
Kyle Evans
