Re: push.default documented in "man git-push"?

Jeff King [off-list ref] writes:

On Wed, Oct 03, 2012 at 11:26:55AM -0700, Junio C Hamano wrote:

quoted

Please do not label the list as "These variables affect this
command" to give a false impression that it is the complete list if
it isn't.

Unless somebody promises to keep an up-to-date complete list there
(or even better, come up with a mechanism to help us keep that
promise automatically, perhaps by annotating pieces with structured
comments in config.txt and automatically appending such a section to
manual pages of relevant commands), that is.

With a weaker phrase, e.g. "These configuration variables may be of
interest", such a list may not hurt readers, but personally I do not
think it adds much value to have a list of variables without even a
single line description of what each is used for.

We talked a while ago about actually moving the config options into the
individual manpages, and generating config.txt to simply contain an
index of keys and where their definitions may be found. That also has
the "list without description" characteristic. But presumably you would
be looking for keys in the manual of the command you want to affect, and
the master list would mostly be for redirecting you to the right
manpage.

That cuts both ways for configuration variables that affects or are
affected by multiple commands, and that would range from the trivial
example of configuration variables for fetch and merge that appear
to take effect in "git pull" from the end users' perspective, to the
more complex ones like remotes.*.merge and remotes.*.url that are
set to make the @{upstream} notation work.

It does break down a little when you have keys that could go in multiple
pages. In many cases, this can be solved by a canonical location that
describes the shared concepts. For example, `diff.*` should probably go
into a `gitdiff(7)` that talks about the various diff options and
formats.

Of course, that only works if you think pulling out the shared diff bits
from git-diff*, git-log, etc into a separate manpage is a good idea. I
do, because I think it makes it more clear to the reader how the
concepts connect (as opposed to simply including shared bits inline in
the manpages, as we do now, with no indication that the same content is
going to apply in many places). But it does have a downside that
individual manpages are not as easily searchable via the pager, as you
may have to follow a cross-reference to find what you want.

I suspect that approach would make individual manual pages less
approacheable by new people, as they will have more required
reading.

git(1) currently guides people to user manual, and then points at
individual pages, assuming that these shared concepts (e.g. the one
for "diff" you discuss in the above paragraph) are fully mastered
once the user manual is read.  Perhaps we would need to replace it
with a "concepts" manual, or enhance it with more "concepts"
material?