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

[Junio C Hamano <gitster@pobox.com>]

Jari Aalto <jari.aalto@cante.net> writes:

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

Why are you making excuses, ignoring the fact that you didn't have a
matching update to make the section also in caps in the patch?

Sections that are common in all manual pages (e.g. NAME, SYNOPSIS,
DESCRIPTION, EXAMPLES, SEE ALSO) are often spelled in and referred to in
caps.  You do not have to explain that to me ;-)

If you wanted to add "Interactive mode" to that set of "common sections"
and spell it in caps, do so consistently.

See http://www.kernel.org/pub/software/scm/git/docs/git-add.html#_interactive_mode
for what I mean.

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

Even if we ignore the double "this is this is", I do not think it is
better than the original.

What does "Patch each file" mean?  When read naively (and that is the
whole point of your "too technical" comment), a reader would expect there
will be changes made _to_ the work tree files.

If you want to start the description with "What it does/what it is used
for", I think it is a good idea.  I already made a suggestion for such an
improvement in my message you are responding to.

If you want to make a counterproposal, at least please do that with a
counter-proposal that is better.