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

cmpilato noreply at red-bean.com
Tue May 6 00:30:57 CDT 2008


Author: cmpilato
Date: Tue May  6 00:30:56 2008
New Revision: 3067

Log:
Enter copyedit tweaks for Appendix B.

Modified:
   trunk/src/en/book/appb-svn-for-cvs-users.xml

Modified: trunk/src/en/book/appb-svn-for-cvs-users.xml
==============================================================================
--- trunk/src/en/book/appb-svn-for-cvs-users.xml	(original)
+++ trunk/src/en/book/appb-svn-for-cvs-users.xml	Tue May  6 00:30:56 2008
@@ -3,7 +3,7 @@
 
   <para>This appendix is a guide for CVS users new to Subversion.
     It's essentially a list of differences between the two systems
-    as <quote>viewed from 10,000 feet</quote>.  For each section, we
+    as <quote>viewed from 10,000 feet.</quote>  For each section, we
     provide backreferences to relevant chapters when
     possible.</para>
 
@@ -21,7 +21,7 @@
   <sect1 id="svn.forcvs.revnums">
     <title>Revision Numbers Are Different Now</title>
 
-    <para>In CVS, revision numbers are per-file.  This is because CVS
+    <para>In CVS, revision numbers are per file.  This is because CVS
       stores its data in RCS files; each file has a corresponding RCS
       file in the repository, and the repository is roughly laid out
       according to the structure of your project tree.</para>
@@ -35,18 +35,18 @@
       looked after the 54th commit).</para>
 
     <para>Technically, it's not valid to talk about <quote>revision 5
-      of <filename>foo.c</filename></quote>.  Instead, one would say
+      of <filename>foo.c</filename>.</quote>  Instead, one would say
       <quote><filename>foo.c</filename> as it appears in revision
-      5</quote>.  Also, be careful when making assumptions about the
+      5.</quote>  Also, be careful when making assumptions about the
       evolution of a file.  In CVS, revisions 5 and 6 of
       <filename>foo.c</filename> are always different.  In Subversion,
       it's most likely that <filename>foo.c</filename> did
       <emphasis>not</emphasis> change between revisions 5 and
       6.</para>
 
-    <para>Similarly, in CVS a tag or branch is an annotation on the
-      file, or on the version information for that individual file,
-      whereas in Subversion a tag or branch is a copy of an entire
+    <para>Similarly, in CVS, a tag or branch is an annotation on the
+      file or on the version information for that individual file,
+      whereas in Subversion, a tag or branch is a copy of an entire
       tree (by convention, into the <filename>/branches</filename>
       or <filename>/tags</filename> directories that appear at the top
       level of the repository, beside <filename>/trunk</filename>). In
@@ -91,7 +91,7 @@
         <para>Directories aren't dumb containers anymore; they have
           revision numbers like files.  (Or more properly, it's
           correct to talk about <quote>directory
-          <filename>foo/</filename> in revision 5</quote>.)</para>
+          <filename>foo/</filename> in revision 5.</quote>)</para>
       </listitem>
     </itemizedlist>
 
@@ -102,7 +102,7 @@
 
     <para>From a theoretical point of view, we define <quote>revision
       5 of directory <filename>foo</filename></quote> to mean a
-      specific collection of directory-entries and properties.  Now
+      specific collection of directory entries and properties.  Now
       suppose we start adding and removing files from
       <filename>foo</filename>, and then commit.  It would be a lie
       to say that we still have revision 5 of
@@ -125,11 +125,11 @@
     <para>Similarly, a problem arises if you attempt to commit
       property changes on a directory.  Normally, the commit would
       bump the working directory's local revision number.  But again,
-      that would be a lie, because there may be adds or deletes that
+      that would be a lie, as there may be adds or deletes that
       the directory doesn't yet have, because no update has happened.
       <emphasis>Therefore, you are not allowed to commit
-      property-changes on a directory unless the directory is
-      up-to-date.</emphasis></para>
+      property changes on a directory unless the directory is
+      up to date.</emphasis></para>
 
     <para>For more discussion about the limitations of directory
       versioning, see <xref linkend="svn.basic.in-action.mixedrevs"/>.</para>
