From: Jeff King <peff@peff.net>
Date: Sun, 30 Aug 2009 21:02:31 GMT
Subject: Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms
Message-ID: <20090830210231.GA4471@coredump.intra.peff.net>
In-Reply-To: <7vab1hdppb.fsf@alter.siamese.dyndns.org>

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

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