[svnbook commit] r2991 - trunk/src/en/book

cmpilato noreply at red-bean.com
Thu Mar 6 21:16:04 CST 2008


Author: cmpilato
Date: Thu Mar  6 21:16:03 2008
New Revision: 2991

Log:
Finish the copyedit tweaks for Chapter 3.

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

Modified: trunk/src/en/book/ch03-advanced-topics.xml
==============================================================================
--- trunk/src/en/book/ch03-advanced-topics.xml	(original)
+++ trunk/src/en/book/ch03-advanced-topics.xml	Thu Mar  6 21:16:03 2008
@@ -1847,7 +1847,7 @@
     <para>Notice that we added to our original <command>svn
       checkout</command> command line a new <option>--depth</option>
       option.  This option is present on many of Subversion's
-      subcommands, and is similar to the
+      subcommands and is similar to the
       <option>--non-recursive</option> (<option>-N</option>) and
       <option>--recursive</option> (<option>-R</option>) options.  In
       fact, it combines, improves upon, supercedes, and ultimately
@@ -1900,14 +1900,14 @@
       our book.  Fortunately, there is more to this story.  This idea
       of depth extends not just to the operations you perform with
       your Subversion client, but also as a description of a working
-      copy citizen's <firstterm>ambient depth</firstterm>—the
-      depth persistently recorded by the working copy for that item.
-      Its key strength is this very persistence, the fact that it is
-      <quote>sticky</quote>.  The working copy remembers the depth
-      you've selected for each item in it until you later change that
-      depth selection, and by default, Subversion commands operate on
-      the working copy citizens present, regardless of their selected
-      depth settings.</para>
+      copy citizen's <firstterm>ambient depth</firstterm>, which is
+      the depth persistently recorded by the working copy for that
+      item.  Its key strength is this very persistence—the fact
+      that it is <firstterm>sticky</firstterm>.  The working copy
+      remembers the depth you've selected for each item in it until
+      you later change that depth selection; by default, Subversion
+      commands operate on the working copy citizens present,
+      regardless of their selected depth settings.</para>
 
     <tip>
       <para>You can check the recorded ambient depth of a working copy
@@ -1953,7 +1953,7 @@
       <option>--non-recursive</option> (<option>-N</option>) and
       <option>--recursive</option> (<option>-R</option>) options
       behave.  This means that when operating on a working copy of
-      some depth, and requesting an operation of a shallower depth,
+      some depth, while requesting an operation of a shallower depth,
       the operation is limited to that shallower depth.  In fact, we
       can make an even more general statement: given a working copy of
       any arbitrary—even mixed—ambient depth, and a
