From: Andrew Hewus Fresh <andrew@afresh1.com>
Subject: Re: Make fw_update -a mean all available firmware
To: tech@openbsd.org
Date: Sat, 12 Oct 2024 12:32:04 -0700

On Thu, Oct 10, 2024 at 07:18:17AM +0100, Jason McIntyre wrote:
> hi.
> 
> being picky, you probably want neither/nor rather than neither/or.
> 
> you could reword it: fw_update does blah, unless...
> 
> however i hate how we tie ourselves in knots trying to cover corner
> cases, when usually things seem fairly obvious. for example, if you
> specify "fw_upgrade <driver>", you would hardly expect it to "try to
> determine which firmware is needed on the system". but we say it!
> 
> could we just simplify it to:

The way it reads with the reset of the DESCRIPTION throws me.

    The fw_update utility installs, updates, or deletes firmware
    packages for driver from the Internet.

> 	By default, fw_upgrade tries to determine which firmware is
> 	needed on the system.


I've been thinking about this and I don't think this is quite right, my
brain stumbles over the wording.  It's hard to find something better
though.


Maybe more like:

    Without -a or any driver specified, fw_upgrade tries to determine
    which firmware is needed on the system.

Or:

 	By default, fw_upgrade tries to determine which drivers on the
    system need firmware.

Or even:

 	By default, fw_upgrade tries to determine which firmware packages
    are needed.
 

> then expect people to know if they run it with options or arguments it
> will work differently to the default?

I think that makes sense.

 
> (it is fair game to document conflicts/extensions within option
> descriptions, not trying to suggest otherwise)