Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto <jari.aalto@cante.net>]

Junio C Hamano <gitster@pobox.com> writes:

> Jari Aalto <jari.aalto@cante.net> writes:
>
>> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
>> ---
>>  Documentation/git-add.txt |   10 +++++-----
>>  1 files changed, 5 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
>> index e67b7e8..71990c2 100644
>> --- a/Documentation/git-add.txt
>> +++ b/Documentation/git-add.txt
>> @@ -67,14 +67,14 @@ OPTIONS
>>  --interactive::
>>  	Add modified contents in the working tree interactively to
>>  	the index. Optional path arguments may be supplied to limit
>> -	operation to a subset of the working tree. See ``Interactive
>> -	mode'' for details.
>> +	operation to a subset of the working tree. See section
>> +	``INTERACTIVE MODE'' for details.
>
> It is not justified with your commit log message, I do not see why you
> have to shout in all CAPS, and there is no such section in the
> documentation.  But the "Interactive mode" section exists and is referred
> to by the original.

It is not shouting, but standard practise to refer to manual page
section in ALL CAPS, when they are top level headings, like in this
case.

>>  -p::
>>  --patch::
>> -	Similar to Interactive mode but the initial command loop is
>> -	bypassed and the 'patch' subcommand is invoked using each of
>> -	the specified filepatterns before exiting.
>> +	Run interactive patch command for each file on command line.
>> +	See section INTERACTIVE MODE and patch subcommand for more
>> +	information.
>
> I personally think fixing misworded phrase "initial command loop" would be
> sufficient.  It should read "initial command menu".  Perhaps like this.
>
> 	Run ``add --interactive``, but bypass the initial command menu and
> 	directly jump to `patch` subcommand.  See ``Interactive mode'' for
> 	details.

It's still too technical. The 1st line should go right into business:

 	Patch each file on command line interactively. This is this is
 	the same as ``add --interactive``, but bypass the initial
 	command menu and directly jump to `patch` subcommand. See
 	``Interactive mode'' for details.

Jari