{"thread":{"id":"25037","subject":"Errors in man git","startedAt":"2010-09-08T14:36:53Z","lastAt":"2010-09-09T00:48:31Z","messageCount":5,"participants":["Daniel U. Thibault","Jan Krüger","der Mouse"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"150298","messageId":"BLU0-SMTP666507C6D3E37A50B92431BB720@phx.gbl","threadId":"25037","inReplyTo":null,"subject":"Errors in man git","fromName":"Daniel U. Thibault","fromEmail":"d.u.thibault-riew9wucm8ffj04o6pk0fg@public.gmane.org","sentAt":"2010-09-08T14:36:53Z","receivedAt":"2010-09-08T14:36:53Z","isPatch":false,"sender":{"key":"d.u.thibault-riew9wucm8ffj04o6pk0fg@public.gmane.org","avatar":null},"body":"\n There are no indications in the \"man git\" pages as to how to report \nerrors, so I'm following the instructions I googled at \nhttp://www.kernel.org/doc/man-pages/reporting_bugs.html (adding \ngit-u79uwXL29TY76Z2rM5mHXA@public.gmane.org to the mailing list as it seems appropriate).\n\n The \"man git\" pages give the syntax (SYNOPSIS) as:\n\n##########\ngit [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]\n [-p|--paginate|--no-pager] [--no-replace-objects]\n [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\n [--help] COMMAND [ARGS]\n##########\n\n Hence \"git COMMAND\" should work once the appropriate value is \nsubstituted for COMMAND. The COMMANDs are later documented (GIT \nCOMMANDS) as long lists of \"porcelain\" and \"plumbing\" COMMANDs. \nHowever, *none* of the COMMANDs given actually work. For instance, one \n(porcelain) COMMAND is \"git-gui\" but typing \"git git-gui\" in a command \nshell results in the message:\n\n##########\ngit: 'git-gui' is not a git command. See 'git --help'.\n##########\n\n The actual COMMAND (documented under \"man git-gui\") is \"gui\".\n\n Now, if the intent of the COMMAND lists is to send the user off to \nthe other man-pages, that is fine but ought to be clearly indicated by a \npreamble of some sort. Maybe the man pages should read something like:\n\n##########\nGIT COMMANDS\n We divide git into high level (\"porcelain\") commands and low level\n (\"plumbing\") commands.\n\n The actual COMMAND strings are documented under the individual\n man pages listed in what follows. For instance, the COMMAND for\n \"adding file contents to the index\" is given by the git-add man \npages.\n##########\n\nDaniel U. Thibault\na.k.a. Urhixidur\na.k.a. Seigneur Bohémond de Nicée\nURL: \n--\nTo unsubscribe from this list: send the line \"unsubscribe linux-man\" in\nthe body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org\nMore majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"150325","messageId":"20100908233140.7d5df3ee@jk.gs","threadId":"25037","inReplyTo":"BLU0-SMTP666507C6D3E37A50B92431BB720@phx.gbl","subject":"Re: Errors in man git","fromName":"Jan Krüger","fromEmail":"jk@jk.gs","sentAt":"2010-09-08T21:31:40Z","receivedAt":"2010-09-08T21:31:40Z","isPatch":false,"sender":{"key":"jk@jk.gs","avatar":"https://avatars.githubusercontent.com/u/1774?v=4"},"body":"Hi,\n\n\"Daniel U. Thibault\" wrote:\n\n> There are no indications in the \"man git\" pages as to how to\n> report errors, so I'm following the instructions I googled at \n> http://www.kernel.org/doc/man-pages/reporting_bugs.html (adding \n> git@vger.kernel.org to the mailing list as it seems appropriate). \n\nSince the manpages are written by the git project only, I think it's\nmore appropriate to address the git mailing list only. [pruning other\nrecipients]\n\n> [...] Hence \"git COMMAND\" should work once the appropriate value\n> is substituted for COMMAND. The COMMANDs are later documented (GIT \n> COMMANDS) as long lists of \"porcelain\" and \"plumbing\" COMMANDs. \n> However, *none* of the COMMANDs given actually work. For instance,\n> one (porcelain) COMMAND is \"git-gui\" but typing \"git git-gui\" in a\n> command shell results in the message: \n\nThat's because of the way other manpages have to be referenced. Let me\ninclude a snippet from the manpage to clarify:\n\n| HIGH-LEVEL COMMANDS (PORCELAIN)\n| We separate the porcelain commands into the main commands and\n| some ancillary user utilities.\n|\n| Main porcelain commands\n| git-add(1)\n| Add file contents to the index.\n\nHere, \"git-add(1)\" is written in one word because otherwise it's not a\nvalid reference to another manpage. The only alternative is that we\nrename the manpage to \"add\"... but people probably won't like git\npolluting the manpage namespace that way, and \"add\" by itself isn't a\nvalid command anyway.\n\nIf you look at \"man git-add\", you'll see that the synopsis given there\nshows the right way to invoke the command:\n\n| NAME\n| git-add - Add file contents to the index\n| \n| SYNOPSIS\n| git add [-n] [-v] [--force | -f] [--interactive | -i]\n| [--patch | -p] [--edit | -e] [--all | [--update | -u]]\n| [--intent-to-add | -N] [--refresh] [--ignore-errors]\n| [--ignore-missing] [--] [...]\n\nI agree that it is potentially confusing, but the manpage references\nare clearly recognisable as such.\n\nPersonally I don't consider it necessary to change this, since it's\nclearly not horribly complicated to figure out the meaning, but here's\na patch for the sake of completeness.\n\n----8<----\n\nSubject: [PATCH] Documentation/git.txt: explain that manpages for subcommands exist\n\nOn the off chance that it is not apparent that the manpages for\nindividual git commands explain how to use git commands (e.g. if\nsomeone manages to conclude that \"git git-add\" is the way to use\ngit-add(1)), add a small explanation about that.\n\nSigned-off-by: Jan Krüger \n---\n Documentation/git.txt | 3 ++-\n 1 files changed, 2 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 93e3b07..fbceb12 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -316,7 +316,8 @@ GIT COMMANDS\n ------------\n \n We divide git into high level (\"porcelain\") commands and low level\n-(\"plumbing\") commands.\n+(\"plumbing\") commands. Please refer to the individual manpages listed\n+in the sections below for details on how to invoke each command.\n \n High-level commands (porcelain)\n -------------------------------\n-- \n1.7.2.3.392.g02377\n"},{"id":"150326","messageId":"201009082209.SAA08134@Sparkle.Rodents-Montreal.ORG","threadId":"25037","inReplyTo":"20100908233140.7d5df3ee@jk.gs","subject":"Re: Errors in man git","fromName":"der Mouse","fromEmail":"mouse@rodents-montreal.org","sentAt":"2010-09-08T22:09:02Z","receivedAt":"2010-09-08T22:09:02Z","isPatch":false,"sender":{"key":"mouse@rodents-montreal.org","avatar":null},"body":"> | Main porcelain commands\n> | git-add(1)\n> | Add file contents to the index.\n\n> Here, \"git-add(1)\" is written in one word because otherwise it's not\n> a valid reference to another manpage.\n\nThat's always bothered me; I'd prefer to something more like\n\n Main porcelain commands\n git add (see git-add(1))\n Add file contents to the index.\n\n/~\\ The ASCII\t\t\t\t Mouse\n\\ / Ribbon Campaign\n X Against HTML\t\tmouse@rodents-montreal.org\n/ \\ Email!\t 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B\n"},{"id":"150327","messageId":"20100909001411.067f29f8@jk.gs","threadId":"25037","inReplyTo":"201009082209.SAA08134@Sparkle.Rodents-Montreal.ORG","subject":"Re: Errors in man git","fromName":"Jan Krüger","fromEmail":"jk@jk.gs","sentAt":"2010-09-08T22:14:11Z","receivedAt":"2010-09-08T22:14:11Z","isPatch":false,"sender":{"key":"jk@jk.gs","avatar":"https://avatars.githubusercontent.com/u/1774?v=4"},"body":"der Mouse wrote:\n\n> That's always bothered me; I'd prefer to something more like\n> \n> Main porcelain commands\n> git add (see git-add(1))\n> Add file contents to the index.\n\nTo what end? I have never seen anyone who got genuinely confused by the\nway it currently reads, and I've been hanging out on #git for over two\nyears now.\n\nAlso, please address your concerns to the department of redundancy\ndepartment. ;)\n"},{"id":"150337","messageId":"201009090048.UAA08864@Sparkle.Rodents-Montreal.ORG","threadId":"25037","inReplyTo":"20100909001411.067f29f8@jk.gs","subject":"Re: Errors in man git","fromName":"der Mouse","fromEmail":"mouse@rodents-montreal.org","sentAt":"2010-09-09T00:48:31Z","receivedAt":"2010-09-09T00:48:31Z","isPatch":false,"sender":{"key":"mouse@rodents-montreal.org","avatar":null},"body":">> That's always bothered me; I'd prefer to something more like\n\n>> git add (see git-add(1))\n\n> To what end?\n\nIn a word, accuracy. To refer to foo(1) without further annotation\nimplies the existence of both the manpage and the command. Violating\nthat expectation grates and annoys even after it's clear what is really\ngoing on.\n\n> I have never seen anyone who got genuinely confused by the way it\n> currently reads, and I've been hanging out on #git for over two years\n> now.\n\nI was. Briefly. Initially. The colleague who introduced me to git\ncleared up the confusion, of course, and it hasn't confused me more\nthan momentarily since - but it still grates every time I see it. Not\nin a truly confusing sense, but more in an \"oh yes, this is a\ngit-related manpage, I have to remember to mentally correct for their\nmisnamed manpages\" special-case sort of sense. Knowing how to correct\nfor it, even (I think) understanding why it was done, those do not make\nit any less expensive to maintain special-case interpretations.\n\n> Also, please address your concerns to the department of redundancy\n> department. ;)\n\nRedundancy is not an inherently bad thing. Writing manpages in English\n(or any other natural language, for that matter) at all introduces\ntremendous redundancy. Shannon estimated the information content of\nnormal connected English at about one bit per letter; even if this is\nlow by a factor of two (and manpages probably have less redundancy than\nShannon's sample), it means manpages are still 3/4 redundant even if\nyou look at only the content, never mind the formatting.\n\nRedundancy greatly improves communication between people; that's why\nall natural langauges have a great deal of it - and manpages are just a\nspecialized form of such communication. Especially when dealing with\nthings like computer interfaces, where precision is essential, I am\nentirely willing to tolerate additional redundancy for the sake of\ngreater precision.\n\nOf course, it's not my decision to make. And I don't know to what\nextent the arguments you cite are the real reasons for keeping the\nstyle you have. But I don't think these arguments really hold all\nthat much weight.\n\n/~\\ The ASCII\t\t\t\t Mouse\n\\ / Ribbon Campaign\n X Against HTML\t\tmouse@rodents-montreal.org\n/ \\ Email!\t 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B\n"}]}