@@ -152,7 +152,7 @@
       serves the same purpose as the <filename>CVS</filename>
       directory, except that it also stores read-only,
       <quote>pristine</quote> copies of your files.  This allows you
-      to do many things off-line:</para>
+      to do much things offline:</para>
     
     <variablelist>
       
@@ -185,12 +185,12 @@
     <para>Also, the cached pristine files allow the Subversion client
       to send differences when committing, which CVS cannot do.</para>
 
-    <para>The last subcommand in the list is new; it will not only
-      remove local changes, but it will un-schedule operations such as
-      adds and deletes.  It's the preferred way to revert a file;
-      running <command>rm file; svn update</command> will still work, but
-      it blurs the purpose of updating.  And, while we're on this
-      subject…
+    <para>The last subcommand in the list—<command>svn
+      revert</command>—is new.  It will not only remove local
+      changes, but it will also unschedule operations such as adds and
+      deletes.  While deleting the file and then running <command>svn
+      update</command> will still work, doing so distorts the true
+      purpose of updating.  And, while we're on this subject…
 
     </para>
 
@@ -202,13 +202,13 @@
   <sect1 id="svn.forcvs.status-vs-update">
     <title>Distinction Between Status and Update</title>
 
-    <para>In Subversion, we've tried to erase a lot of the confusion
+    <para>Subversion attempts to erase a lot of the confusion
       between the <command>cvs status</command> and
       <command>cvs update</command> commands.</para>
 
     <para>The <command>cvs status</command> command has two purposes:
       first, to show the user any local modifications in the working
-      copy, and second, to show the user which files are out-of-date.
+      copy, and second, to show the user which files are out of date.
       Unfortunately, because of CVS's hard-to-read status output, many
       CVS users don't take advantage of this command at all.  Instead,
       they've developed a habit of running <command>cvs
@@ -218,10 +218,10 @@
       merging repository changes they may not be ready to deal
       with.</para>
 
-    <para>With Subversion, we've tried to remove this muddle by making
-      the output of <command>svn status</command> easy to read for
-      both humans and parsers.  Also, <command>svn update</command>
-      only prints information about files that are updated,
+    <para>Subversion removes this muddle by making the output of
+      <command>svn status</command> easy to read for both humans and
+      parsers.  Also, <command>svn update</command> prints only
+      information about files that are updated,
       <emphasis>not</emphasis> local modifications.</para>
 
     <sect2 id="svn.forcvs.status-vs-update.status">
@@ -252,7 +252,7 @@
         <varlistentry>
           <term><option>-N</option></term>
           <listitem>
