hi. the text reads fine, and seems clearer. also i prefer your version to the "in-synch" text. ok.

jmc

On 2 May 2025 10:28:47 BST, Stuart Henderson <stu@spacehopper.org> wrote:
>On 2025/05/01 21:56, Josh Grosse wrote:
>> For consideration.
>
>> diff --git usr.sbin/pkg_add/pkg_add.1 usr.sbin/pkg_add/pkg_add.1
>> index 67be4b80179..17b3fc12687 100644
>> --- usr.sbin/pkg_add/pkg_add.1
>> +++ usr.sbin/pkg_add/pkg_add.1
>> @@ -109,7 +109,9 @@ with
>>  .Fl u
>>  whenever possible, but
>>  .Fl U
>> -can be much faster.
>> +can be much faster, and is intended for use when running -current, if
>> +a new package needs to be added without conducting a full update of all
>> +packages.
>>  .It
>>  Replace existing packages with explicit other versions, using option
>>  .Fl r .
>
>-U is a bit of a hack and I think mostly useful for ports developers.
>
>Diff below gives a better reason *not* to use it.
>
>Perhaps pkg_add should reject -Uu, afaict it is meaningless, and there
>is some meme which won't go away about running -Uu for updates.
>
>Bonus -u -> .Fl u fix.
>
>Index: pkg_add.1
>===================================================================
>RCS file: /cvs/src/usr.sbin/pkg_add/pkg_add.1,v
>diff -u -p -r1.168 pkg_add.1
>--- pkg_add.1	2 Oct 2024 09:14:08 -0000	1.168
>+++ pkg_add.1	2 May 2025 09:24:00 -0000
>@@ -104,12 +104,14 @@ The
> .Ar pkg-name ...
> specified on the command line are new packages that may require updating
> dependencies first.
>-It is recommended to keep all packages in-synch
>+It is recommended to update all packages
> with
> .Fl u
>-whenever possible, but
>+before installing a new package, but
> .Fl U
>-can be much faster.
>+can be much faster (at the risk of possibly leaving an inconsistent
>+set of packages).
>+Mainly for use with -current snapshots.
> .It
> Replace existing packages with explicit other versions, using option
> .Fl r .
>@@ -685,7 +687,9 @@ Dependencies from the old packages are a
> package.
> .El
> .Pp
>-To update packages in -u mode,
>+To update packages in
>+.Fl u
>+mode,
> .Nm
> performs the following steps.
> .Bl -enum
>