[svnbook] r6061 committed - trunk/en/book/ch03-advanced-topics.xml

[cmpilato at users.sourceforge.net]

Revision: 6061
          http://sourceforge.net/p/svnbook/source/6061
Author:   cmpilato
Date:     2023-07-13 14:52:56 +0000 (Thu, 13 Jul 2023)
Log Message:
-----------
Issue #284: Document the externals definitions comment syntax.

* en/book/ch03-advanced-topics.xml
  (svn.advanced.externals): Add to one of the example series an
    externals definition comment, plus a paragraph after the first
    demonstration which calls out this feature of the syntax
    explicitly.
  
Suggested by: danielsahlberg

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

Modified: trunk/en/book/ch03-advanced-topics.xml
===================================================================
--- trunk/en/book/ch03-advanced-topics.xml	2023-05-18 01:40:53 UTC (rev 6060)
+++ trunk/en/book/ch03-advanced-topics.xml	2023-07-13 14:52:56 UTC (rev 6061)
@@ -4773,12 +4773,22 @@
     <informalexample>
       <screen>
 $ svn propget svn:externals calc
+# Resources versioned elsewhere.
 third-party/sounds             http://svn.example.com/repos/sounds
 third-party/skins -r148        http://svn.example.com/skinproj
 third-party/skins/toolkit -r21 http://svn.example.com/skin-maker
+$
 </screen>
     </informalexample>
 
+    <para>In the previous example, three externals have been defined.
+      The first is <quote>unpinned</quote>—it effectively refers
+      to the HEAD revision of its target.  The other two have specific
+      revisions declared.  Also demonstrated is the fact that lines
+      that begin with a hash (<literal>#</literal>) are treated as
+      comments and ignored by the externals definitions parsing
+      logic.</para>
+
     <para>When someone checks out a working copy of the
       <filename>calc</filename> directory referred to in the previous
       example, Subversion also continues to check out the items found
@@ -4824,9 +4834,11 @@
     <informalexample>
       <screen>
 $ svn propget svn:externals calc
+# Resources versioned elsewhere.
       http://svn.example.com/repos/sounds third-party/sounds
 -r148 http://svn.example.com/skinproj third-party/skins
 -r21  http://svn.example.com/skin-maker third-party/skins/toolkit
+$
 </screen>
     </informalexample>
 
@@ -4837,9 +4849,11 @@
     <informalexample>
       <screen>
 $ svn propget svn:externals calc
+# Resources versioned elsewhere.
 http://svn.example.com/repos/sounds third-party/sounds
 http://svn.example.com/skinproj@148 third-party/skins
 http://svn.example.com/skin-maker@21 third-party/skins/toolkit
+$
 </screen>
     </informalexample>
 
@@ -4991,6 +5005,7 @@
     <informalexample>
       <screen>
 $ svn propget svn:externals calc
+# Resources versioned elsewhere.
 ^/sounds third-party/sounds
 /skinproj at 148 third-party/skins
 //svn.example.com/skin-maker at 21 third-party/skins/toolkit