Subject: Re: [PATCH 07/34] doc SYNOPSIS & -h: fix incorrect alternates syntax

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Mon, 26 Sep 2022 13:28:49 +0200

On Mon, Sep 19 2022, Victoria Dye wrote:

> Ævar Arnfjörð Bjarmason wrote:
>> Fix the incorrect "[-o | --option <argument>]" syntax, which should be
>> "[(-o | --option) <argument>]", we were previously claiming that only
>> the long option accepted the "<argument>", which isn't what we meant.
>> 
>> Unlike a preceding commit where this was fixed for commands which had
>
> nit: if you're referring to patch 10 [1], it wouldn't be a "preceding"
> commit. Otherwise, I'm not sure which commit you're referring to?

Thanks, yes this is incorrect. It's due to rebasing/reordering this &
missing this mention.

> In any case, I'd personally prefer that this patch is combined with patch 10
> anyway, since both fix the same underlying issue (just in different places).
> Neither patch is particularly large, and it would be nice to make (and
> review!) all of the "fix alternates syntax" changes at once.

Yes, it's the same issue, but I think I'll keep them split up (working
on a re-roll).

The reason is (as mentioned in the CL) to cleanly split up the
"consistency" changes from the rest.

I.e. in this one we need to change both *.c and *.txt versions, so it's
a "new" change, i.e. reviewers need to do more work to eyeball & review
a version that's never used that form in-tree.

Whereas the "consistency" commits are ones where we *only* change one of
*.c or *.txt, to make it consistent with the other existing and
corresponding form.

That still requires review to see which version should "win", but with
34/34 (where we test all of those at the end) doesn't require the
reviewer to consider whether the change is sensible at all (if it
doesn't make sense we already have that version in 1/2 places in-tree
already).