#6 Clarify explanation of TTB structure and project layout

[Anonymous]

Originally created by: cmpilato
Originally owned by: cmpilato

[Was http://svnbook.red-bean.com/trac/ticket/122]

Steve Stanley made some suggestions about the explanation of project roots
and TTB layouts:
{{{
To: svnbook-dev@red-bean.com
From: Steve Stanley <w3steve@berkeley.edu>
Subject: svnbook 1.4: inconsistent explanation of TTB directories?
Date: Thu, 19 Jun 2008 09:39:21 -0700

Hello,

John Niven <jniven@bravurasolutions.com> suggested (in response to my
post on the users@subversion list) that I write this list. (The
pertinent part of the users digest follows these notes.)

First of all, thanks for providing the online version of svnbook; it's
insanely great!

Second, I imagine I am stepping on the toes of the author of the
"Recommended repository layout" chunk, but I respectfully submit:

As a new Subversion administrator, I found the svnbook discussion of
the TTB directories confusing.

After reading the helpful replies from the users@subversion.tigris.org
list, I think my problem is that the book seems to imply (in a few
places) that the TTB directories are an attribute of the repository
(and thus *created* by the administrator with svnadmin commands)
whereas (as the replies indicate) the TTB dirs are *added* to the
repository with svn commands (by administrators or users?).

In this chapter:

   http://svnbook.red-bean.com/en/1.4/svn.tour.importing.html

I now suggest changing the heading "Recommended repository layout" to
"Recommended *project* layout" and likewise in the following
paragraph, with the added code examples:

   While Subversion's flexibility allows you to layout your *project*
   in any way that you choose, we recommend that you create a trunk
   directory to hold the “main line” of development, a branches
   directory to contain branch copies, and a tags directory to contain
   tag copies, for example:

   $ mkdir mytree/trunk ; mkdir mytree/tags ; mkdir mytree/branches
   $ svn import mytree file:///usr/local/svn/repos 
       ### (or svn mkdir ... svn ci, or svn mkdir URL ...) -ss
   $ svn list file:///usr/local/svn/repos
   /trunk
   /branches
   /tags

Other sections where the svnadmin/svn distinction seems muddled:

 
http://svnbook.red-bean.com/en/1.4/svn.branchmerge.maint.html#svn.branchmerge.maint.layout
 
http://svnbook.red-bean.com/en/1.4/svn.reposadmin.planning.html#svn.reposadmin.projects.chooselayout

Here it's ambiguous:

   http://svnbook.red-bean.com/en/1.4/svn.reposadmin.maint.html
   http://svnbook.red-bean.com/en/1.4/svn.branchmerge.using.html
 
http://svnbook.red-bean.com/en/1.4/svn.reposadmin.maint.html#svn.reposadmin.maint.filtering

Here it's a lot clearer that the TTBs are created in the project:

   http://svnbook.red-bean.com/en/1.4/svn.intro.quickstart.html

Respectfully,

Steve Stanley
}}}

[Anonymous]

Originally posted by: cmpilato

(No comment was entered for this change.)

Labels: Milestone-whenever

[Anonymous]

Originally posted by: cmpilato

(No comment was entered for this change.)

Owner: ---

[Anonymous]

Originally posted by: cmpilato

I'll take care of this soon.

Labels: -Milestone-whenever Milestone-en-1.8
Owner: cmpilato

[Anonymous]

Originally posted by: cmpilato

As I review never versions of the book, I think we've already made the most important tweaks at the root of this complaint.  The semantic difference between "a repository layout" and "a project layout" seems to be at the heart of things, but as the book only rarely if ever) concerns itself with how your physical repository is positioned on your server, I think we're being consistent enough.  I've made some additional small tweaks to hopefully offset any confusion, too.  (Though, honestly, this complaint is the only such one I remember ever receiving.)

Anyway, calling it Fixed now.

Status: Fixed