Re: ghost refs

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 17, 2010, 16:32 UTC
Message-ID: <7v8w8m3uqj.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20100417115111.GB28623@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 27 quoted lines

> I would also like to have consensus on this, too. But it seems like it
> gets bikeshedded to death every time it comes up.  But hey, why not try
> it one more time? :)
>
>> I'll list my preference off the top of my head as a firestarter.
>> 
>> NAME::
>> 
>> The name followed by what it is used for
>
> Yep, makes sense.
>
>> SYNOPSIS::
> ...
> As another example, for git-branch, I would suggest:
>
>   git branch [<options>]
>   git branch [<options>] <branchname> <start-point>
>   git branch -m [<oldbranch>] <newbranch>
>   git branch -d [<options>] <branchname>
>
> From that I can quickly see that there are four major modes: listing,
> creating a new branch, moving a branch, and deleting a branch. I would
> also be happy if each mode was explicitly described. Some of my favorite
> synopses are those of perl modules, which tend to give you a very short
> and readable code snippet of how you might use the module, along with
> comments showing anything non-obvious.

Yes, that makes a lot more sense than "list every possible option".

Show 28 quoted lines

>> Detailed discussion of concepts::
>> 
>> Some manual pages need to have discussion of basic concepts that would not
>> be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in
>> "checkout" manual).  I am not sure if this kind of material is better
>> given in OPTIONS section close to the functional group (e.g. "History
>> Siimplification" heading in "log" manual).
>
> I would really prefer most of this material to be pushed out into its
> own manual pages, and referred to by name (e.g., say "see
> githistory(7) for a discussion of history simplification" or "history
> is simplified as described in githistory(7)").
>
> Here's my reasoning.  [jc: good summary of possible solutions skipped] 
> ...
>   3. factor it into githistory(7), and reference it by name
>
>      Obviously this is my favorite. :) It does have one downside,
>      though. If we convert pretty-formats.txt into gitpretty(7), then
>      searching for "oneline" in git-log may not turn up what you want.
>      I wonder if we can summarize with something like:
>
>        --format=:
>        --pretty=<oneline|full|raw>:
>        --oneline:
>          Format the output. See gitpretty(7).
>
>     in git-log(1).

I like the suggested outcome.

One way of doing this is to strip the description from pretty-format.txt and move the description to gitpretty.txt (and anything that supports pretty format will continue to include pretty-format.txt).

But we will need to list _all_ the options twice if we go this route; pretty-format.txt for the heading, and the descriptions in gitpretty.txt. Perhaps pretty-format.txt can be autogenerated from gitpretty.txt to keep them in sync.

> You didn't mention configuration variables.

Yeah, I forgot.

Show 13 quoted lines

> 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.