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

Signed-off-by: Jari Aalto <redacted>
---
 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.
 
 -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.
 
 -e, \--edit::
 	Open the diff vs. the index in an editor and let the user

-- 
1.6.3.3

Jari Aalto [off-list ref] writes:

Sorry, the change in this hunk does not make *any* sense to me.

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.

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

If you assume that the reader is not familiar with "add -i", then the
above is not descriptive enough, but "Run interactive patch command" is
not an improvement either.  We would need a description of "what it is
used for" before "how it would look to you" (i.e.. my rewrite shown
above).

"What it is used for" would perhaps read like this.

	Review the difference between the index and the work tree, and add
	modified contents to the index interactively by choosing which
	patch hunks to use.

On Sun, Aug 30, 2009 at 01:14:24PM -0700, Junio C Hamano wrote:

quoted

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

Sorry, the change in this hunk does not make *any* sense to me.

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.

I think it is an attempt to match the way docbook renders manpage
headings; it converts headings to all-caps. And there is some precedent;
try grepping for ".EXAMPLES" in Documentation/*.txt.

That being said, the straight asciidoc->html version leaves the
capitalization untouched. However, that actually makes the html version
look quite awkward. Some of the headings are in all-caps and some are
not. So I wonder if we should make them typographically consistent.

(And yes, I totally agree that this hunk was a surprise after reading
the commit message and if anything is done, it should be in a separate
patch).

-Peff