From: Philippe Vaucher Date: Thu, 10 May 2012 18:26:21 GMT Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: In-Reply-To: >> What's weird about them?  They are real messages issued exactly when they are described to be issued. > > The problem is surely that an explanatory line is needed to say that these are the diagnostic messages that occur in various cases. Its in 'ident.c'. I guess I'm just unfamiliar with the "Diagnostics" section of a man page. When I fall on this there's nothing I learn... all the other sections are helpful and providing self explanatory informations. In this case (diagnostic section), the first thing I see is "You don't exist, Go away!", and I'm like "okay..." then I see something about the passwd file (what on earth has git-commit-tree in common with passwd?) then I see "Your parents must have hated you!" and there I'm like "okay, there's definitly something wrong with this man page". I'm probably not the only one confused by this. I think a simple line "This tool might report the following error messages" would already be a great step forward. The next step would be to improve those error messages :) Philippe