-            <para>Run non-recursively (do not descend into
+            <para>Run nonrecursively (do not descend into
               subdirectories).</para>
           </listitem>
         </varlistentry>
@@ -282,9 +282,9 @@
 </screen>
 
       <para>In this case, two new columns appear.  The second column
-        contains an asterisk if the file or directory is out-of-date.
-        The third column shows the working-copy's revision number of the
-        item.  In the example above, the asterisk indicates that
+        contains an asterisk if the file or directory is out of date.
+        The third column shows the working copy's revision number of the
+        item.  In the previous example, the asterisk indicates that
         <filename>faces.html</filename> would be patched if we updated,
         and that <filename>bloo.png</filename> is a newly added file in
         the repository.  (The absence of any revision number next to
@@ -326,9 +326,9 @@
       <title>Update</title>
 
       <para><command>svn update</command> updates your working copy,
-        and only prints information about files that it updates.</para>
+        and prints only information about files that it updates.</para>
 
-      <para>Subversion has combined the CVS <literal>P</literal> and
+      <para>Subversion has combined CVS's <literal>P</literal> and
         <literal>U</literal> codes into just <literal>U</literal>.  When
         a merge or conflict occurs, Subversion simply prints
         <literal>G</literal> or <literal>C</literal>, rather than a
@@ -350,20 +350,20 @@
     <para>Subversion doesn't distinguish between filesystem space and
       <quote>branch</quote> space; branches and tags are ordinary
       directories within the filesystem.  This is probably the single
-      biggest mental hurdle a CVS user will need to climb.  Read all
-      about it in <xref linkend="svn.branchmerge"/>.</para>
-
+      biggest mental hurdle that a CVS user will need to cross.  Read
+      all about it in <xref linkend="svn.branchmerge"/>.</para>
 
     <warning>
+
       <para>Since Subversion treats branches and tags as ordinary
-        directories, always remember to check out the
-        <literal>trunk</literal>
-        (<literal>http://svn.example.com/repos/calc/trunk/</literal>)
-        of your project, and not the project itself
-        (<literal>http://svn.example.com/repos/calc/</literal>).  If
-        you make the mistake of checking out the project itself,
-        you'll wind up with a working copy that contains a copy of
-        your project for every branch and tag you have.
+        directories, your project's various lines of development
+        probably live in subdirectories of the main project directory.
+        So remember to check out using the URL of the subdirectory
+        that contains the particular line of development you want, not
+        the project's root URL.  If you make the mistake of checking
+        out the root of the project, you may very well wind up with a
+        working copy that contains a complete copy of your project's
+        content for each and every one of its branches and tags.
         <footnote>
           <para>That is, providing you don't run out of disk space
             before your checkout finishes.</para>
@@ -401,20 +401,26 @@
   <sect1 id="svn.forcvs.conflicts">
     <title>Conflict Resolution</title>
 
-    <para>CVS marks conflicts with in-line <quote>conflict
-      markers</quote>, and prints a <literal>C</literal> during an
-      update.  Historically, this has caused problems, because CVS
-      isn't doing enough.  Many users forget about (or don't see) the
-      <literal>C</literal> after it whizzes by on their terminal.
-      They often forget that the conflict-markers are even present,
-      and then accidentally commit files containing
-      conflict-markers.</para>
-
-    <para>Subversion solves this problem by making conflicts more
-      tangible.  It remembers that a file is in a state of conflict,
-      and won't allow you to commit your changes until you run
-      <command>svn resolved</command>.  See <xref
-      linkend="svn.tour.cycle.resolve"/> for more details.</para>
+    <para>CVS marks conflicts with inline <quote>conflict
+      markers</quote>, and then prints a <literal>C</literal> during
+      an update or merge operation.  Historically, this has caused
+      problems, because CVS isn't doing enough.  Many users forget
+      about (or don't see) the <literal>C</literal> after it whizzes
+      by on their terminal.  They often forget that the conflict
+      markers are even present, and then accidentally commit files
+      containing those conflict markers.</para>
+
+    <para>Subversion solves this problem in a pair of ways.  First,
+      when a conflict occurs in a file, Subversion records the fact
+      that the file is in a state of conflict, and won't allow you to
+      commit changes to that file until you explicitly resolve the
+      conflict.  Secondly, Subversion 1.5 provides interactive
+      conflict resolution, which allows you to resolve conflicts as
+      they happen instead of having to go back and do so after the
+      update or merge operation completes.  See <xref
+      linkend="svn.tour.cycle.resolve" /> for more about conflict
+      resolution in Subversion.</para>
+
   </sect1>
 
   <!-- ================================================================= -->
@@ -427,14 +433,14 @@
       more gracefully than CVS does.  Because CVS uses RCS, it can
       only store successive full copies of a changing binary file.
       Subversion, however, expresses differences between files using a
-      binary-differencing algorithm, regardless of whether they
+      binary differencing algorithm, regardless of whether they
       contain textual or binary data.  That means that all files are
       stored differentially (compressed) in the repository.</para>
     
     <para>CVS users have to mark binary files with
-      <option>-kb</option> flags, to prevent data from being garbled
-      (due to keyword expansion and line-ending translations).  They
-      sometimes forget to do this.</para>
+      <option>-kb</option> flags in order to prevent data from being
+      garbled (due to keyword expansion and line-ending translations).
+      They sometimes forget to do this.</para>
 
     <para>Subversion takes the more paranoid route—first, it never
       performs any kind of keyword or line-ending translation unless
@@ -455,7 +461,7 @@
     <para>To determine whether a contextual merge is possible,
       Subversion examines the <literal>svn:mime-type</literal>
       property.  If the file has no <literal>svn:mime-type</literal>
-      property, or has a mime-type that is textual (e.g.
+      property, or has a mime-type that is textual (e.g.,
       <literal>text/*</literal>),
       Subversion assumes it is text.  Otherwise, Subversion assumes
       the file is binary.  Subversion also helps users by running a
@@ -477,12 +483,12 @@
 
     <para>Unlike CVS, a Subversion working copy is aware that it has
       checked out a module.  That means that if somebody changes the
-      definition of a module (e.g. adds or removes components), then a
+      definition of a module (e.g., adds or removes components), then a
       call to <command>svn update</command> will update the working
       copy appropriately, adding and removing components.</para>
 
     <para>Subversion defines modules as a list of directories within a
-      directory property:  see <xref linkend="svn.advanced.externals"/>.</para>
+      directory property; see <xref linkend="svn.advanced.externals"/>.</para>
 
   </sect1>
 
@@ -493,18 +499,18 @@
 
     <title>Authentication</title>
 
-    <para>With CVS's pserver, you are required to <quote>login</quote>
-      to the server before any read or write operation—you
-      sometimes even have to login for anonymous operations.  With a
-      Subversion repository using Apache <command>httpd</command> or
-      <command>svnserve</command> as the server, you don't provide
-      any authentication credentials at the outset—if an
-      operation that you perform requires authentication, the server
-      will challenge you for your credentials (whether those
-      credentials are username and password, a client certificate, or
-      even both).  So if your repository is world-readable, you will
-      not be required to authenticate at all for read
-      operations.</para>
+    <para>With CVS's pserver, you are required to log in to the server
+      (using the <command>cvs login</command> command) before
+      performing any read or write operation—you sometimes even
+      have to log in for anonymous operations.  With a Subversion
+      repository using Apache <command>httpd</command> or
+      <command>svnserve</command> as the server, you don't provide any
+      authentication credentials at the outset—if an operation
+      that you perform requires authentication, the server will
+      challenge you for your credentials (whether those credentials
+      are username and password, a client certificate, or even both).
+      So if your repository is world-readable, you will not be
+      required to authenticate at all for read operations.</para>
 
     <para>As with CVS, Subversion still caches your credentials on
       disk (in your <filename>~/.subversion/auth/</filename>
@@ -533,22 +539,22 @@
       an exported CVS repository, the more thorough solution involves
       transferring not just the latest snapshot of their data, but all
       the history behind it as well, from one system to another.  This
-      is an extremely difficult problem to solve that involves
-      deducing changesets in the absence of atomicity, and translating
+      is an extremely difficult problem to solve; it involves
+      deducing changesets in the absence of atomicity and translating
       between the systems' completely orthogonal branching policies,
       among other complications.  Still, there are a handful of tools
       claiming to at least partially support the ability to convert
       existing CVS repositories into Subversion ones.</para>
 
-    <para>The most popular (and likely the most mature) conversion
-      tool is cvs2svn (<ulink url="http://cvs2svn.tigris.org/"/>), a
-      Python script originally created by members of Subversion's own
-      development community.  This tool is meant to run exactly
-      once:  it scans your CVS repository multiple times and attempts
-      to deduce commits, branches, and tags as best it can.  When it
+    <para>The most popular (and most mature) conversion tool is
+      cvs2svn (<ulink url="http://cvs2svn.tigris.org/"/>), a Python
+      script originally created by members of Subversion's own
+      development community.  This tool is meant to run exactly once:
+      it scans your CVS repository multiple times and attempts to
+      deduce commits, branches, and tags as best it can.  When it
       finishes, the result is a either a Subversion repository or a
       portable Subversion dumpfile representing your code's history.
-      See the website for detailed instructions and caveats.</para>
+      See the web site for detailed instructions and caveats.</para>
 
   </sect1>
 




More information about the svnbook-dev mailing list