* Notes and questions while reading the documentation
@ 2005-10-05 22:06 Christian Meder
2005-10-05 23:30 ` Junio C Hamano
0 siblings, 1 reply; 3+ messages in thread
From: Christian Meder @ 2005-10-05 22:06 UTC (permalink / raw)
To: git
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)
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Notes and questions while reading the documentation
2005-10-05 22:06 Notes and questions while reading the documentation Christian Meder
@ 2005-10-05 23:30 ` Junio C Hamano
2005-10-10 21:22 ` Christian Meder
0 siblings, 1 reply; 3+ messages in thread
From: Junio C Hamano @ 2005-10-05 23:30 UTC (permalink / raw)
To: Christian Meder; +Cc: git
Christian Meder <chris@absolutegiganten.org> 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.
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Notes and questions while reading the documentation
2005-10-05 23:30 ` Junio C Hamano
@ 2005-10-10 21:22 ` Christian Meder
0 siblings, 0 replies; 3+ messages in thread
From: Christian Meder @ 2005-10-10 21:22 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
Sorry for being slow.
On Wed, 2005-10-05 at 16:30 -0700, Junio C Hamano wrote:
> Christian Meder <chris@absolutegiganten.org> 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)
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2005-10-10 21:23 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2005-10-05 22:06 Notes and questions while reading the documentation Christian Meder
2005-10-05 23:30 ` Junio C Hamano
2005-10-10 21:22 ` Christian Meder
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).