Re: Config variables and scripting // was Re: [RFC/PATCH] log: add log.firstparent option

[Michael J Gruber <git@drmicha.warpmail.net>]

Jacob Keller venit, vidit, dixit 23.07.2015 08:55:
> On Wed, Jul 22, 2015 at 11:53 PM, Jeff King <peff@peff.net> wrote:
>> "man git" already has such a list (which is generated from the
>> annotations in command-list.txt). But I agree that it would probably be
>> helpful to point people directly from "git log" to "git rev-list" and
>> vice versa.
>>
>> -Peff
> 
> That's good. I just know that I've had many a co-worker complain
> because the man page felt too technical because they accidentally
> found their way into a plumbing section. If I heard a specific case of
> confusion again in the future I'll try to work up a patch for it.
> 
> Regards,
> Jake
> 

That reminds me of my attempt to add those "categories" to the man pages
of each command (rather than just to that of "git") so that users know
where they landed. It died off, though: I preferred just specifying the
category (maybe with a long form), others including the whole
explanation of the category (which I thought would be too much text; we
have the glossary for that).

Would something like that help? Maybe "category" plus optionally pointer
to a related command in the "other" category.

Michael