[svnbook] r3877 committed - Finish issue #52 ("Explain the differing ways in which -rX is...

[svnbook at googlecode.com]

Revision: 3877
Author:   cmpilato at gmail.com
Date:     Tue Jul  5 08:33:53 2011
Log:      Finish issue #52 ("Explain the differing ways in which -rX is
interpreted in externals definitions").

* src/en/book/ch03-advanced-topics.xml
   (svn.advanced.externals): Note the -rN is a peg revision in the
     pre-1.5 externals definition syntax and an operative revision in the
     newer syntax.

http://code.google.com/p/svnbook/source/detail?r=3877

Modified:
  /trunk/src/en/book/ch03-advanced-topics.xml

=======================================
--- /trunk/src/en/book/ch03-advanced-topics.xml	Tue Jul  5 08:21:01 2011
+++ /trunk/src/en/book/ch03-advanced-topics.xml	Tue Jul  5 08:33:53 2011
@@ -3691,8 +3691,7 @@
        must be modified instead. However, file externals can be copied.
      </para>

-    <para>
-      Perhaps most disappointingly, the working copies created via the
+    <para>Perhaps most disappointingly, the working copies created via the
        externals definition support are still disconnected from the primary
        working copy (on whose versioned directories the
        <literal>svn:externals</literal> property was actually set).
@@ -3706,12 +3705,21 @@
      <para>We've already mentioned some of the additional shortcomings
        of the old <literal>svn:externals</literal> format and how the
        new Subversion 1.5 format improves upon it.  But be careful when
-      making use of the new format that you don't inadvertently cause
-      problems for other folks accessing your repository who are using
-      older Subversion clients.  While Subversion 1.5 clients will
-      continue to recognize and support the original externals
-      definition format, older clients will <emphasis>not</emphasis>
-      be able to correctly parse the new format.</para>
+      making use of the new format that you don't inadvertently
+      introduce new problems.  For example, while Subversion 1.5
+      clients will continue to recognize and support the original
+      externals definition format, older clients
+      will <emphasis>not</emphasis> be able to correctly parse the new
+      format.  If you change all your externals definitions to the
+      newer format, you effectively force everyone who uses those
+      externals to upgrade their Subversion clients to a version that
+      can parse them.  Also, be careful to avoid naively relocating
+      the <literal>-r<replaceable>NNN</replaceable></literal> portion
+      of the definition—the older format uses that revision as
+      a peg revision, but the newer format uses it as an operative
+      revision (with a peg revision of <literal>HEAD</literal> unless
+      otherwise specified; see <xref linkend="svn.advanced.pegrevs"
+      /> for a full explanation of the distinction here).</para>

      <warning>
        <para>External working copies are still completely