@@ -2003,7 +2003,7 @@
       portions absent altogether (hence the <quote>sparse</quote> bit
       of the feature's name).  Here's an example of how we might build
       out a portion of one branch of our family's tree, enable full
-      recursion on another branch, and still other pieces pruned
+      recursion on another branch, and keep still other pieces pruned
       (absent from disk).</para>
 
     <screen>
@@ -2026,8 +2026,8 @@
 
     <para>Fortunately, having a complex collection of ambient depths
       in a single working copy doesn't complicate the way you interact
-      with that working copy.  You can still make, revert, display and
-      commit local modifications in your working copy without
+      with that working copy.  You can still make, revert, display,
+      and commit local modifications in your working copy without
       providing any new options (including <option>--depth</option> or
       <option>--set-depth</option>) to the relevant subcommands.  Even
       <command>svn update</command> works as it does elsewhere when no
@@ -2036,17 +2036,17 @@
       depths.</para>
 
     <para>You might at this point be wondering, <quote>So what?  When
-      would I use this?</quote>.  One scenario where this feature
+      would I use this?</quote>  One scenario where this feature
       finds utility is tied to a particular repository layout,
-      specifically where you have many related or co-dependent
+      specifically where you have many related or codependent
       projects or software modules living as siblings in a single
       repository location (<filename>trunk/project1</filename>,
       <filename>trunk/project2</filename>,
       <filename>trunk/project3</filename>, and so on).  In such
-      scenarios, it might be the case that you personally only care
+      scenarios, it might be the case that you personally care only
       about a handful of those projects—maybe some primary
       project and a few other modules on which it depends.  You can
-      checkout individual working copies of all of these things, but
+      check out individual working copies of all of these things, but
       those working copies are disjoint and, as a result, it can be
       cumbersome to perform operations across several or all of them
       at the same time.  The alternative is to use the sparse
@@ -2059,7 +2059,7 @@
       citizens.</para>
 
     <para>Subversion 1.5's implementation of shallow checkouts is
-      good, but does not support a couple of interesting behaviors.
+      good but does not support a couple of interesting behaviors.
       First, you cannot de-telescope a working copy item.  Running
       <command>svn update --set-depth empty</command> on an
       infinite-depth working copy will not have the effect of
@@ -2078,22 +2078,22 @@
     <title>Locking</title>
 
     <para>Subversion's copy-modify-merge version control model lives
-      and dies on its data merging algorithms, specifically on how
-      well those algorithms perform when trying to resolve conflicts
-      caused by multiple users modifying the same file concurrently.
-      Subversion itself provides only one such algorithm, a three-way
-      differencing algorithm which is smart enough to handle data at a
-      granularity of a single line of text.  Subversion also allows
-      you to supplement its content merge processing with external
-      differencing utilities (as described in <xref
-      linkend="svn.advanced.externaldifftools.diff3" />), some of
-      which may do an even better job, perhaps providing granularity
-      of a word or a single character of text.  But common among those
-      algorithms is that they generally work only on text files.  The
-      landscape starts to look pretty grim when you start talking
-      about content merges of nontextual file formats.  And when you
-      can't find a tool that can handle that type of merging, you
-      begin to run into problems with the copy-modify-merge
+      and dies on its data merging algorithms—specifically on
+      how well those algorithms perform when trying to resolve
+      conflicts caused by multiple users modifying the same file
+      concurrently.  Subversion itself provides only one such
+      algorithm:  a three-way differencing algorithm that is smart
+      enough to handle data at a granularity of a single line of text.
+      Subversion also allows you to supplement its content merge
+      processing with external differencing utilities (as described in
+      <xref linkend="svn.advanced.externaldifftools.diff3" />), some
+      of which may do an even better job, perhaps providing
+      granularity of a word or a single character of text.  But common
+      among those algorithms is that they generally work only on text
+      files.  The landscape starts to look pretty grim when you start
+      talking about content merges of non-textual file formats.  And
+      when you can't find a tool that can handle that type of merging,
+      you begin to run into problems with the copy-modify-merge
       model.</para>
 
    <para>Let's look at a real-life example of where this model runs
@@ -2108,9 +2108,9 @@
       the left front fender.</para>
 
     <para>Now, as is common in graphic design work, there's a change
-      in plans which causes the car's color to be a concern.  So Sally
+      in plans, which causes the car's color to be a concern.  So Sally
       updates her working copy to <literal>HEAD</literal>, fires up
-      her photo editing software, and sets about tweaking the image so
+      her photo-editing software, and sets about tweaking the image so
       that the car is now cherry red.  Meanwhile, Harry, feeling
       particularly inspired that day, decides that the image would
       have greater impact if the car also appears to have suffered
@@ -2119,24 +2119,24 @@
       manages to finish his work before Sally finishes hers, and after
       admiring the fruits of his undeniable talent, commits the
       modified image.  Shortly thereafter, Sally is finished with the
-      car's new finish, and tries to commit her changes.  But, as
-      expected, Subversion fails the commit, informing Sally that now
-      her version of the image is out of date.</para>
-
-    <para>Here's where the difficulty sets in.  Were Harry and Sally
-      making changes to a text file, Sally would simply update her
-      working copy, receiving Harry's changes in the process.  In the
-      worst possible case, they would have modified the same region of
-      the file, and Sally would have to work out by hand the proper
-      resolution to the conflict.  But these aren't text
+      car's new finish and tries to commit her changes.  But, as
+      expected, Subversion fails the commit, informing Sally that
+      her version of the image is now out of date.</para>
+
+    <para>Here's where the difficulty sets in.  If Harry and Sally
+      were making changes to a text file, Sally would simply update
+      her working copy, receiving Harry's changes in the process.  In
+      the worst possible case, they would have modified the same
+      region of the file, and Sally would have to work out by hand the
+      proper resolution to the conflict.  But these aren't text
       files—they are binary images.  And while it's a simple
       matter to describe what one would expect the results of this
       content merge to be, there is precious little chance that any
-      software exists which is smart enough to examine the common
+      software exists that is smart enough to examine the common
       baseline image that each of these graphic artists worked
       against, the changes that Harry made, and the changes that Sally
-      made, and spit out an image of a busted-up red Mustang with a
-      cracked windshield!</para>
+      made, and then spit out an image of a busted-up red Mustang with
+      a cracked windshield!</para>
 
     <para>Of course, things would have gone more smoothly if Harry and
       Sally had serialized their modifications to the image—if, say,
@@ -2153,8 +2153,8 @@
       </footnote>
       But as one's version control system is, in fact, one form of
       communication, it follows that having that software facilitate
-      the serialization of non-parallelizable editing efforts is no
-      bad thing.  This where Subversion's implementation of the
+      the serialization of nonparallelizable editing efforts is no
+      bad thing.  This is where Subversion's implementation of the
       lock-modify-unlock model steps into the spotlight.  This is
       where we talk about Subversion's <firstterm>locking</firstterm>
       feature, which is similar to the <quote>reserved
@@ -2164,7 +2164,7 @@
     <para>Subversion's locking feature serves two main
       purposes:</para>
 
-    <itemizedlist>
+    <orderedlist>
       <listitem>
         <para><emphasis>Serializing access to a versioned
           object</emphasis>.  By allowing a user to
@@ -2183,10 +2183,10 @@
           unmergeable changes that won't be committable due to eventual
           out-of-dateness.</para>
       </listitem>
-    </itemizedlist>
+    </orderedlist>
 
     <para>When referring to Subversion's locking feature, one is
-      actually talking about a fairly diverse collection of behaviors
+      actually talking about a fairly diverse collection of behaviors,
       which include the ability to lock a versioned file
       <footnote>
         <para>Subversion does not currently allow locks on directories.</para>
@@ -2199,7 +2199,7 @@
       larger locking feature.</para>
 
     <sidebar id="svn.advanced.locking.meanings">
-      <title>The three meanings of <quote>lock</quote></title>
+      <title>The Three Meanings of <quote>Lock</quote></title>
 
       <para>In this section, and almost everywhere in this book, the
         words <quote>lock</quote> and <quote>locking</quote> describe
@@ -2221,8 +2221,9 @@
         used internally by the Berkeley DB backend to prevent clashes
         between multiple programs trying to access the database.  This
         is the sort of lock whose unwanted persistence after an error
-        can cause a repository to be <quote>wedged</quote>, as
-        described in <xref linkend="svn.reposadmin.maint.recovery"/>.</para> 
+        can cause a repository to be <quote>wedged,</quote> as
+        described in <xref linkend="svn.reposadmin.maint.recovery"
+        />.</para>
 
       <para>You can generally forget about these other kinds of locks
         until something goes wrong that requires you to care about
@@ -2234,10 +2235,10 @@
 
     <!-- =============================================================== -->
     <sect2 id="svn.advanced.locking.creation">
-      <title>Creating locks</title>
+      <title>Creating Locks</title>
       
       <para>In the Subversion repository, a
-        <firstterm>lock</firstterm> is a piece of metadata which
+        <firstterm>lock</firstterm> is a piece of metadata that
         grants exclusive access to one user to change a file.  This
         user is said to be the <firstterm>lock owner</firstterm>.
         Each lock also has a unique identifier, typically a long
@@ -2253,7 +2254,7 @@
         lock it is using.</para>
       
       <para>To demonstrate lock creation, let's refer back to our
-        example of multiple graphic designers working with on the same
+        example of multiple graphic designers working on the same
         binary image files.  Harry has decided to change a JPEG image.
         To prevent other people from committing changes to the file
         while he is modifying it (as well as alerting them that he is
@@ -2282,7 +2283,7 @@
       <para>Secondly, the lock attempt succeeded.  This means that the
         file wasn't already locked, and that Harry had the latest
         version of the file.  If Harry's working copy of the file had
-        been out-of-date, the repository would have rejected the
+        been out of date, the repository would have rejected the
         request, forcing Harry to <command>svn update</command> and
         reattempt the locking command.  The locking command would also
         have failed if the file had already been locked by someone
@@ -2321,18 +2322,18 @@
 $
 </screen>
 
-      <para>That the <command>svn info</command> command, which does
-        not contact the repository when run against working copy
-        paths, can display the lock token reveals an important fact
-        about lock tokens—that they are cached in the working
-        copy.  The presence of the lock token is critical.  It gives
-        the working copy authorization to make use of the lock later
-        on.  Also, the <command>svn status</command> command shows a
-        <literal>K</literal> next to the file (short for locKed),
-        indicating that the lock token is present.</para>
+      <para>The fact that the <command>svn info</command> command,
+        which does not contact the repository when run against working
+        copy paths, can display the lock token reveals an important
+        piece of information about those tokens:  they are cached in
+        the working copy.  The presence of the lock token is critical.
+        It gives the working copy authorization to make use of the
+        lock later on.  Also, the <command>svn status</command>
+        command shows a <literal>K</literal> next to the file (short
+        for locKed), indicating that the lock token is present.</para>
 
       <sidebar>
-        <title>Regarding lock tokens</title>
+        <title>Regarding Lock Tokens</title>
 
         <para>A lock token isn't an authentication token, so much as
           an <emphasis>authorization</emphasis> token.  The token
@@ -2375,7 +2376,7 @@
 
       <para>But Harry, after touching up the banana's shade of yellow,
         is able to commit his changes to the file.  That's because he
-        authenticates as the lock owner, and also because his working
+        authenticates as the lock owner and also because his working
         copy holds the correct lock token:</para>
 
       <screen>
@@ -2394,18 +2395,18 @@
         present in working copy.  This is the standard behavior of
         <command>svn commit</command>—it searches the working
         copy (or list of targets, if you provide such a list) for
-        local modifications, and sends all the lock tokens it
+        local modifications and sends all the lock tokens it
         encounters during this walk to the server as part of the
         commit transaction.  After the commit completes successfully,
         all of the repository locks that were mentioned are
         released—<emphasis>even on files that weren't
         committed</emphasis>.  This is meant to discourage users from
-        being sloppy about locking, or from holding locks for too
-        long.  If Harry haphazardly locks thirty files in a directory
-        named <filename>images</filename> because he's unsure of which
-        files he needs to change, yet only only changes four of those
-        files, when he runs <command>svn commit images</command>, the
-        process will still release all thirty locks.</para>
+        being sloppy about locking or from holding locks for too long.
+        If Harry haphazardly locks 30 files in a directory named
+        <filename>images</filename> because he's unsure of which files
+        he needs to change, yet changes only 4 of those files, when he
+        runs <command>svn commit images</command>, the process will
+        still release all 30 locks.</para>
 
       <para>This behavior of automatically releasing locks can be
         overridden with the <option>--no-unlock</option> option to
@@ -2429,7 +2430,7 @@
 
     <!-- =============================================================== -->
     <sect2 id="svn.advanced.locking.discovery">
-      <title>Discovering locks</title>
+      <title>Discovering Locks</title>
 
       <para>When a commit fails due to someone else's locks, it's
         fairly easy to learn about them.  The easiest of
@@ -2445,10 +2446,10 @@
 </screen>
 
       <para>In this example, Sally can see not only that her copy of
-        <filename>foo.h</filename> is out-of-date, but that one of the
+        <filename>foo.h</filename> is out of date, but that one of the
         two modified files she plans to commit is locked in the
         repository.  The <literal>O</literal> symbol stands for
-        <quote>Other</quote>, meaning that a lock exists on the file,
+        <quote>Other,</quote> meaning that a lock exists on the file
         and was created by somebody else.  If she were to attempt a
         commit, the lock on <filename>raisin.jpg</filename> would
         prevent it.  Sally is left wondering who made the lock, when,
@@ -2490,7 +2491,7 @@
 
       <para>So in this particular example, Sally can see that Harry
         locked the file on February 16th to <quote>make a quick
-        tweak</quote>.  It being June, she suspects that he probably
+        tweak.</quote>  It being June, she suspects that he probably
         forgot all about the lock.  She might phone Harry to complain
         and ask him to release the lock.  If he's unavailable, she
         might try to forcibly break the lock herself or ask an
@@ -2500,14 +2501,13 @@
 
     <!-- =============================================================== -->
     <sect2 id="svn.advanced.locking.break-steal">
-      <title>Breaking and stealing locks</title>
+      <title>Breaking and Stealing Locks</title>
 
       <para>A repository lock isn't sacred—in Subversion's
         default configuration state, locks can be released not only by
-        the person who created them, but by anyone at all.  When
-        somebody other than the original lock creator destroys a lock,
-        we refer to this as <firstterm>breaking</firstterm> the
-        lock.</para>
+        the person who created them, but by anyone.  When somebody
+        other than the original lock creator destroys a lock, we refer
+        to this as <firstterm>breaking the lock</firstterm>.</para>
 
       <para>From the administrator's chair, it's simple to break
         locks.  The <command>svnlook</command>
@@ -2541,8 +2541,8 @@
 
       <para>The more interesting option is allowing users to break
         each other's locks over the network.  To do this, Sally simply
-        needs to pass the <option>--force</option> to the unlock
-        command:</para>
+        needs to pass the <option>--force</option> to the <command>svn
+        unlock</command> command:</para>
 
       <screen>
 $ svn status -u
@@ -2641,9 +2641,9 @@
           particular, the <filename>pre-lock</filename> and
           <filename>pre-unlock</filename> hooks allow administrators
           to decide when lock creation and lock releases are allowed
-          to happen.  Depending on whether or not a lock already
-          exists, these two hooks can decide whether or not to allow a
-          certain user to break or steal a lock.  The
+          to happen.  Depending on whether a lock already exists,
+          these two hooks can decide whether to allow a certain user
+          to break or steal a lock.  The
           <filename>post-lock</filename> and
           <filename>post-unlock</filename> hooks are also available,
           and can be used to send email after locking actions.  To
@@ -2670,7 +2670,7 @@
         --show-updates</command>, so she has no idea that Harry has
         already locked the file.  She spends hours editing the file,
         and when she tries to commit her change, she discovers that
-        either the file is locked or that she's out-of-date.
+        either the file is locked or that she's out of date.
         Regardless, her changes aren't mergeable with Harry's.  One of
         these two people has to throw away their work, and a lot of
         time has been wasted.</para>
@@ -2678,7 +2678,7 @@
       <para>Subversion's solution to this problem is to provide a
         mechanism to remind users that a file ought to be locked
         <emphasis>before</emphasis> the editing begins.  The mechanism
-        is a special property, <literal>svn:needs-lock</literal>.  If
+        is a special property:  <literal>svn:needs-lock</literal>.  If
         that property is attached to a file (regardless of its value,
         which is irrelevant), then Subversion will try to use
         filesystem-level permissions to make the file read-only—unless,
@@ -2716,12 +2716,12 @@
       <tip>
         <para>Users and administrators alike are encouraged to attach
           the <literal>svn:needs-lock</literal> property to any file
-          which cannot be contextually merged.  This is the primary
+          that cannot be contextually merged.  This is the primary
           technique for encouraging good locking habits and preventing
           wasted effort.</para>
       </tip>
 
-      <para>Note that this property is a communication tool which
+      <para>Note that this property is a communication tool that
         works independently from the locking system.  In other words,
         any file can be locked, whether or not this property is
         present.  And conversely, the presence of this property
@@ -2754,7 +2754,7 @@
     <para>Sometimes it is useful to construct a working copy that is
       made out of a number of different checkouts.  For example, you
       may want different subdirectories to come from different
-      locations in a repository, or perhaps from different
+      locations in a repository or perhaps from different
       repositories altogether.  You could certainly set up such a
       scenario by hand—using <command>svn checkout</command> to
       create the sort of nested working copy structure you are trying
@@ -2772,7 +2772,7 @@
       <command>svn propset</command> or <command>svn
       propedit</command> (see <xref linkend="svn.advanced.props.manip"
       />).  It can be set on any versioned directory, and its value is
-      a multi-line table of subdirectories (relative to the versioned
+      a multiline table of subdirectories (relative to the versioned
       directory on which the property is set), optional revision
       flags, and fully qualified, absolute Subversion repository
       URLs.</para>
@@ -2788,16 +2788,16 @@
       property is that once it is set on a versioned directory,
       everyone who checks out a working copy with that directory also
       gets the benefit of the externals definition.  In other words,
-      once one person has made the effort to define those nested
-      working copy checkouts, no one else has to
-      bother—Subversion will, upon checkout of the original
-      working copy, also check out the external working copies.</para>
+      once one person has made the effort to define the nested working
+      copy structure, no one else has to bother—Subversion will,
+      after checking out the original working copy, automatically also
+      check out the external working copies.</para>
 
     <warning>
       <para>The relative target subdirectories of externals
-        definitions <emphasis>must not</emphasis> already exist on your or other users'
-        systems—Subversion will create them when it checks out
-        the external working copy.</para>
+        definitions <emphasis>must not</emphasis> already exist on
+        your or other users' systems—Subversion will create them
+        when it checks out the external working copy.</para>
     </warning>
 
     <para>Note the previous externals definition example.  When
@@ -2842,24 +2842,6 @@
         propset</command>.</para>
     </tip>
 
-    <tip>
-      <para>You should seriously consider using explicit revision
-        numbers in all of your externals definitions.  Doing so means
-        that you get to decide when to pull down a different snapshot
-        of external information, and exactly which snapshot to pull.
-        Besides avoiding the surprise of getting changes to
-        third-party repositories that you might not have any control
-        over, using explicit revision numbers also means that as you
-        backdate your working copy to a previous revision, your
-        externals definitions will also revert to the way they looked
-        in that previous revision, which in turn means that the
-        external working copies will be updated to match the way
-        <emphasis>they</emphasis> looked back when your repository was
-        at that previous revision.  For software projects, this could
-        be the difference between a successful and a failed build of
-        an older snapshot of your complex codebase.</para> 
-    </tip>
-
     <para>The <command>svn status</command> command also recognizes
       externals definitions, displaying a status code of
       <literal>X</literal> for the <firstterm>disjoint</firstterm> (or
@@ -2872,12 +2854,12 @@
       Subversion is less than ideal, though.  First, an
       externals definition can only point to directories, not files.
       Second, the externals definition cannot point to relative paths
-      (paths like <filename>../../skins/myskin</filename>).  Third, the
+      (such as <filename>../../skins/myskin</filename>).  Third, 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).  And Subversion still only truly
-      operates on non-disjoint working copies.  So, for example, if
+      operates on nondisjoint working copies.  So, for example, if
       you want to commit changes that you've made in one or more of
       those external working copies, you must run <command>svn
       commit</command> explicitly on those working
@@ -2893,7 +2875,7 @@
       have a top-level directory named
       <filename>my-project</filename>, and you've created an externals
       definition on one of its subdirectories
-      (<filename>my-project/some-dir</filename>) which tracks the
+      (<filename>my-project/some-dir</filename>) that tracks the
       latest revision of another of its subdirectories
       (<filename>my-project/external-dir</filename>).</para>
 
@@ -2952,6 +2934,24 @@
       externals definitions will <emphasis>not</emphasis> also be
       re-parented.</para>
 
+    <tip>
+      <para>You should seriously consider using explicit revision
+        numbers in all of your externals definitions.  Doing so means
+        that you get to decide when to pull down a different snapshot
+        of external information, and exactly which snapshot to pull.
+        Besides avoiding the surprise of getting changes to
+        third-party repositories that you might not have any control
+        over, using explicit revision numbers also means that as you
+        backdate your working copy to a previous revision, your
+        externals definitions will also revert to the way they looked
+        in that previous revision, which in turn means that the
+        external working copies will be updated to match the way
+        <emphasis>they</emphasis> looked back when your repository was
+        at that previous revision.  For software projects, this could
+        be the difference between a successful and a failed build of
+        an older snapshot of your complex codebase.</para> 
+    </tip>
+
     <para>Finally, there might be times when you would prefer that
       <command>svn</command> subcommands would not recognize, or
       otherwise operate upon, the external working copies.   In those instances,
@@ -2965,22 +2965,22 @@
   <sect1 id="svn.advanced.pegrevs">
     <title>Peg and Operative Revisions</title>
 
-    <para>We copy, move, rename, and
-      completely replace files and directories on our computers all
-      the time.  And your version control system shouldn't get in the
-      way of your doing these things with your version-controlled
-      files and directories, either.  Subversion's file management
-      support is quite liberating, affording almost as much
-      flexibility for versioned files as you'd expect when
-      manipulating your unversioned ones.  But that flexibility means
-      that across the lifetime of your repository, a given versioned
-      object might have many paths, and a given path might represent
-      several entirely different versioned objects.  And this
-      introduces a certain level of complexity to your interactions
-      with those paths and objects.</para>
+    <para>We copy, move, rename, and completely replace files and
+      directories on our computers all the time.  And your version
+      control system shouldn't get in the way of your doing these
+      things with your version-controlled files and directories,
+      either.  Subversion's file management support is quite
+      liberating, affording almost as much flexibility for versioned
+      files as you'd expect when manipulating your unversioned ones.
+      But that flexibility means that across the lifetime of your
+      repository, a given versioned object might have many paths, and
+      a given path might represent several entirely different
+      versioned objects.  This introduces a certain level of
+      complexity to your interactions with those paths and
+      objects.</para>
 
     <para>Subversion is pretty smart about noticing when an object's
-      version history includes such <quote>changes of address</quote>.
+      version history includes such <quote>changes of address.</quote>
       For example, if you ask for the revision history log of a
       particular file that was renamed last week, Subversion happily
       provides all those logs—the revision in which the rename
@@ -2993,9 +2993,9 @@
       is deleted from version control, and then a new directory or
       file is created with the same name and added to version control.
       The thing you deleted and the thing you later added aren't the
-      same thing.  They merely happen to have had the same path,
-      <filename>/trunk/object</filename> for example.  What, then,
-      does it mean to ask Subversion about the history of
+      same thing.  They merely happen to have had the same
+      path—<filename>/trunk/object</filename>, for example.
+      What, then, does it mean to ask Subversion about the history of
       <filename>/trunk/object</filename>?  Are you asking about the
       thing currently at that location, or the old thing you deleted
       from that location?  Are you asking about the operations that
@@ -3019,7 +3019,7 @@
       point, it makes sense to rename the directory to reflect the
       project's new name, so <filename>concept</filename> is renamed
       to <filename>frabnaggilywort</filename>.  Life goes on,
-      Frabnaggilywort releases a 1.0 version, and is downloaded and
+      Frabnaggilywort releases a 1.0 version and is downloaded and
       used daily by hordes of people aiming to improve their
       lives.</para>
     
@@ -3040,24 +3040,24 @@
       Subversion to work with these re-used paths can be a little like
       instructing a motorist in Chicago's West Suburbs to drive east
       down Roosevelt Road and turn left onto Main Street.  In a mere
-      twenty minutes, you can cross <quote>Main Street</quote> in
+      20 minutes, you can cross <quote>Main Street</quote> in
       Wheaton, Glen Ellyn, and Lombard.  And no, they aren't the same
       street.  Our motorist—and our Subversion—need a
       little more detail in order to do the right thing.</para>
 
     <para>In version 1.1, Subversion introduced a way for you to tell
       it exactly which Main Street you meant.  It's called the
-      <firstterm>peg revision</firstterm>, and it is a revision
-      provided to Subversion for the sole purpose of identifying a
-      unique line of history.  Because at most one versioned object
-      may occupy a path at any given time—or, more precisely, in
-      any one revision—the combination of a path and a peg
-      revision is all that is needed to refer to a specific line of
-      history.  Peg revisions are specified to the Subversion
-      command-line client using <firstterm>at syntax</firstterm>, so
-      called because the syntax involves appending an <quote>at
-      sign</quote> (<literal>@</literal>) and the peg revision to the
-      end of the path with which the revision is associated.</para>
+      <firstterm>peg revision</firstterm>, and it is provided to
+      Subversion for the sole purpose of identifying a unique line of
+      history.  Because at most, one versioned object may occupy a path
+      at any given time—or, more precisely, in any one
+      revision—the combination of a path and a peg revision is
+      all that is needed to refer to a specific line of history.  Peg
+      revisions are specified to the Subversion command-line client
+      using <firstterm>at syntax</firstterm>, so called because the
+      syntax involves appending an <quote>at sign</quote>
+      (<literal>@</literal>) and the peg revision to the end of the
+      path with which the revision is associated.</para>
 
     <para>But what of the <option>--revision</option>
       (<option>-r</option>) of which we've spoken so much in this
@@ -3071,20 +3071,20 @@
       Wheaton,
       <footnote>
         <para>606 N. Main Street, Wheaton, Illinois, is the home of
-          the Wheaton History Center.  Get it—<quote>History
-          Center</quote>?  It seemed appropriate….</para>
+          the Wheaton <emphasis>History</emphasis> Center.  It seemed
+          appropriate….</para>
       </footnote>
       we can think of <quote>Main Street</quote> as our path and
       <quote>Wheaton</quote> as our peg revision.  These two pieces of
-      information identify a unique path which can travelled (north or
-      south on Main Street), and will keep us from travelling up and
+      information identify a unique path that can be travelled (north or
+      south on Main Street), and they keep us from travelling up and
       down the wrong Main Street in search of our destination.  Now we
-      throw in <quote>606 N.</quote> as our operative revision, of
+      throw in <quote>606 N.</quote> as our operative revision of
       sorts, and we know <emphasis>exactly</emphasis> where to
       go.</para>
 
     <sidebar>
-      <title>The peg revision algorithm</title>
+      <title>The Peg Revision Algorithm</title>
       
       <para>The Subversion command-line performs the peg revision
         algorithm any time it needs to resolve possible ambiguities in
@@ -3099,27 +3099,23 @@
         <replaceable>PEG-REV</replaceable>, then the algorithm is as
         follows:</para>
 
-      <itemizedlist>
-        
+      <orderedlist>
         <listitem>
           <para>Locate <replaceable>item</replaceable> in the revision
             identified by <replaceable>PEG-REV</replaceable>.  There
             can be only one such object.</para>
         </listitem>
-
         <listitem>
           <para>Trace the object's history backwards (through any
             possible renames) to its ancestor in the revision
             <replaceable>OPERATIVE-REV</replaceable>.</para>
         </listitem>
-
         <listitem>
           <para>Perform the requested action on that ancestor,
             wherever it is located, or whatever its name might
             be or have been at that time.</para>
         </listitem>
-
-      </itemizedlist>
+      </orderedlist>
 
       <para>But what if <replaceable>OPERATIVE-REV</replaceable> is
         <emphasis>younger</emphasis> than
@@ -3133,20 +3129,17 @@
         performantly trace an object's history forward, anyway.  So
         the algorithm is a little different:</para>
 
-      <itemizedlist>
-        
+      <orderedlist>
         <listitem>
           <para>Locate <replaceable>item</replaceable> in the revision
             identified by <replaceable>OPERATIVE-REV</replaceable>.  There
             can be only one such object.</para>
         </listitem>
-
         <listitem>
           <para>Trace the object's history backwards (through any
             possible renames) to its ancestor in the revision
             <replaceable>PEG-REV</replaceable>.</para>
         </listitem>
-
         <listitem>
           <para>Verify that the object's location (path-wise) in
             <replaceable>PEG-REV</replaceable> is the same as it is in
@@ -3160,8 +3153,7 @@
             this usage scenario with more flexibility and
             grace.)</para>
         </listitem>
