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

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