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

[Jeff King <peff@peff.net>]

On Thu, May 31, 2018 at 09:09:58AM +0200, Ævar Arnfjörð Bjarmason wrote:

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

Yeah, good point. We could probably write "color.advice", etc, in the
second level list. It's redundant, but more explicit. And we still
benefit from the grouping.

-Peff