Re: [PATCH] Add a birdview-on-the-source-code section to the user manual

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: May 9, 2007, 09:27 UTC
Message-ID: <Pine.LNX.4.64.0705091120560.4167@racer.site>
In-Reply-To: <20070509031803.GA27980@fieldses.org>

Hi,

On Tue, 8 May 2007, J. Bruce Fields wrote:

Show 9 quoted lines

> On Tue, May 08, 2007 at 05:10:47PM +0200, Johannes Schindelin wrote:
> > 
> > +If you grasp the ideas in that initial commit (it is really small and you 
> > +can get into it really fast, and it will help you recognize things in the 
> > +much larger code base we have now), you should go on skimming `cache.h`, 
> > +`object.h` and `commit.h`.
> 
> Might want to add "in a recent commit"?--it's not clear that you've
> transitioned away from talking about the initial commit.

Yes, good idea.

Show 5 quoted lines

> > +This is just to get you into the groove for the most libified part of Git:
> > +the revision walker.
> 
> Unless the reader has already been hanging out on the mailing list a 
> while, "most libified" may not mean much to them yet at this point.

How about a sentence way before that, when I talk about the initial commit, like this:

	In the early days, Git (in the tradition of UNIX) was a bunch of 
	programs which were extremely simple, and which you used in scripts, 
	piping the output of one into another. This turned out to be good 
	for initial development, since it was easier to test new things. 
	However, recently many of these parts have become builtins, and 
	some of the core has been "libified", i.e. put into libgit.a for 
	performance, portability reasons, and to avoid code duplication.

Show 11 quoted lines

> The organization of the next bit is slightly confusing: we're set up to
> expect a longer lecture on the revision walker, but instead there's just
> the historical note on git-rev-list, a mention of 'revision.c',
> 'revision.h', and 'struct rev_info', and then it rapidly digresses into
> discussing builtins.
> 
> Which actually is fine, but just a few small markers of where we are in
> the discussion might be reassuring--a section header or two, maybe a
> little more emphasis on the pointers you're giving, like: "take a moment
> to go read revision.h and revision.c now, paying special attention to
> struct rev_info, which ....".

Okay. I hope I will be able to make these changes until tomorrow (I will be gone for a few days after that).

Ciao, Dscho