Re: [PATCH 00/34] doc/UX: make txt & -h output more consistent

From: Victoria Dye <vdye@github.com>
Date: Sep 20, 2022, 00:57 UTC
Message-ID: <07b35632-8e3c-fea1-0996-fb2e88ea6ba8@github.com>
In-Reply-To: <af319ab4-2351-2d74-e0c7-6153f229d88c@github.com>

Victoria Dye wrote:

Show 37 quoted lines

> If I could offer a suggestion, my preference would be that you split the
> series into three parts: one with the straightforward, easier-to-review
> changes, another with the more substantial updates to user-facing
> docs/information (which might warrant more discussion, i.e. which options we
> should be showing for a command in the SYNOPSIS/-h), and the last catching
> any new inconsistencies & adding the test. That way, more involved
> discussion on some patches doesn't prevent *all* of them from being merged.
> 
> I think the following patches would fit a "straightforward,
> easier-to-review" series:
> 
> * Patch 1 (CodingGuidelines: update and clarify command-line conventions)
> * Patch 2 (builtin/bundle.c: use \t, not fix indentation 2-SP indentation)
> * Patch 3 (bundle: define subcommand -h in terms of command -h)
> * Patch 5 (doc SYNOPSIS: don't use ' for subcommands)
> * Patch 6 (doc SYNOPSIS: consistently use ' for commands)
> * Patch 7 (doc SYNOPSIS & -h: fix incorrect alternates syntax)
> * Patch 8 (built-ins: consistently add "\n" between "usage" and options)
> * Patch 9 (doc txt & -h consistency: word-wrap)
> * Patch 10 (doc txt & -h consistency: fix incorrect alternates syntax)
> * Patch 12 (doc txt & -h consistency: add missing "]" to bugreport "-h")
> * Patch 13 (doc txt & -h consistency: correct padding around "[]()")
> * Patch 14 (stash doc SYNOPSIS & -h: correct padding around "[]()")
> * Patch 15 (doc txt & -h consistency: use "<options>", not "<options>...")
> * Patch 16 (t/helper/test-proc-receive.c: use "<options>", not
>   "<options>...")
> * Patch 17 (doc txt & -h consistency: fix mismatching labels)
> * Patch 18 (doc txt & -h consistency: add or fix optional "--" syntax)
> 
> (basically, 1-18, skipping patch 4 because it changes the content of an
> error message & patch 11 because it adds an option to the -h of 'cat-file')
> 
> In terms of review, my only comment on those patches is that 7 & 10 could
> probably benefit from being squashed together [1]. Otherwise, with the
> changes you mentioned in response to Junio's feedback [2], I think that
> subset of the series would be ready to merge.
>

I forgot to mention this in the previous message, but it's probably worth noting - regardless of whether or not you split the series, I am still planning to review the remaining patches you've submitted here (that is, everything *other than* what's in the list above, which I've already looked over/commented on). I likely won't get the chance until later this week at the earliest, though.

Thanks! -Victoria