Re: Git documentation writing guidelines

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 18, 2010, 00:28 UTC
Message-ID: <7vtyr9y578.fsf@alter.siamese.dyndns.org>
In-Reply-To: <m3mxx2dnlu.fsf_-_@localhost.localdomain>

Jakub Narebski <jnareb@gmail.com> writes:

Show 25 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Jeff King <peff@peff.net> writes:
>
>> > git-config (or perhaps even gitconfig(7)) should have a list of all
>> > variables and where they are described, like:
>> >
>> >   apply.ignorewhitespace        git-apply(1)
>> >   apply.whitespace              git-apply(1)
>> >   branch.autosetupmerge         git-branch(1)
>> >   [etc]
>> >
>> > There is not much point in having full descriptions in one giant list.
>> > Instead, you can peruse the whole list, and then go to the configuration
>> > section of the relevant manpage to see a bunch of related options. Such
>> > a list should be pretty easy to generate automatically from the other
>> > documentation.
>> 
>> Yes, I like it.
>
> Well, there are some variables, like advice.*, or core.*, or alias.*, or
> color.*, or browser.<tool>.path, or i18n.*, or interactive.singlekey,
> or notes.*, or user.* that do not really belong to single git command
> (well, perhaps they could be put in git(1) manpage), or belong to more
> than one command.

So?

Naturally they will be listed like:

    alias.*		git(1)
    color.diff.*	git-diff(1)
    browser.*.path      git(1)
    ...

and I don't see a problem in the general structure Jeff suggested.