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

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

[Philippe Vaucher]

Here's a patch removing the weird bits. I spoke about in my previous message.

Philippe


Signed-off-by: Philippe Vaucher <philippe.vaucher@gmail.com>
---
 Documentation/git-commit-tree.txt |    9 ---------
 Documentation/git-var.txt         |    9 ---------
 2 files changed, 18 deletions(-)

diff --git a/Documentation/git-commit-tree.txt
b/Documentation/git-commit-tree.txt
index cfb9906..eb8ee99 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -88,15 +88,6 @@ for one to be entered and terminated with ^D.

 include::date-formats.txt[]

-Diagnostics
------------
-You don't exist. Go away!::
-    The passwd(5) gecos field couldn't be read
-Your parents must have hated you!::
-    The passwd(5) gecos field is longer than a giant static buffer.
-Your sysadmin must hate you!::
-    The passwd(5) name field is longer than a giant static buffer.
-
 Discussion
 ----------

diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 988a323..67edf58 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -59,15 +59,6 @@ ifdef::git-default-pager[]
     The build you are using chose '{git-default-pager}' as the default.
 endif::git-default-pager[]

-Diagnostics
------------
-You don't exist. Go away!::
-    The passwd(5) gecos field couldn't be read
-Your parents must have hated you!::
-    The passwd(5) gecos field is longer than a giant static buffer.
-Your sysadmin must hate you!::
-    The passwd(5) name field is longer than a giant static buffer.
-
 SEE ALSO
 --------
 linkgit:git-commit-tree[1]
-- 
1.7.9.5

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

[Philippe Vaucher]

I see I messed up the commit message which is too long. You can change
it to something like "Clean documentation (git-var/git-commit-tree)"
if you decide to import the patch.

Philippe

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

[Junio C Hamano]

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

> Here's a patch removing the weird bits. I spoke about in my previous message.

What's weird about them?  They are real messages issued exactly when they
are described to be issued.

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com> Sent: Thursday, May 10, 2012 5:55 PM
> Philippe Vaucher <philippe.vaucher@gmail.com> writes:
>
>> Here's a patch removing the weird bits. I spoke about in my previous message.
>
> What's weird about them?  They are real messages issued exactly when they
> are described to be issued.
> --

Philippe,

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

Philip 

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

[Philippe Vaucher]

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

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

[Junio C Hamano]

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!::

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

[Philippe Vaucher]

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

Yes that's much better. Thanks!

I think in the long term those error messages should be more
descriptive. For example "Your parents must have hated you" should be
"Your name is too long, maximum %d characters allowed" or whatever.

Philippe

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

[Philippe Vaucher]

Oh, I see there's already a patch for it :) Nice!

Philippe

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

[René Scharfe]

Am 10.05.2012 18:45, schrieb Philippe Vaucher:
> Here's a patch removing the weird bits. I spoke about in my previous message.

Ideally, a commit message should be self-contained and explain the 
reasons for the introduced changes, or at least contain a link to a 
mailing list archive, so that readers who only have the git repository 
have a chance to follow the arguments.

>
> Philippe
>
>
> Signed-off-by: Philippe Vaucher<philippe.vaucher@gmail.com>

The author field of a commit plus the sign-off line are enough to 
identify you, no extra line with your name required.

> ---
>   Documentation/git-commit-tree.txt |    9 ---------
>   Documentation/git-var.txt         |    9 ---------
>   2 files changed, 18 deletions(-)
>
> diff --git a/Documentation/git-commit-tree.txt
> b/Documentation/git-commit-tree.txt
> index cfb9906..eb8ee99 100644
> --- a/Documentation/git-commit-tree.txt
> +++ b/Documentation/git-commit-tree.txt
> @@ -88,15 +88,6 @@ for one to be entered and terminated with ^D.
>
>   include::date-formats.txt[]
>
> -Diagnostics
> ------------
> -You don't exist. Go away!::
> -    The passwd(5) gecos field couldn't be read
> -Your parents must have hated you!::
> -    The passwd(5) gecos field is longer than a giant static buffer.
> -Your sysadmin must hate you!::
> -    The passwd(5) name field is longer than a giant static buffer.
> -

These are actual error messages and their meanings, e.g. git prints "You 
don't exist. Go away!" in case the gecos field of your account in 
/etc/passwd (or NIS, or LDAP) couldn't be read.

René