Re: [PATCH 1/4] config doc: move color.ui documentation to one place

From: Jeff King <peff@peff.net>
Date: May 31, 2018, 05:25 UTC
Message-ID: <20180531052538.GB17068@sigill.intra.peff.net>
In-Reply-To: <20180530210641.19771-2-avarab@gmail.com>

On Wed, May 30, 2018 at 09:06:38PM +0000, Ævar Arnfjörð Bjarmason wrote:

Show 8 quoted lines

> Ever since b982592d66 ("git-status: document colorization config
> options", 2006-09-11) we've slowly been accumulating more and more
> color.* options, where the documentation for each new one has
> seemingly been copy/pasted with minor adjustments from the last.
> 
> This has resulted in documentation where we're describing what sort of
> values color.ui or its overriding variables can take a grand total of
> 9 times.

Yeah, I agree the current state is poor.

Show 7 quoted lines

> This makes for hard and tedious reading, and is going to be a royal
> pain if we're ever going to add more color.ui values.
> 
> Instead let's briefly describe what each variable is for, and then
> copy/paste a new boilerplate saying that this variable takes the exact
> same values as color.ui, and if it's unset it'll fallback to whatever
> color.ui is set to.

Definitely an improvement. Though I wonder if we should go further and show the user the relationship in the documentation explicitly. Like:

  color.<system>::
	A boolean to enable/disable color in a particular part of Git,
	overriding `color.ui` (see `color.ui` for possible values). The
	current set of systems is:

	advice::
		Hints shown with the "hint:" prefix, controlled by
		`advice.*` config.

	branch::
		Output from the linkgit:git-branch[1] command.

	...etc...

We could possibly do the same with color.<system>.<slot>. Or maybe even make a single hierarchical list of systems, and then the color slots under each. I think if our mental model in adding these options is to have this kind of hierarchy, then it makes sense to communicate it explicitly to the user and get them using the same mental model.

-Peff