having read through most of the first 3 chapters of the online
subversion book, there were a few things that initially threw me with
they way they were presented, and some inconsistencies that i suspect
will confuse a few other newbies if they are following the
presentation. (some of these are admittedly nitpicky and pedantic,
but they did cost me a few minutes of time, and it's quite possible
that i'm just totally confused about what's going on.)
some observations (with page numbers being from the PDF version, the
actual *on-page* number):
p. 6:
"To begin, create a new repository:
$ 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*.
if someone is used to using "repo" as short for "repository", it's
just possible to be confusing, at least temporarily. why not just
"/path/to/repo" to avoid any potential misreading? (i did say i was
going to be nitpicky.)
p. 6:
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.
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.
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. 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? and what's the relationship between
a project and a repository now? is the reader now supposed to
conclude that a repository can contain multiple projects?
newbies are definitely going to wonder what happened to those
top-level directories.
p. 23:
The example shown here just adds more confusion. Consider the
sample checkout comamand:
$ svn checkout http://svn.collab.net/repos/svn/trunk
Based on the previous pages, suddenly "trunk/" is back, but
where did its parent directory "svn/" suddenly come from? now
it appears that the "svn.collab.net/repos" really *does* contain
multiple repos/projects, of which "svn" is only one, with its
corresponding "trunk/" directory.
(the highlighted note on that page suggests that "trunk" is part of
the way the book recommends laying out a repository, but the fact
that it disagrees with the previous usage is really going to confuse
the heck out of new readers who, by now, are going to be wondering,
"what's a repo?" "what's a project?" "how are they related?" "and
why does this 'trunk/' directory keep coming and going, and showing
up in different places?")
anyway, just a few observations, based on *exactly* what confused me
as i was reading.
thoughts?
rday
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Sun Dec 19 18:09:26 2004