-
-      </itemizedlist>
+      </orderedlist>
 
       <para>Note that even when you don't explicitly supply a peg
         revision or operative revision, they are still present.  For
@@ -3181,7 +3173,7 @@
       <filename>frabnaggilywort</filename>.  By revision 27, we had a
       new concept, a new <filename>concept</filename> directory to
       hold it, and a new <filename>IDEA</filename> file to describe
-      it.  And then five years and twenty thousand revisions flew by,
+      it.  And then 5 years and 20 thousand revisions flew by,
       just like they would in any good romance story.</para>
 
     <para>Now, years later, we wonder what the
@@ -3191,7 +3183,7 @@
       if we are asking for the contents of whatever file lived at
       <filename>concepts/IDEA</filename> in revision 1.  Certainly
       those questions have different answers, and because of peg
-      revisions, you can ask either of them.  To find out how the
+      revisions, you can ask question.  To find out how the
       current <filename>IDEA</filename> file looked in that old
       revision, you run:</para>
 
@@ -3202,7 +3194,7 @@
 
     <para>Of course, in this example, the current
       <filename>IDEA</filename> file didn't exist yet in revision 1,
-      so Subversion gives an error.  The command above is shorthand
+      so Subversion gives an error.  The previous command is shorthand
       for a longer notation which explicitly lists a peg revision.
       The expanded notation is:</para>
 
