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

Jari Aalto [off-list ref] 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.

quoted

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.