Junio C Hamano schrieb am 09.12.2014 um 21:26: > Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> writes: > >> Rather than changing git-foo.txt, we could do the substitution magic >> from Documentation/Makefile, of course, to keep man pages and command-list >> in sync. Although this would keep me from submitting the final series >> with 1 patch per file :) > > I do not get that smiley. Are you saying that these noisy patches > add to your karma points? Well, I didn't and I won't send them as 1p/f. Have I ever split my patches noisilly atomically? >> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt >> index 9631526..b6a8bc6 100644 >> --- a/Documentation/git-add.txt >> +++ b/Documentation/git-add.txt >> @@ -13,6 +13,10 @@ SYNOPSIS >> [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] >> [--] [<pathspec>...] >> >> +CATEGORY >> +-------- >> +Main user interface command (porcelain) >> + >> DESCRIPTION >> ----------- > > While I do not have objection to adding this information, I have > a few problems with the execution: > > - These four lines at the very beginning is a precious real > estate. The new reader would not benefit from the distinction > before reading the first paragraph of description to learn what > it does and what it is for anyway. Move it much later, perhaps > at the end. Then we can just leave it out. The aim is to give new(er) users some orientation about which commands to use and which to stay away from, unless they want to do scripting. There's no point in putting a stop sign at the end of the road. This series was triggered by the recent update-index discussion. I think it showed: Sometimes users get confused by the plumbing man pages who shouldn't even read them at all (and rather stick with porcelain commands). > - A phrase "Main user interface command" to a new user does not > help very much if it does not tell enough what that phrase really > means (e.g. you should not be using it for scripting). Extend > the description more, after moving it to the end. I'm all open for different wording, this is just a POC. Even though I think that it should be okay to use a term like porcelain (defined in the glossary) the same way as we use other central terms (revision, object) which we don't spell out in each man page. The point is to give some direction. > - As you said, this should be done in a way to keep the two sources > of information in sync. Either add these from command-list, or > generate command-list from these. Does the categorisation change a lot? My impression is that this is a one-time business like adding a new command, which causes redundant work already. If we really want to automate it, Doc/Makefile would probably need to translate foo.txt to foo.txt+ and operate on that. I'm not sure automatisation is worth that effort. Michael -- 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