Re: [PATCH v2] doc: camelCase the config variables to improve readability

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 24, 2017, 00:28 UTC
Message-ID: <xmqqmv5lhre2.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170923045617.3782-1-kaarticsivaraam91196@gmail.com>

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

Show 8 quoted lines

> A few configuration variable names of Git are composite words. References
> to such variables in manpages are hard to read because they use all-lowercase
> names, without indicating where each word ends and begins.
>
> Improve its readability by using camelCase instead.  Git treats these
> names case-insensitively so this does not affect functionality. This
> also ensures consistency with other parts of the docs that use camelCase
> fo refer to configuration variable names.

s/fo/to/ (or s/fo/in order to/)?

I think the one I have on 'pu' uses Jonathan's suggested rewrite of the log message verbatim, and I suspect that it is already clear enough, even though I admit that I stuttered a bit while reading its first sentence.

I'd avoid "A few" above, as it is my impression that we use multi-word names quite a bit, not just a few.

Perhaps

	References to multi-word configuration variable names in our
	documentation must consistently use camelCase to highlight
	where the word boundaries are, even though these are treated
	case insensitively.

	Fix a few places that spell them in all lowercase, which
	makes them harder to read.

may be a more succinct way to say the same thing. We state the rule upfront, explain what the rule is for, and tell the codebase to apply the rule. That should cover everything your version and Jonathan's version wanted to convey, I'd think.