Jeff King <peff@peff.net> writes:
quoted text > 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".
quoted text >> 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.
quoted text > You didn't mention configuration variables.
Yeah, I forgot.
quoted text > 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
majordomo@vger.kernel.org
More majordomo info at
http://vger.kernel.org/majordomo-info.html
