Jeff King <peff@xxxxxxxx> writes: > 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". >> 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. > 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html