@@ -3218,12 +3210,12 @@
       or URLs that actually have at signs in them.  After
       all, how does <command>svn</command> know whether
       <literal>news at 11</literal> is the name of a directory in my
-      tree, or just a syntax for <quote>revision 11 of
+      tree or just a syntax for <quote>revision 11 of
       <filename>news</filename></quote>?  Thankfully, while
       <command>svn</command> will always assume the latter, there is a
       trivial workaround.  You need only append an at sign to the
       end of the path, such as <literal>news at 11@</literal>.
-      <command>svn</command> only cares about the last at sign in
+      <command>svn</command> cares only about the last at sign in
       the argument, and it is not considered illegal to omit a literal
       peg revision specifier after that at sign.  This workaround
       even applies to paths that end in an at sign—you would
@@ -3251,7 +3243,7 @@
 
     <para>As you can see, the output from our operation appears to be
       correct.  The text even mentions frabbing naggily worts, so this
-      is almost certainly the file which describes the software now
+      is almost certainly the file that describes the software now
       called Frabnaggilywort.  In fact, we can verify this using the
       combination of an explicit peg revision and explicit operative
       revision.  We know that in <literal>HEAD</literal>, the
@@ -3328,18 +3320,18 @@
     <para>There are various work methodologies that developers can
       employ to keep these logical changes organized.  Some use
       separate working copies of the same repository to hold each
