Re: git: d8a4843cb76e - main - umass.4: Modernize driver loading instructions

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 <ziaee@FreeBSD.org>
> AuthorDate: 2025-10-09 14:55:14 +0000
> Commit:     Alexander Ziaee <ziaee@FreeBSD.org>
> 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.

Also I don't think .Cd is applicable here, shouldn't it rather be .Va
(seems more appropriate) or even literal text?

>  .Sh DESCRIPTION
>  The
>  .Nm
>  driver provides support for Mass Storage devices that attach to the USB
> -port.
> +interface.
>  .Pp
> -To use the
> -.Nm
> -driver,
> +If the appropriate hardware is detected,
> +the driver will be loaded automatically by
> +.Xr devmatch 8 .
> +To load the driver manually at boot time, use the
> +.Cm umass_load
> +command at the
> +.Xr loader 8
> +prompt, or add it to
> +.Xr loader.conf 5 .
> +.Pp
> +To use the driver in a custom kernel,
>  .Xr usb 4
> -and one of
> -.Xr uhci 4
> -or
> -.Xr ohci 4
> -or
> -.Xr ehci 4
> +and at least one of
> +.Xr uhci 4 ,
> +.Xr ohci 4 ,
> +.Xr ehci 4 ,
>  or
>  .Xr xhci 4
>  must be configured in the kernel.
> @@ -88,16 +88,8 @@ USB hard disk drives
>  USB floppy drives
>  .El
>  .Sh EXAMPLES
> -.Bd -literal -offset indent
> -device umass
> -device scbus
> -device da
> -device pass
> -.Ed
> -.Pp
> -Add the
> -.Nm
> -driver to the kernel.
> +Rescan all slots on a multi-slot flash reader,
> +where the slots map to separate LUNs on a single SCSI ID:
>  .Bd -literal -offset indent
>  camcontrol rescan 0:0:0
>  camcontrol rescan 0:0:1
> @@ -105,8 +97,6 @@ camcontrol rescan 0:0:2
>  camcontrol rescan 0:0:3
>  .Ed
>  .Pp
> -Rescan all slots on a multi-slot flash reader, where the slots map to separate
> -LUNs on a single SCSI ID.
>  Typically only the first slot will be enabled at boot time.
>  This assumes that
>  the flash reader is the first SCSI bus in the system and has 4 slots.
>