{"thread":{"id":"2027","subject":"Notes and questions while reading the documentation","startedAt":"2005-10-05T22:06:06Z","lastAt":"2005-10-10T21:22:35Z","messageCount":3,"participants":["Christian Meder","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"9732","messageId":"1128549966.11363.29.camel@localhost","threadId":"2027","inReplyTo":null,"subject":"Notes and questions while reading the documentation","fromName":"Christian Meder","fromEmail":"chris@absolutegiganten.org","sentAt":"2005-10-05T22:06:06Z","receivedAt":"2005-10-05T22:06:06Z","isPatch":false,"sender":{"key":"chris@absolutegiganten.org","avatar":null},"body":"Hi,\n\nwhile (proof-)reading the Documentation I noted down some remarks and\nquestions:\n\n* a lot of the manpages include something like \"v0.1, June 2005\" in the\nheader; these versions tags are pretty obscure to interpret, timestamp\nwhen last edited ? version of the manpage ? version of git when the\nmanpage was included ? maturity the author assigned to the content ?\nIf these tags don't follow some sane schema they should be removed.\n\n* git-applymbox: -q for interactivity seems like a strange choice, ok I\nknew -i for interactive and -q for quiet but -q for interactive editing\nis _not_ really intuitive\n\n* the usage of git, Git and GIT isn't consistent in the documentation.\nI'd vote for only using git.\n\n* git-clone says that http transport is not supported yet I used it to\nclone the git repo from kernel.org yesterday. Should the documentation\nget updated ?\n\n* the manpage synopsises aren't consistent wrt command naming; it's \"git\ncommit\" but \"git-branch\"; I guess all the manpages should reference\ntheir commands as \"git-x\" and not \"git x\"\n\nGreetings,\n\n\n\n\t\t\t\tChristian \n-- \nChristian Meder, email: chris@absolutegiganten.org\n\nThe Way-Seeking Mind of a tenzo is actualized \nby rolling up your sleeves.\n\n (Eihei Dogen Zenji)\n"},{"id":"9739","messageId":"7v1x2zfsp2.fsf@assigned-by-dhcp.cox.net","threadId":"2027","inReplyTo":"1128549966.11363.29.camel@localhost","subject":"Re: Notes and questions while reading the documentation","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-10-05T23:30:01Z","receivedAt":"2005-10-05T23:30:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Christian Meder writes:\n\n> * a lot of the manpages include something like \"v0.1, June 2005\" in the\n> header; these versions tags are pretty obscure to interpret, timestamp\n> when last edited ? version of the manpage ? version of git when the\n> manpage was included ? maturity the author assigned to the content ?\n> If these tags don't follow some sane schema they should be removed.\n\nI think the original intent was the last modification datestamp\nand the version of the documentation, but I agree it should be\nremoved. I do not think they show on the HTML version, nor man\npages, although I have to admit that I haven't looked at\ngenerated manpages for some time.\n\n> * git-applymbox: -q for interactivity seems like a strange choice, ok I\n> knew -i for interactive and -q for quiet but -q for interactive editing\n> is _not_ really intuitive\n\nLast night I felt the same way, and an rewrite [*1*] of\napplymbox I am working on uses '-i' instead. If users do not\nobject, I would vote for changing applymbox to use '-i' as well.\n\nThe user community consensus does not have to be unanimous, but\nanybody who has linux kernel tree on kernel.org servers has a\nveto on this, I should say. It's the tool they use every day.\n\n> * the usage of git, Git and GIT isn't consistent in the documentation.\n> I'd vote for only using git.\n\nSounds sane. What would we do if we need to start sentences with it?\n\n> * git-clone says that http transport is not supported yet I used it to\n> clone the git repo from kernel.org yesterday. Should the documentation\n> get updated ?\n\nThanks for noticing. Yes, now HTTP can handle both of the\ntrickier setups (packed, and alternates); credit goes to Daniel.\n\n> * the manpage synopsises aren't consistent wrt command naming; it's \"git\n> commit\" but \"git-branch\"; I guess all the manpages should reference\n> their commands as \"git-x\" and not \"git x\"\n\nAgreed.\n\nAgain, thanks for taking the time to do this.\n\n[Footnote]\n\n*1* Why rewrite? One reason was I was afraid to break things\nfor Linus ;-). And I wanted to add a bit more interactivity and\nrestartability. The ultimate goal is to make 'git-rebase' and\n'git-cherry-pick' faster and easier to use. The idea is not to\nalways do 3-way merge, but essentailly feed format-patch output\n(now it can do --stdout) into the new applymbox, and when patch\napplies cleanly things will go faster, otherwise it will fall\nback to 3-way merge behaviour.\n"},{"id":"9931","messageId":"1128979355.7097.33.camel@localhost","threadId":"2027","inReplyTo":"7v1x2zfsp2.fsf@assigned-by-dhcp.cox.net","subject":"Re: Notes and questions while reading the documentation","fromName":"Christian Meder","fromEmail":"chris@absolutegiganten.org","sentAt":"2005-10-10T21:22:35Z","receivedAt":"2005-10-10T21:22:35Z","isPatch":false,"sender":{"key":"chris@absolutegiganten.org","avatar":null},"body":"Sorry for being slow.\n\nOn Wed, 2005-10-05 at 16:30 -0700, Junio C Hamano wrote:\n> Christian Meder writes:\n> \n> > * a lot of the manpages include something like \"v0.1, June 2005\" in the\n> > header; these versions tags are pretty obscure to interpret, timestamp\n> > when last edited ? version of the manpage ? version of git when the\n> > manpage was included ? maturity the author assigned to the content ?\n> > If these tags don't follow some sane schema they should be removed.\n> \n> I think the original intent was the last modification datestamp\n> and the version of the documentation, but I agree it should be\n> removed. I do not think they show on the HTML version, nor man\n> pages, although I have to admit that I haven't looked at\n> generated manpages for some time.\n\nOk. I've done a patch to remove them in a separate email.\n\n> > * the usage of git, Git and GIT isn't consistent in the documentation.\n> > I'd vote for only using git.\n> \n> Sounds sane. What would we do if we need to start sentences with it?\n\nI prepared a patch which changes all usages to git even at the beginning\nof sentences. \n\n> > * git-clone says that http transport is not supported yet I used it to\n> > clone the git repo from kernel.org yesterday. Should the documentation\n> > get updated ?\n> \n> Thanks for noticing. Yes, now HTTP can handle both of the\n> trickier setups (packed, and alternates); credit goes to Daniel.\n\nI noted it down for my second sweep.\n\n> > * the manpage synopsises aren't consistent wrt command naming; it's \"git\n> > commit\" but \"git-branch\"; I guess all the manpages should reference\n> > their commands as \"git-x\" and not \"git x\"\n> \n> Agreed.\n> \n\nOk. Patch in separate email.\n\n\n\t\t\t\tChristian\n\n-- \nChristian Meder, email: chris@absolutegiganten.org\n\nThe Way-Seeking Mind of a tenzo is actualized \nby rolling up your sleeves.\n\n (Eihei Dogen Zenji)\n"}]}