-      individual change-in-progress.  Others might choose to create
-      short-lived feature branches in the repository, and use a single
+      individual change in progress.  Others might choose to create
+      short-lived feature branches in the repository and use a single
       working copy that is constantly switched to point to one such
       branch or another.  Still others use <command>diff</command> and
-      <command>patch</command> tools to backup and restore uncommitted
+      <command>patch</command> tools to back up and restore uncommitted
       changes to and from patchfiles associated with each change.
       Each of these methods has its pros and cons, and to a large
       degree, the details of the changes being made heavily influence
       the methodology used to distinguish them.</para>
 
     <para>Subversion 1.5 brings a new
-      <firstterm>changelists</firstterm> feature which adds yet
+      <firstterm>changelists</firstterm> feature that adds yet
       another method to the mix.  Changelists are basically arbitrary
       labels applied to working copy files for the express purpose of
       associating multiple files together.  Users of many of Google's
@@ -3352,7 +3344,7 @@
       similarly labeled emails then becomes a simple user interface
       trick.  Many other Web 2.0 sites have similar
       mechanisms—consider the <quote>tags</quote> used by sites
-      like <ulink url="http://www.youtube.com/">YouTube</ulink> and
+      such as <ulink url="http://www.youtube.com/">YouTube</ulink> and
       <ulink url="http://www.flickr.com/">Flickr</ulink>,
       <quote>categories</quote> applied to blog posts, and so on.
       Folks understand today that organization of data is critical,
