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

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