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

some confusing passages in online SVN book

From: Robert P. J. Day <rpjday_at_mindspring.com>
Date: 2004-12-19 18:06:36 CET

  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.



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

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

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.