# Notes and questions while reading the documentation 3 messages from 2005-10-05 to 2005-10-10. Participants: Christian Meder, Junio C Hamano. Thread: https://gitlist.dev/t/2027 ## Christian Meder, 2005-10-05 22:06 Subject: Notes and questions while reading the documentation Message-ID: <1128549966.11363.29.camel@localhost> URL: https://gitlist.dev/e/1128549966.11363.29.camel%40localhost ``` Hi, while (proof-)reading the Documentation I noted down some remarks and questions: * a lot of the manpages include something like "v0.1, June 2005" in the header; these versions tags are pretty obscure to interpret, timestamp when last edited ? version of the manpage ? version of git when the manpage was included ? maturity the author assigned to the content ? If these tags don't follow some sane schema they should be removed. * git-applymbox: -q for interactivity seems like a strange choice, ok I knew -i for interactive and -q for quiet but -q for interactive editing is _not_ really intuitive * the usage of git, Git and GIT isn't consistent in the documentation. I'd vote for only using git. * git-clone says that http transport is not supported yet I used it to clone the git repo from kernel.org yesterday. Should the documentation get updated ? * the manpage synopsises aren't consistent wrt command naming; it's "git commit" but "git-branch"; I guess all the manpages should reference their commands as "git-x" and not "git x" Greetings, Christian -- Christian Meder, email: chris@absolutegiganten.org The Way-Seeking Mind of a tenzo is actualized by rolling up your sleeves. (Eihei Dogen Zenji) ``` ## Junio C Hamano, 2005-10-05 23:30 Subject: Re: Notes and questions while reading the documentation Message-ID: <7v1x2zfsp2.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7v1x2zfsp2.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <1128549966.11363.29.camel@localhost> ``` Christian Meder writes: > * a lot of the manpages include something like "v0.1, June 2005" in the > header; these versions tags are pretty obscure to interpret, timestamp > when last edited ? version of the manpage ? version of git when the > manpage was included ? maturity the author assigned to the content ? > If these tags don't follow some sane schema they should be removed. I think the original intent was the last modification datestamp and the version of the documentation, but I agree it should be removed. I do not think they show on the HTML version, nor man pages, although I have to admit that I haven't looked at generated manpages for some time. > * git-applymbox: -q for interactivity seems like a strange choice, ok I > knew -i for interactive and -q for quiet but -q for interactive editing > is _not_ really intuitive Last night I felt the same way, and an rewrite [*1*] of applymbox I am working on uses '-i' instead. If users do not object, I would vote for changing applymbox to use '-i' as well. The user community consensus does not have to be unanimous, but anybody who has linux kernel tree on kernel.org servers has a veto on this, I should say. It's the tool they use every day. > * the usage of git, Git and GIT isn't consistent in the documentation. > I'd vote for only using git. Sounds sane. What would we do if we need to start sentences with it? > * git-clone says that http transport is not supported yet I used it to > clone the git repo from kernel.org yesterday. Should the documentation > get updated ? Thanks for noticing. Yes, now HTTP can handle both of the trickier setups (packed, and alternates); credit goes to Daniel. > * the manpage synopsises aren't consistent wrt command naming; it's "git > commit" but "git-branch"; I guess all the manpages should reference > their commands as "git-x" and not "git x" Agreed. Again, thanks for taking the time to do this. [Footnote] *1* Why rewrite? One reason was I was afraid to break things for Linus ;-). And I wanted to add a bit more interactivity and restartability. The ultimate goal is to make 'git-rebase' and 'git-cherry-pick' faster and easier to use. The idea is not to always do 3-way merge, but essentailly feed format-patch output (now it can do --stdout) into the new applymbox, and when patch applies cleanly things will go faster, otherwise it will fall back to 3-way merge behaviour. ``` ## Christian Meder, 2005-10-10 21:22 Subject: Re: Notes and questions while reading the documentation Message-ID: <1128979355.7097.33.camel@localhost> URL: https://gitlist.dev/e/1128979355.7097.33.camel%40localhost In-Reply-To: <7v1x2zfsp2.fsf@assigned-by-dhcp.cox.net> ``` Sorry for being slow. On Wed, 2005-10-05 at 16:30 -0700, Junio C Hamano wrote: > Christian Meder writes: > > > * a lot of the manpages include something like "v0.1, June 2005" in the > > header; these versions tags are pretty obscure to interpret, timestamp > > when last edited ? version of the manpage ? version of git when the > > manpage was included ? maturity the author assigned to the content ? > > If these tags don't follow some sane schema they should be removed. > > I think the original intent was the last modification datestamp > and the version of the documentation, but I agree it should be > removed. I do not think they show on the HTML version, nor man > pages, although I have to admit that I haven't looked at > generated manpages for some time. Ok. I've done a patch to remove them in a separate email. > > * the usage of git, Git and GIT isn't consistent in the documentation. > > I'd vote for only using git. > > Sounds sane. What would we do if we need to start sentences with it? I prepared a patch which changes all usages to git even at the beginning of sentences. > > * git-clone says that http transport is not supported yet I used it to > > clone the git repo from kernel.org yesterday. Should the documentation > > get updated ? > > Thanks for noticing. Yes, now HTTP can handle both of the > trickier setups (packed, and alternates); credit goes to Daniel. I noted it down for my second sweep. > > * the manpage synopsises aren't consistent wrt command naming; it's "git > > commit" but "git-branch"; I guess all the manpages should reference > > their commands as "git-x" and not "git x" > > Agreed. > Ok. Patch in separate email. Christian -- Christian Meder, email: chris@absolutegiganten.org The Way-Seeking Mind of a tenzo is actualized by rolling up your sleeves. (Eihei Dogen Zenji) ```