From: Stefan Beller <sbeller@google.com>
Date: Tue, 02 Aug 2016 22:02:00 GMT
Subject: Re: [PATCH 1/2] submodule documentation: add options to the subcommand
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:
> 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.

>
>> 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