From: Tim Henigan <tim.henigan@gmail.com>
Date: Tue, 13 Mar 2012 20:36:48 GMT
Subject: Re: [PATCH 2/2] Documentation/diff-options: reword description of --submodule option
Message-ID: <CAFouetgSw7MMzHWOJox6DiPmBWD=6j4mST1KFZYsZyLmKHRrEQ@mail.gmail.com>
In-Reply-To: <7vipi8uv12.fsf@alter.siamese.dyndns.org>

>>  --submodule[=<format>]::
>> -     Choose the output format for submodule differences. <format> can be one of
>> -     'short' and 'log'. 'short' just shows pairs of commit names, this format
>> -     is used when this option is not given. 'log' is the default value for this
>> -     option and lists the commits in that commit range like the 'summary'
>> -     option of linkgit:git-submodule[1] does.
>> +     Choose the output format for submodule differences. <format> can be one
>> +     of 'short' or 'log'. The default value is 'log'.
>> +     'log' lists commits in the commit range like linkgit:git-submodule[1] `--summary`.
>> +     'short' shows only the SHA1 of the source and destination.
>
> Does it risk being unclear to say src/dst here without defining, or is it
> sufficiently clear from the context (the previous line says "range")?

I chose those words based on descriptions in some of the other diff
options (see `changes` and --src-prefix in the same file.  That being
said, the description you gave is more clear.


> You lost "not giving this option at all is the same as --submodule=short".

I removed that part on purpose.  I wasn't sure that it needs to be
documented here since it is about how the 'diff' command normally
behaves rather than about the '--submodule' option itself.


> Here is my attempt, but I do not think I particularly did a good job at
> this.
>
>        Specify how differences in submodules are shown.  A `--submodule`
>        or `--submodule=log` option uses the long format, which lists the
>        commits in the range like linkgit:git-submodule[1] `--summary` does.
>        Omitting the `--submodule` option, or a `--submodule=short` option,
>        uses the short format, which just shows the names of the commits
>        at the beginning and the end of the range.

Some further minor changes to your version:

    Specify how differences in submodules are shown.  When `--submodule`
    or `--submodule=log` is given, the 'log' format is used.  This format lists
    the commits in the range like linkgit:git-submodule[1] `--summary` does.
    Omitting the `--submodule` option or specifying `--submodule=short`,
    uses the 'short' format. This format just shows the names of the commits
    at the beginning and end of the range.