@@ -3377,12 +3369,12 @@
         association of a particular working copy file.  A changelist
         is effectively created the first time you label a file with
         that changelist; it is deleted when you remove that label from
-        the last file which had it.  Let's examine a usage scenario
-        which demonstrates these concepts.</para>
+        the last file that had it.  Let's examine a usage scenario
+        that demonstrates these concepts.</para>
 
       <para>Harry is fixing some bugs in the calculator application's
         mathematics logic.  His work leads him to change a couple of
-        files.</para>
+        files:</para>
 
       <screen>
 $ svn status
@@ -3405,7 +3397,7 @@
       <para>Harry first creates a changelist and associates with it
         the two files he's already changed.  He does this by using the
         <command>svn changelist</command> command to assign the same
-        arbitrary changelist name to those files.</para>
+        arbitrary changelist name to those files:</para>
 
       <screen>
 $ svn changelist math-fixes integer.c mathops.c
@@ -3425,7 +3417,7 @@
       <para>Harry now sets off to fix the secondary UI problem.  Since
         he knows which file he'll be changing, he assigns that path to
         a changelist, too.  Unfortunately, Harry careless assigns this
-        third file to the same changelist as the previous two files.</para>
+        third file to the same changelist as the previous two files:</para>
 
       <screen>
 $ svn changelist math-fix button.c
