Re: [PATCH 1/2] submodule documentation: add options to the subcommand

From: Stefan Beller <sbeller@google.com>
Date: Aug 2, 2016, 22:02 UTC
Message-ID: <CAGZ79kYChcixXtOc2HigHCY7S5bteO1QZau+4cqQYbxtHW3wDA@mail.gmail.com>
In-Reply-To: <xmqqtwf2c0aw.fsf@gitster.mtv.corp.google.com>

On Tue, Aug 2, 2016 at 2:45 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 5 quoted lines

> Stefan Beller <sbeller@google.com> writes:
>
>> When reading up on a subcommand of `gi submodule`, it is convenient
>
> s/gi /git /;

will fix.

And in the neighboring thread you just pointed out you used to just correct spelling fixes like this. I think it really depends on the workflow of the contributor. As I do the interdiff of the next version of the series against your tree I'll be likely to notice such typos in the content, but not in commit messages.

Show 15 quoted lines

>
>> to have its options nearby and not just at the top of the man page.
>> Add the options to each subcommand.
>>
>> While at it, also document the `--checkout` option for `update`.
>
> I do find the resulting per-subcommand description easier to read
> with this change.
>
> Perhaps we want to go one step further and change the SYNOPSIS so
> that per-subcommand options are not described there at all?
> I.e.e.g.
>
> -    'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]...
> +    'git submodule' [--quiet] update [<option>...]

will do.

My original intention was to get rid of the duplicates in the OPTIONS section, where each option has

    This option is only valid for <subcommand> and <subcommand>

in its description. So I looked at the `stash` man page, which has the options listed with the subcommands (and also has [<options>] in the SYNOPSIS but also some of the options as well).

I think only the long option lists (i.e. those that are more than one line) will be collapsed. The short options are ok, specifically when you just want to know e.g. if foreach supports the recursive option. Then you can open the man page and have no need to scroll down to the foreach command.

Thanks, Stefan