Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jeff King <peff@peff.net>]

On Sun, May 09, 2010 at 03:43:25AM -0500, Jonathan Nieder wrote:

> Thanks for bringing this up.  I think some of the changes ultimately
> ought to be propagated back to config.txt.  I copied the text anyway
> because as long as the differences are in short-term memory, I find it
> easier to manipulate two similar files than one file with ifdefs in
> it; so it seemed like a reasonable strategy to let these diverge for a
> few weeks and then merge them with ifdefs again.

Hrm. If that merge actually happens while things are still in short-term
memory. ;)

> Some divergence is needed imho so that the text can say things like
> “see the Options section earlier in this page”.

Yeah, understandable. And I also don't want to get into a rat's nest of
ifdefs in the documentation. Which is why I was pushing to move straight
into something more elegant. :)

> Longer term, I suspect I would like a gitconfig.5 page that functioned
> something like the main commands list, which could avoid some
> duplication.  But this is something to be considered carefully: right
> now it is very easy to start with knowing there is some configuration
> for what you want to change (conflict hunk format, say) and find it by
> searching the descriptions in git-config.1; if we split that file up,
> that won’t be so easy.

Yeah, I do worry about people being able to search effectively. But to
some degree, sensible naming of the options helps with that. Searching
for "conflict" even in just a list of options should come up with
"merge.conflictstyle", and I had always intended for such a gitconfig.5
to have a full list.

>   CONFIGURATION SECTIONS
>   [...]

Your breakdown looks like a sensible thing to have at the start of
gitconfig.5. It looks like you were planning on putting some generic
concepts like "alias" and "core" into that page (at the end of the
overview list), and then referring to individual command pages for their
respective sections. That sounds reasonable to me.

-Peff