[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: some confusing passages in online SVN book

From: Ben Collins-Sussman <sussman_at_collab.net>
Date: 2004-12-19 19:46:15 CET

On Dec 19, 2004, at 11:06 AM, Robert P. J. Day wrote:
>
> $ svnadmin create /path/to/repos"
>
> it's potentially confusing to refer to "/path/to/repos" since that
> gives the impression of being "repos" *plural*, rather than, as i
> now read it, "repos" being short for "repository" *singular*.

Good point.

> again a bit more possible for confusion, when it shows how to
> import a "project" to initialize a repository. is it clear that
> there is a 1:1 correspondence between a repository and the "project"
> it represents? that's not explicitly spelled out here, but it's
> certainly implied.

Does it matter?

>
> it's also pretty clearly implied that a repository should always
> contain the three top-level directories branches/, tags/ and trunk/.
> more on this shortly.

That's a deliberate implication, since it's a suggested standard.

>
> p. 13:
> the sample repo here seems to disagree with the rules presented just
> a few pages earlier. here, we have a repo that contains *two*
> software projects (paint and calc) and, on the next page, there's
> a depiction of those projects.

Aha.

> but where are the aforementioned
> directories branches/, tags/ and trunk/? if you recommend that
> users create these top-level directories, why are they missing in
> the very first working example?

Answer below.

> anyway, just a few observations, based on *exactly* what confused me
> as i was reading.
>
>

I think there's a meta-problem here.

Originally, the chapter 1 "quick-start" example didn't exist at all.
The book followed a nice logical progression:

    * Chapter 2 merely introduced the concepts of working copies and
repositories. It made no suggestions or proclamations about "how many
projects" lived in a repository, or what the branch/tag structure of a
repository should look like. The examples were designed to be as
simple as possible.

    * Chapter 4 first introduced the concepts of trunk/branches/tags
structure.

    * Chapter 5 first introduced the idea of deciding how many projects
to put in a repository.

    * Chapter 6 first introduced the idea of "customizing" the URL that
makes your repository available to the world, i.e. putting an 'svn/' in
the URL, or whatever you wish.

But then a whole class of users -- those who demand learning by example
("bottom up"), rather than reading a long "top-down" presentation over
many chapters. So we added the chapter 1 quick-start section as a way
to get these people started... and hopefully those folks follow all the
pointers throughout the quick start to the relevant chapters.

So I'm not sure how to resolve this tension: put the quick-start into
an appendix, and merely mention it in chapter 1? Would that help?
It sounds to me like you're a 'top-down' reader who's busy trying to
infer meaning in every little detail you see. Things might have been
smoother for you if you had never encountered the 'quick start' at all.

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Sun Dec 19 19:50:06 2004

This is an archived mail posted to the Subversion Users mailing list.