# [PATCH] Clean weird documentation for 'git var' and 'git 9 messages from 2012-05-10 to 2012-05-10. Participants: Philippe Vaucher, Junio C Hamano, René Scharfe, Philip Oakley. Thread: https://gitlist.dev/t/30497 ## Philippe Vaucher, 2012-05-10 16:45 Subject: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: URL: https://gitlist.dev/e/CAGK7Mr7QWrddaRLkr%3D1h%3DGYUNtNVOatQF1sj%2Bp11mejzs65u8A%40mail.gmail.com ``` Here's a patch removing the weird bits. I spoke about in my previous message. Philippe Signed-off-by: Philippe Vaucher --- 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 ``` ## Philippe Vaucher, 2012-05-10 16:47 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: URL: https://gitlist.dev/e/CAGK7Mr7WQFmf1S5ed%2B1Cu9gRQ-ZgO-t%2Bdj7a8PKRM%3DU2ZVERyQ%40mail.gmail.com In-Reply-To: ``` 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, 2012-05-10 16:55 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: <7vzk9gm0wa.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vzk9gm0wa.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Philippe Vaucher 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. ``` ## René Scharfe, 2012-05-10 17:06 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: <4FABF5A2.1050200@lsrfire.ath.cx> URL: https://gitlist.dev/e/4FABF5A2.1050200%40lsrfire.ath.cx In-Reply-To: ``` 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 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é ``` ## Philip Oakley, 2012-05-10 18:03 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: URL: https://gitlist.dev/e/F89882854A7D45E2843F6F1F7CB21DB4%40PhilipOakley In-Reply-To: <7vzk9gm0wa.fsf@alter.siamese.dyndns.org> ``` From: "Junio C Hamano" Sent: Thursday, May 10, 2012 5:55 PM > Philippe Vaucher 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 ``` ## Philippe Vaucher, 2012-05-10 18:26 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: URL: https://gitlist.dev/e/CAGK7Mr7rzuPVmGsnx%2BuhmVgBepAav734uh6hHeqn25BC0_%2B0Lw%40mail.gmail.com 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 ``` ## Junio C Hamano, 2012-05-10 18:41 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: <7vvck3najc.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vvck3najc.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Philippe Vaucher 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!:: ``` ## Philippe Vaucher, 2012-05-10 20:14 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: URL: https://gitlist.dev/e/CAGK7Mr4GJw4zZ5Qwab%2Bco07JG5kBn-EFsfmU%2BYzpm6LoD8j-Rw%40mail.gmail.com In-Reply-To: <7vvck3najc.fsf@alter.siamese.dyndns.org> ``` >> 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 ``` ## Philippe Vaucher, 2012-05-10 20:15 Subject: Re: [PATCH] Clean weird documentation for 'git var' and 'git Message-ID: URL: https://gitlist.dev/e/CAGK7Mr46-btS3gZvw4UUeiZEFn6cxH%2BBuYV02heWSbLbavpwvA%40mail.gmail.com In-Reply-To: ``` Oh, I see there's already a patch for it :) Nice! Philippe ```