Re: [PATCH 1/4] config doc: move color.ui documentation to one place
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.:: > > 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... 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
Re: [PATCH 1/4] config doc: move color.ui documentation to one place
On Thu, May 31 2018, Jeff King wrote:
> On Wed, May 30, 2018 at 09:06:38PM +, Æ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.::
> 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... 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.
Re: [PATCH 1/4] config doc: move color.ui documentation to one place
On Wed, May 30, 2018 at 09:06:38PM +, Æ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.::
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... 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
