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

On 10/10/25 09:29, Alexander Ziaee wrote:
> 
> On 2025-10-10 09:37 -04:00 EDT, cyric@mm.st 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 <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.
> 
> 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