Skip to contentSkip to conversation

Notes and questions while reading the documentation

DISCUSSION Christian Meder 2 participants 3 messages Jun 15, 2016

lore
Share & tools
lore
#0 lore raw

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

Signature · 6 lines
Christian Meder, email: [email protected]

The Way-Seeking Mind of a tenzo is actualized 
by rolling up your sleeves.

                (Eihei Dogen Zenji)
#1 lore raw
Quoted 5 lines · Christian Meder

* 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.

Quoted 3 lines

* 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.

Quoted 2 lines

* 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?

Quoted 3 lines

* 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.

Quoted 3 lines

* 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.

#2 lore raw

Sorry for being slow.

Quoted 8 lines · Junio C Hamano
Quoted 5 lines · Christian Meder

* 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.

Quoted 5 lines

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.

Quoted 4 lines
Quoted 2 lines

* 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.

Quoted 6 lines
Quoted 3 lines

* 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.

Quoted 6 lines
Quoted 3 lines

* 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

Signature · 6 lines
Christian Meder, email: [email protected]

The Way-Seeking Mind of a tenzo is actualized 
by rolling up your sleeves.

                (Eihei Dogen Zenji)