Re: [PATCH] Clean weird documentation for 'git var' and 'git

[Junio C Hamano <gitster@pobox.com>]

Philippe Vaucher <philippe.vaucher@gmail.com> writes:

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

Ahh, that makes your initial message understandable.

It indeed is not one of the very common and established ones, and it may
help to give it a gentler introduction.

 Documentation/git-commit-tree.txt | 4 ++++
 Documentation/git-var.txt         | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index cfb9906..868ad09 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -90,6 +90,10 @@ include::date-formats.txt[]
 
 Diagnostics
 -----------
+
+Some of the common error message the command may give upon errors are
+listed here.
+
 You don't exist. Go away!::
     The passwd(5) gecos field couldn't be read
 Your parents must have hated you!::
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 988a323..394bfa7 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -61,6 +61,10 @@ endif::git-default-pager[]
 
 Diagnostics
 -----------
+
+Some of the common error message the command may give upon errors are
+listed here.
+
 You don't exist. Go away!::
     The passwd(5) gecos field couldn't be read
 Your parents must have hated you!::