Subject: Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels

From: Junio C Hamano <[email-masked]>
Date: Sat, 01 Oct 2022 21:52:04 -0700

Junio C Hamano <[email-masked]> writes:

> Instead of going over the patches in the rest of the series, I think
> we'd probably need to step back a bit and give ourselves a general
> guideline.  

Having said that, I am a bit torn on the next step.

The updates done in this series stops way short to make the usage
strings conform to the proposed guideline.  We could include such
changes to make them conform, but that would make the series that is
already long even longer, which is not what I want to see.

My preference is to go in the other direction, i.e. make NO attempt
to improve usage strings in this series, the only change we will
make would be, except for documenting the coding guideline and
adding tests that ensure usage strings in the code and in the
document match for majority of commands, are to make sure the code
and the doc match (IOW, if an existing option is not described in
either, we leave it to a later round to add it, as long as the code
and the doc consistently fail to describe it).  That may allow us to
make this series shorter than it currently is, hopefully?  I dunno.

And a fix to the proposed guideline.

>  * The usage string for a command with a large number of options can
>    and should use "[<options>]" placeholder in the SYNOPSIS and
>    "usage:" lines, i.e. "git cmd [<options>]", and let the
>    DESCRIPTION section (in documentation) and the option listing (in
>    the output from usage_with_options() function).

"... list and explain them" is missing from the end.