threads / patch / 30497

patchClean weird documentation for 'git var' and 'git

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

## tl;dr

9 messages between May 10, 2012 and May 10, 2012. Diffs are folded; open one to read it.

replies: 8people: 4as markdown or json

Philippe Vaucher· May 10, 2012, 16:45 UTC · lore
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(-)
Show changes to 2 files +0 −16

Documentation/git-commit-tree.txt, Documentation/git-var.txt

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
Philippe Vaucher· May 10, 2012, 16:47 UTC · re: Philippe Vaucher · lore

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

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
Junio C Hamano· May 10, 2012, 16:55 UTC · re: Philippe Vaucher · lore

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

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.

Philip Oakley· May 10, 2012, 18:03 UTC · re: Junio C Hamano · lore

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

From: "Junio C Hamano" <gitster@pobox.com> Sent: Thursday, May 10, 2012 5:55 PM
Show 7 quoted lines
> 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
René Scharfe· May 10, 2012, 17:06 UTC · re: Philippe Vaucher · lore

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

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.

Show 5 quoted lines
>
> 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.

Show 23 quoted lines
> ---
>   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é
Philippe Vaucher· May 10, 2012, 18:26 UTC · lore

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

>> 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
Junio C Hamano· May 10, 2012, 18:41 UTC · re: Philippe Vaucher · lore

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

Philippe Vaucher <philippe.vaucher@gmail.com> writes:
Show 6 quoted lines
>>> 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(+)
Show changes to 2 files +8 −0

Documentation/git-commit-tree.txt, Documentation/git-var.txt

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!::
Philippe Vaucher· May 10, 2012, 20:14 UTC · re: Junio C Hamano · lore

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

Show 7 quoted lines
>> 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

← back to recent threads