@@ -3439,10 +3431,10 @@
 $
 </screen>
 
-      <para>Fortunately, Harry catches his mistake.  At this point,
-        he has two options.  He can remove the changelist association
-        from button.c, and then assign a different changelist
-        name:</para>
+      <para>Fortunately, Harry catches his mistake.  At this point, he
+        has two options.  He can remove the changelist association
+        from <filename>button.c</filename>, and then assign a
+        different changelist name:</para>
 
       <screen>
 $ svn changelist --remove button.c
@@ -3479,8 +3471,8 @@
         <filename>button.c</filename>, it still shows up in the output
         of <command>svn status</command> as interesting because it has
         a changelist assignment.  Changelists can be added to and
-        removed from files at any time, regardless of whether or not
-        they contain local modifications.</para>
+        removed from files at any time, regardless of whether they
+        contain local modifications.</para>
 
       <para>Harry now fixes the user interface problem in
         <filename>button.c</filename>.</para>
@@ -3537,11 +3529,11 @@
 </screen>
 
       <para>That works okay for a few files, but what if Harry's
-        change touched twenty or thirty files?  That would be an
-        annoyingly long list of explicitly named files.  Now that he's
-        using changelists, though, Harry can avoid explicitly listing
-        the set of files in his changelist from now on, and provide
-        instead just the changelist name.</para>
+        change touched 20 or 30 files?  That would be an annoyingly
+        long list of explicitly named files.  Now that he's using
+        changelists, though, Harry can avoid explicitly listing the
+        set of files in his changelist from now on, and instead
+        provide just the changelist name:</para>
 
       <screen>
 $ svn diff --changelist math-fixes
@@ -3599,18 +3591,18 @@
           target is the directory <filename>/path/to/dir</filename>
           and its children (to infinite depth).  If you then add a
           changelist specifier to that command, only those files in
-          and under <filename>/path/to/dir</filename> which are
+          and under <filename>/path/to/dir</filename> that are
           assigned that changelist name will be considered as targets
           of the commit—the commit will not include files
           located elsewhere (such is in
-          <filename>/path/to/another-dir</filename>, regardless of
+          <filename>/path/to/another-dir</filename>), regardless of
           their changelist assignment, even if they are part of the
           same working copy as the operation's target(s).</para>
       </note>
 
       <para>Even the <command>svn changelist</command> command accepts
         the <option>--changelist</option> option.  This allows you to
-        quickly and easily rename or remove a changelist.</para>
+        quickly and easily rename or remove a changelist:</para>
 
       <screen>
 $ svn changelist math-bugs --changelist math-fixes --depth infinity
@@ -3636,8 +3628,8 @@
       <title>Changelist Limitations</title>
 
       <para>Subversion's changelist feature is a handy tool for
