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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Thu, May 31 2018, Jeff King wrote:

> On Wed, May 30, 2018 at 09:06:38PM +0000, Ævar Arnfjörð Bjarmason wrote:
>
>> 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.
>
>> 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.

I wouldn't be opposed to some twist on that, but I really dislike the
variables that are documented in such a way that you can't find them in
the documentation by searching for their fully qualified name.