-        grouping working copy files, but does have a few limitations.
-        Changelist are artifacts of a particular working copy, which
+        grouping working copy files, but it does have a few limitations.
+        Changelists are artifacts of a particular working copy, which
         means that changelist assignments cannot be propogated to the
         repository or otherwise shared with other users.  Changelists
         can only be assigned to files—Subversion doesn't
@@ -3693,8 +3685,8 @@
         an authentication challenge to the client, and the client
         responds by providing <firstterm>credentials</firstterm> back
         to the server.  Once authentication is complete, the server
-        responds with the original information the client asked for.
-        Notice that this system is different from systems like CVS,
+        responds with the original information that the client asked for.
+        Notice that this system is different from systems such as CVS,
         where the client pre-emptively offers credentials (<quote>logs
         in</quote>) to the server before ever making a request.  In
         Subversion, the server <quote>pulls</quote> credentials by
@@ -3707,13 +3699,13 @@
 
       <para>If the particular network requests issued by the client
         result in a new revision being created in the repository,
-        (e.g. <command>svn commit</command>), then Subversion uses the
+        (e.g., <command>svn commit</command>), then Subversion uses the
         authenticated username associated with those requests as the
         author of the revision.  That is, the authenticated user's
         name is stored as the value of the
         <literal>svn:author</literal> property on the new revision
         (see <xref linkend="svn.ref.properties"/>).  If
-        the client was not authenticated (in other words, the server
+        the client was not authenticated (in other words, if the server
         never issued an authentication challenge), then the revision's
         <literal>svn:author</literal> property is empty.
       </para>
@@ -3725,7 +3717,7 @@
       <title>Client Credentials Caching</title>
 
       <para>Many servers are configured to require authentication on
-        every request.  This would be a big annoyance to users, if
+        every request.  This would be a big annoyance to users if
         they were forced to type their passwords over and over again.
         Fortunately, the Subversion client has a remedy for
         this—a built-in system for caching authentication
@@ -3737,7 +3729,7 @@
         or <filename>%APPDATA%/Subversion/auth/</filename> on Windows;
         see <xref linkend="svn.advanced.confarea" /> for more details
         about the runtime configuration system).  Successful
-        credentials are cached on disk, keyed on a combination of the
+        credentials are cached on disk and keyed on a combination of the
         server's hostname, port, and authentication realm.</para>
 
       <para>When the client receives an authentication challenge, it
@@ -3825,7 +3817,7 @@
 
       <para>Or, if you want to disable credential caching permanently,
         you can edit the <filename>config</filename> file in your
-        runtime configuration area, and set the
+        runtime configuration area and set the
         <option>store-auth-creds</option> option to
         <literal>no</literal>.  This will prevent the storing of
         credentials used in any Subversion interactions you perform on
@@ -3884,22 +3876,22 @@
         credentials from the client when it deems necessary; the
         client cannot <quote>push</quote> them at will.  If a username
         and/or password are passed as options, they will only be
-        presented to the server if the server requests them.
-        <footnote>
-         <para>Again, a common mistake is to misconfigure a
-           server so that it never issues an authentication challenge.
-           When users pass <option>--username</option> and
-           <option>--password</option> options to the client, they're
-           surprised to see that they're never used, i.e. new revisions
-           still appear to have been committed
-           anonymously!</para>
-        </footnote>
+        presented to the server if the server requests them.  These
+        options are typically used to authenticate as a different user
+        than Subversion would have chosen by default (such as your
+        system login name) or when trying to avoid interactive
+        prompting (such as when calling <command>svn</command> from a
+        script).</para>
 
-        These options are typically used to authenticate as a
-        different user than Subversion would have chosen by default
-        (such as your system login name), or when trying to avoid
-        interactive prompting (such as when calling
-        <command>svn</command> from a script).</para>
+      <note>
+        <para>A common mistake is to misconfigure a server so
+          that it never issues an authentication challenge.  When
+          users pass <option>--username</option> and
+          <option>--password</option> options to the client, they're
+          surprised to see that they're never used; i.e., new
+          revisions still appear to have been committed
+          anonymously!</para>
+      </note>
 
       <para>Here is a final summary that describes how a Subversion
         client behaves when it receives an authentication
@@ -3910,31 +3902,32 @@
           <para>First, the client checks whether the user specified
             any credentials as command-line options
             (<option>--username</option> and/or
-            <option>--password</option>).  If not, or if these options
-            fail to authenticate successfully, then</para> 
+            <option>--password</option>).  If so, the client will try
+            to use those credentials to authenticate against the
+            server.</para>
         </listitem>
-
         <listitem>
-          <para>the client looks up the server's hostname, port, and realm in
-            the runtime <filename>auth/</filename> area, to see if the
-            user already has the appropriate credentials cached.  If
-            not, or if the cached credentials fail to authenticate,
-            then</para>
+          <para>If no command-line credentials were provided, or the
+            provided ones were invalid, the client looks up the server's
+            hostname, port, and realm in the runtime configuration's
+            <filename>auth/</filename> area, to see if appropriate 
+            credentials are cached there.  If so, it attempts to use
+            those credentials to authenticate.</para>
         </listitem>
-
         <listitem>
-          <para>finally, the client resorts to prompting the user
-            (unless instructed not to do so via the
+          <para>Finally, if the previous mechanisms failed to
+            successfully authenticate the user against the server, the
+            client resorts to interactively prompting the user for
+            valid credentials (unless instructed not to do so via the
             <option>--non-interactive</option> option or its
             client-specific equivalents).</para>
         </listitem>
-
       </orderedlist>
 
-      <para>If the client successfully authenticates by any of the
-        methods listed above, it will attempt to cache the credentials
-        on disk (unless the user has disabled this behavior, as
-        mentioned earlier).</para>
+      <para>If the client successfully authenticates by any of these
+        methods, it will attempt to cache the credentials on disk
+        (unless the user has disabled this behavior, as mentioned
+        earlier).</para>
 
     </sect2>
 




More information about the svnbook-dev mailing list