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

cmpilato noreply at red-bean.com
Tue Mar 4 21:14:53 CST 2008


Author: cmpilato
Date: Tue Mar  4 21:14:52 2008
New Revision: 2988

Log:
Begin making copyedit changes suggested by O'Reilly.  Love the
results, but the process is putting a crick in my neck!

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	Tue Mar  4 21:14:52 2008
@@ -8,13 +8,13 @@
     check out a working copy from a Subversion repository.  You are
     comfortable with submitting and receiving changes using the
     <command>svn commit</command> and <command>svn update</command>
-    functions.  You've probably even developed a reflex which causes
+    functions.  You've probably even developed a reflex that causes
     you to run the <command>svn status</command> command almost
     unconsciously.  For all intents and purposes, you are ready to
     use Subversion in a typical environment.</para>
 
   <para>But the Subversion feature set doesn't stop at <quote>common
-    version control operations</quote>.  It has other bits of
+    version control operations.</quote>  It has other bits of
     functionality besides just communicating file and
     directory changes to and from a central repository.</para>
 
@@ -24,7 +24,7 @@
     directory versioning capabilities.  If you aren't, you'll want to
     first read <xref linkend="svn.basic" /> and <xref
     linkend="svn.tour" />.  Once you've mastered those basics and
-    consumed this chapter, you'll be a Subversion power-user!</para>
+    consumed this chapter, you'll be a Subversion power user!</para>
 
 
   <!-- ================================================================= -->
@@ -33,26 +33,26 @@
   <sect1 id="svn.tour.revs.specifiers">
     <title>Revision Specifiers</title>
 
-    <para>As you saw in <xref linkend="svn.basic.in-action.revs" />, revision
-      numbers in Subversion are pretty straightforward—integers
-      that keep getting larger as you commit more changes to your
-      versioned data.  Still, it doesn't take long before you can no
-      longer remember exactly what happened in each and every
-      revision.  Fortunately, the typical Subversion workflow doesn't
-      often demand that you supply arbitrary revisions to the
-      Subversion operations you perform.  For operations that
-      <emphasis>do</emphasis> require a revision specifier, you
-      generally supply a revision number that you saw in a commit
-      email, in the output of some other Subversion operation, or in
-      some other context that would give meaning to that particular
-      number.</para>
+    <para>As we described in <xref linkend="svn.basic.in-action.revs"
+      />, revision numbers in Subversion are pretty
+      straightforward—integers that keep getting larger as you
+      commit more changes to your versioned data.  Still, it doesn't
+      take long before you can no longer remember exactly what
+      happened in each and every revision.  Fortunately, the typical
+      Subversion workflow doesn't often demand that you supply
+      arbitrary revisions to the Subversion operations you perform.
+      For operations that <emphasis>do</emphasis> require a revision
+      specifier, you generally supply a revision number that you saw
+      in a commit email, in the output of some other Subversion
+      operation, or in some other context that would give meaning to
+      that particular number.</para>
 
     <para>But occasionally, you need to pinpoint a moment in time for
       which you don't already have a revision number memorized or
       handy.  So besides the integer revision numbers,
       <command>svn</command> allows as input some additional forms of
-      revision specifiers—<firstterm>revision keywords</firstterm>, and revision
-      dates.</para>
+      revision specifiers: <firstterm>revision keywords</firstterm>
+      and revision dates.</para>
 
     <note>
       <para>The various forms of Subversion revision specifiers can be
@@ -89,16 +89,16 @@
         <primary>PREV</primary>
       </indexterm>
 
-      <para>The Subversion client understands a number of
-        revision keywords.  These keywords can
-        be used instead of integer arguments to the
-        <option>--revision (-r)</option> switch, and are resolved into
-        specific revision numbers by Subversion:</para>
+      <para>The Subversion client understands a number of revision
+        keywords.  These keywords can be used instead of integer
+        arguments to the <option>--revision</option>
+        (<option>-r</option>) switch, and are resolved into specific
+        revision numbers by Subversion:</para>
 
       <variablelist>
         
         <varlistentry>
-          <term>HEAD</term>
+          <term><literal>HEAD</literal></term>
           <listitem>
             <para>The latest (or <quote>youngest</quote>) revision in
               the repository.</para>
@@ -106,17 +106,17 @@
         </varlistentry>
         
         <varlistentry>
-          <term>BASE</term>
+          <term><literal>BASE</literal></term>
           <listitem>
             <para>The revision number of an item in a working copy.
-              If the item has been locally modified, the <quote>BASE
-              version</quote> refers to the way the item appears
-              without those local modifications.</para>
+              If the item has been locally modified, this refers to
+              the way the item appears without those local
+              modifications.</para>
           </listitem>
         </varlistentry>
         
         <varlistentry>
-          <term>COMMITTED</term>
+          <term><literal>COMMITTED</literal></term>
           <listitem>
             <para>The most recent revision prior to, or equal to,
               <literal>BASE</literal>, in which an item changed.</para>
@@ -124,7 +124,7 @@
         </varlistentry>
         
         <varlistentry>
-          <term>PREV</term>
+          <term><literal>PREV</literal></term>
           <listitem>
             <para>The revision immediately <emphasis>before</emphasis>
               the last revision in which an item changed.
@@ -187,13 +187,13 @@
       <para>Revision numbers reveal nothing about the world outside
         the version control system, but sometimes you need to
         correlate a moment in real time with a moment in version
-        history.  To facilitate this, the <option>--revision (-r)</option>
-        option can also accept as input date specifiers wrapped in
-        curly braces (<literal>{</literal> and <literal>}</literal>).
-        Subversion accepts the standard ISO-8601 date and time
-        formats, plus a few others.  Here are some examples.
-        (Remember to use quotes around any date that contains
-        spaces.)</para>
+        history.  To facilitate this, the <option>--revision</option>
+        (<option>-r</option>) option can also accept as input date
+        specifiers wrapped in curly braces (<literal>{</literal> and
+        <literal>}</literal>).  Subversion accepts the standard
+        ISO-8601 date and time formats, plus a few others.  Here are
+        some examples.  (Remember to use quotes around any date that
+        contains spaces.)</para>
 
       <screen>
 $ svn checkout -r {2006-02-17}
@@ -233,10 +233,10 @@
           the 26th, or even earlier.  Remember that Subversion will
           find the <emphasis>most recent revision of the
           repository</emphasis> as of the date you give.  If you give
-          a date without a timestamp, like
+          a date without a timestamp, such as
           <literal>2006-11-27</literal>, Subversion assumes a time of
           00:00:00, so looking for the most recent revision won't
-          return anything on the day of the 27th.</para>
+          return anything on the 27th.</para>
 
         <para>If you want to include the 27th in your search, you can
           either specify the 27th with the time (<literal>{"2006-11-27
@@ -256,7 +256,7 @@
       <warning>
         <para>Since the timestamp of a revision is stored as an
           unversioned, modifiable property of the revision (see <xref
-          linkend="svn.advanced.props" />, revision timestamps can be
+          linkend="svn.advanced.props" />), revision timestamps can be
           changed to represent complete falsifications of true
           chronology, or even removed altogether.  Subversion's
           ability to correctly convert revision dates into real
@@ -325,29 +325,29 @@
       apply—human-readable names and anything-you-want binary
       values.  The main difference is that revision properties are not
       versioned.  In other words, if you change the value of, or
-      delete, a revision property, there's no way within the scope of
-      Subversion's functionality to recover the previous value.</para>
+      delete, a revision property, there's no way, within the scope of
+      Subversion's functionality, to recover the previous value.</para>
 
     <para>Subversion has no particular policy regarding the use of
       properties.  It asks only that you not use property names that
       begin with the prefix <literal>svn:</literal>.  That's the
       namespace that it sets aside for its own use.  And Subversion
-      does, in fact, use properties, both the versioned and
+      does, in fact, use properties—both the versioned and
       unversioned variety.  Certain versioned properties have special
-      meaning or effects when found on files and directories, or house
-      a particular bit of information about the revisions on which
-      they are found.  Certain revision properties are automatically
-      attached to revisions by Subversion's commit process, and carry
-      information about the revision.  Most of these properties are
-      mentioned elsewhere in this or other chapters as part of the
-      more general topics to which they are related.  For an
-      exhaustive list of Subversion's pre-defined properties, see
-      <xref linkend="svn.ref.properties"/>.</para>
+      meaning or effects when found on files and directories, or they
+      house a particular bit of information about the revisions on
+      which they are found.  Certain revision properties are
+      automatically attached to revisions by Subversion's commit
+      process, and they carry information about the revision.  Most of
+      these properties are mentioned elsewhere in this or other
+      chapters as part of the more general topics to which they are
+      related.  For an exhaustive list of Subversion's predefined
+      properties, see <xref linkend="svn.ref.properties" />.</para>
 
     <para>In this section, we will examine the utility—both to
-      users of Subversion, and to Subversion itself—of property
+      users of Subversion and to Subversion itself—of property
       support.  You'll learn about the property-related
-      <command>svn</command> subcommands, and how property
+      <command>svn</command> subcommands and how property
       modifications affect your normal Subversion workflow.</para>
 
     <!-- =============================================================== -->
@@ -361,8 +361,8 @@
         close to your versioned data to hang custom metadata about
         that data.</para>
 
-      <para>Say you wish to design a website that houses many digital
-        photos, and displays them with captions and a datestamp.  Now,
+      <para>Say you wish to design a web site that houses many digital
+        photos and displays them with captions and a datestamp.  Now,
         your set of photos is constantly changing, so you'd like to
         have as much of this site automated as possible.  These photos
         can be quite large, so as is common with sites of this nature,
@@ -372,30 +372,29 @@
       <para>Now, you can get this functionality using traditional
         files.  That is, you can have your
         <filename>image123.jpg</filename> and an
-        <filename>image123-thumbnail.jpg</filename> side-by-side in a
+        <filename>image123-thumbnail.jpg</filename> side by side in a
         directory.  Or if you want to keep the filenames the same, you
-        might have your thumbnails in a different directory, like
+        might have your thumbnails in a different directory, such as
         <filename>thumbnails/image123.jpg</filename>.  You can also
         store your captions and datestamps in a similar fashion, again
         separated from the original image file.  But the problem here
-        is that your collection of files grows in multiples with each
-        new photo added to the site.</para>
+        is that your collection of files multiplies with each new
+        photo added to the site.</para>
 
-      <para>Now consider the same website deployed in a way that makes
-        use of Subversion's file properties.  Imagine having a single
-        image file, <filename>image123.jpg</filename>, and then
-        properties set on that file named <literal>caption</literal>,
-        <literal>datestamp</literal>, and even
-        <literal>thumbnail</literal>.  Now your working copy directory
-        looks much more manageable—in fact, it looks to the
-        casual browser like there are nothing but image files in it.
-        But your automation scripts know better.  They know that they
-        can use <command>svn</command> (or better yet, they can use
-        the Subversion language bindings—see <xref
-        linkend="svn.developer.usingapi" />) to dig out the
-        extra information that your site needs to display without
-        having to read an index file or play path manipulation
-        games.</para>
+      <para>Now consider the same web site deployed in a way that
+        makes use of Subversion's file properties.  Imagine having a
+        single image file, <filename>image123.jpg</filename>, with
+        properties set on that file that are named
+        <literal>caption</literal>, <literal>datestamp</literal>, and
+        even <literal>thumbnail</literal>.  Now your working copy
+        directory looks much more manageable—in fact, it looks
+        to the casual browser like there are nothing but image files
+        in it.  But your automation scripts know better.  They know
+        that they can use <command>svn</command> (or better yet, they
+        can use the Subversion language bindings—see <xref
+        linkend="svn.developer.usingapi" />) to dig out the extra
+        information that your site needs to display without having to
+        read an index file or play path manipulation games.</para>
 
       <para>Custom revision properties are also frequently used.  One
         common such use is a property whose value contains an issue
@@ -405,7 +404,7 @@
         more friendly names on the revision—it might be hard to
         remember that revision 1935 was a fully tested revision.  But
         if there's, say, a <literal>test-results</literal> property on
-        that revision with a value <literal>all passing</literal>,
+        that revision with the value <literal>all passing</literal>,
         that's meaningful information to have.</para>
 
       <sidebar>
@@ -414,8 +413,8 @@
 
         <para>For all their utility, Subversion properties—or,
           more accurately, the available interfaces to them—have
-          a major shortcoming:
-          while it is a simple matter to <emphasis>set</emphasis> a custom property,
+          a major shortcoming: while it is a simple matter to
+          <emphasis>set</emphasis> a custom property,
           <emphasis>finding</emphasis> that property later is whole
           different ball of wax.</para>
 
@@ -433,12 +432,12 @@
           repository.</para>
 
         <para>For this reason, you might choose—especially in
-          the revision property use-case—to simply add your
-          metadata to the revision's log message, using some
-          policy-driven (and perhaps programmatically-enforced)
+          the revision property use case—to simply add your
+          metadata to the revision's log message using some
+          policy-driven (and perhaps programmatically enforced)
           formatting that is designed to be quickly parsed from the
           output of <command>svn log</command>.  It is quite common to
-          see in Subversion log messages the likes of:</para>
+          see the following in Subversion log messages:</para>
 
         <programlisting>
 Issue(s): IZ2376, IZ1919
@@ -466,7 +465,7 @@
         with short, human-readable values, perhaps the simplest way to
         add a new property is to specify the property name and value
         on the command line of the <command>propset</command>
-        subcommand.</para>
+        subcommand:</para>
 
       <screen>
 $ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c
@@ -479,8 +478,9 @@
         have a multi-line textual, or even binary, property value, you
         probably do not want to supply that value on the command line.
         So the <command>propset</command> subcommand takes a
-        <option>--file (-F)</option> option for specifying the name of
-        a file which contains the new property value.</para>
+        <option>--file</option> (<option>-F</option>) option for
+        specifying the name of a file that contains the new property
+        value.</para>
 
       <screen>
 $ svn propset license -F /path/to/LICENSE calc/button.c
@@ -508,7 +508,7 @@
         modify properties.  When you run the command,
         <command>svn</command> invokes your editor program on a
         temporary file that contains the current value of the property
-        (or which is empty, if you are adding a new property).  Then,
+        (or that is empty, if you are adding a new property).  Then,
         you just modify that value in your editor program until it
         represents the new value you wish to store for the property,
         save the temporary file, and then exit the editor program.  If
@@ -527,7 +527,7 @@
         subcommands, those related to properties can act on multiple
         paths at once.  This enables you to modify properties on whole
         sets of files with a single command.  For example, we could
-        have done:</para>
+        have done the following:</para>
 
       <screen>
 $ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
@@ -614,7 +614,7 @@
       <para>Remember those unversioned revision properties?  You can
         modify those, too, using the same <command>svn</command>
         subcommands that we just described.  Simply add the
-        <option>--revprop</option> command-line parameter, and specify
+        <option>--revprop</option> command line parameter and specify
         the revision whose property you wish to modify.  Since
         revisions are global, you don't need to specify a target path
         to these property-related commands so long as you are
@@ -665,7 +665,7 @@
           propedit</command> instead of <command>svn
           propset</command>.  While the end result of the commands is
           identical, the former will allow them to see the current
-          value of the property they are about to change, which helps
+          value of the property that they are about to change, which helps
           them to verify that they are, in fact, making the change
           they think they are making.  This is especially true when
           modifying unversioned revision properties.  Also, it is
@@ -688,12 +688,12 @@
         merging—cleanly or with conflicts—someone
         else's modifications into your own.</para>
 
-      <para>And as with file contents, your property changes are local
-        modifications, only made permanent when you commit them to the
+      <para>As with file contents, your property changes are local
+        modifications, made permanent only when you commit them to the
         repository with <command>svn commit</command>.  Your property
         changes can be easily unmade, too—the <command>svn
         revert</command> command will restore your files and
-        directories to their un-edited states—contents, properties,
+        directories to their unedited states—contents, properties,
         and all.  Also, you can receive interesting information about
         the state of your file and directory properties by using the
         <command>svn status</command> and <command>svn diff</command>
@@ -739,7 +739,7 @@
          
         <para>Subversion will also create, in the same directory as
           the conflicted object, a file with a
-          <filename>.prej</filename> extension which contains the
+          <filename>.prej</filename> extension that contains the
           details of the conflict.  You should examine the contents of
           this file so you can decide how to resolve the conflict.
           Until the conflict is resolved, you will see a
@@ -764,7 +764,7 @@
 
       </sidebar>
 
-      <para>You might also have noticed the non-standard way that
+      <para>You might also have noticed the nonstandard way that
         Subversion currently displays property differences.  You can
         still run <command>svn diff</command> and redirect the output
         to create a usable patch file.  The <command>patch</command>
@@ -801,8 +801,8 @@
         Subversion will automatically set the
         <literal>svn:executable</literal> property on newly added or
         imported files whose execute bit is enabled.  (See <xref
-        linkend="svn.advanced.props.special.executable" /> for more
-        about this property.)</para>
+        linkend="svn.advanced.props.special.executable" /> later in
+        this chapter for more about this property.)</para>
 
       <para>Secondly, Subversion tries to determine the file's MIME
         type.  If you've configured a
@@ -813,8 +813,8 @@
         <literal>svn:mime-type</literal> property to the MIME type it
         found.  If no mapping file is configured, or no mapping for
         your file's extension could be found, Subversion runs a very
-        basic heuristic to determine if the file contains non-textual
-        content and, if so, automatically sets the
+        basic heuristic to determine if the file contains nontextual
+        content.  If so, it automatically sets the
         <literal>svn:mime-type</literal> property on that file to
         <literal>application/octet-stream</literal> (the generic
         <quote>this is a collection of bytes</quote> MIME type).  Of
@@ -824,11 +824,12 @@
         <literal>application/x-shockwave-flash</literal>—you can
         always remove or edit that property.  (For more on
         Subversion's use of MIME types, see <xref
-        linkend="svn.advanced.props.special.mime-type" />.)</para>
+        linkend="svn.advanced.props.special.mime-type" /> later in
+        this chapter.)</para>
 
       <para>Subversion also provides, via its runtime configuration
         system (see <xref linkend="svn.advanced.confarea" />), a more
-        flexible automatic property setting feature which allows you
+        flexible automatic property setting feature that allows you
         to create mappings of filename patterns to property names and
         values.  Once again, these mappings affect adds and imports,
         and can not only override the default MIME type decision made
@@ -843,7 +844,7 @@
         <literal>svn:eol-style</literal> set to
         <literal>native</literal>, and <literal>svn:keywords</literal>
         set to <literal>Id</literal>.  Automatic property support is
-        perhaps the handiest property-related tool in the Subversion
+        perhaps the handiest property related tool in the Subversion
         toolbox.  See <xref
         linkend="svn.advanced.confarea.opts.config"/> for more about
         configuring that support.</para>
@@ -865,7 +866,7 @@
       everywhere.</para>
 
     <para>However, the same is not always true of other general classes
-      of software, or of the actual files you keep in Subversion.  For
+      of software or of the actual files you keep in Subversion.  For
       example, on a Windows machine, the definition of a <quote>text
       file</quote> would be similar to that used on a Linux box, but
       with a key difference—the character sequences used to mark
@@ -886,7 +887,7 @@
     <sect2 id="svn.advanced.props.special.mime-type">
       <title>File Content Type</title>
       
-      <para>Subversion joins the ranks of the many applications which
+      <para>Subversion joins the ranks of the many applications that
         recognize and make use of Multipurpose Internet Mail
         Extensions (MIME) content types.  Besides being a
         general-purpose storage location for a file's content type,
@@ -902,12 +903,12 @@
           file by the file's name, specifically its file extension.
           For example, files whose names end in
           <filename>.txt</filename> are generally assumed to be
-          human-readable, able to be understood by simple perusal
+          human-readable; that is, able to be understood by simple perusal
           rather than requiring complex processing to decipher.  Files
           whose names end in <filename>.png</filename>, on the other
           hand, are assumed to be of the Portable Network Graphics
           type—not human-readable at all, and sensible only when
-          interpreted by software which understands the PNG format and
+          interpreted by software that understands the PNG format and
           can render the information in that format as a raster
           image.</para>
 
@@ -934,22 +935,22 @@
           doubt on the mapping between a file's name and its content.
           With information being served across networks and generated
           dynamically by server-side scripts, there was often no real
-          file per se, and therefore no file name.  Web
+          file per se, and therefore no filename.  Web
           servers, for example, needed some other way to tell browsers
           what they were downloading so the browser could do something
           intelligent with that information, whether that was to
           display the data using a program registered to handle that
-          data type, or to prompt the user for where on the client
+          data type or to prompt the user for where on the client
           machine to store the downloaded data.</para>
 
         <para>Eventually, a standard emerged for, among other things,
           describing the contents of a data stream.  In 1996, RFC2045
-          was published, the first of five RFCs describing MIME.  It
-          describes the concept of media types and subtypes, and
-          recommends a syntax for the representation of those types.
-          Today, MIME media types—or <quote>MIME
+          was published.  It was the first of five RFCs describing
+          MIME.  It describes the concept of media types and subtypes
+          and recommends a syntax for the representation of those
+          types.  Today, MIME media types—or <quote>MIME
           types</quote>—are used almost universally across
-          e-mail applications, Web servers, and other software as the
+          email applications, web servers, and other software as the
           de facto mechanism for clearing up the file content
           confusion.</para>
 
@@ -958,10 +959,10 @@
       <para>For example, one of the benefits that Subversion typically
         provides is contextual, line-based merging of changes received
         from the server during an update into your working file.  But
-        for files containing non-textual data, there is often no
-        concept of a <quote>line</quote>.  So, for versioned files
+        for files containing nontextual data, there is often no
+        concept of a <quote>line.</quote>  So, for versioned files
         whose <literal>svn:mime-type</literal> property is set to a
-        non-textual MIME type (generally, something that doesn't begin
+        nontextual MIME type (generally, something that doesn't begin
         with <literal>text/</literal>, though there are exceptions),
         Subversion does not attempt to perform contextual merges
         during updates.  Instead, any time you have locally modified a
@@ -980,14 +981,14 @@
           to a value that does not indicate textual file contents, can
           cause some unexpected behaviors with respect to other
           properties.  For example, since the idea of line endings
-          (and therefore, line ending conversion) makes no sense when
-          applied to non-textual files, Subversion will prevent you
+          (and therefore, line-ending conversion) makes no sense when
+          applied to nontextual files, Subversion will prevent you
           from setting the <literal>svn:eol-style</literal> property
           on such files.  This is obvious when attempted on a single
           file target—<command>svn propset</command> will error
           out.  But it might not be as clear if you perform a
           recursive property set, where Subversion will silently skip
-          over files which it deems unsuitable for a given
+          over files that it deems unsuitable for a given
           property.</para>
       </warning>
 
@@ -995,8 +996,8 @@
         <literal>mime-types-file</literal> runtime configuration
         parameter, which identifies the location of a MIME types
         mapping file.  Subversion will consult this mapping file to
-        determine, for newly added and imported files, their MIME
-        type.</para>
+        determine the MIME type of newly added and imported
+        files.</para>
 
       <para>Also, if the <literal>svn:mime-type</literal> property is
         set, then the Subversion Apache module will use its value to
@@ -1016,7 +1017,7 @@
         permission bit.  This bit usually defaults to being disabled,
         and must be explicitly enabled by the user for each file that
         needs it.  But it would be a monumental hassle to have to
-        remember exactly which files in freshly checked-out working
+        remember exactly which files in a freshly checked-out working
         copy were supposed to have their executable bits toggled on,
         and then to have to do that toggling.  So, Subversion provides
         the <literal>svn:executable</literal> property as a way to
@@ -1029,8 +1030,8 @@
         NTFS.
         <footnote>
           <para>The Windows filesystems use file extensions (such as
-            <literal>.EXE</literal>, <literal>.BAT</literal>, and
-            <literal>.COM</literal>) to denote executable
+            <filename>.EXE</filename>, <filename>.BAT</filename>, and
+            <filename>.COM</filename>) to denote executable
             files.</para>
         </footnote>
         Also, although it has no defined values, Subversion will force
@@ -1047,7 +1048,7 @@
       <para>Unless otherwise noted using a versioned file's
         <literal>svn:mime-type</literal> property, Subversion
         assumes the file contains human-readable data.  Generally
-        speaking, Subversion only uses this knowledge to determine
+        speaking, Subversion uses this knowledge only to determine
         if contextual difference reports for that file are
         possible.  Otherwise, to Subversion, bytes are bytes.</para>
       
@@ -1056,7 +1057,7 @@
         markers</firstterm> used in your files.  Unfortunately,
         different operating systems have different conventions about
         which character sequences represent the end of a line of text
-        in a file.  For example, the usual line ending token used by
+        in a file.  For example, the usual line-ending token used by
         software on the Windows platform is a pair of ASCII control
         characters—a carriage return (<literal>CR</literal>)
         followed by a line feed (<literal>LF</literal>).  Unix
@@ -1064,24 +1065,23 @@
         character to denote the end of a line.</para>
 
       <para>Not all of the various tools on these operating systems
-        understand files that contain line endings
-        in a format that differs from the <firstterm>native line
-        ending style</firstterm> of the operating system on which
-        they are running.  So, typically, Unix programs
-        treat the <literal>CR</literal> character present in Windows
-        files as a regular character (usually rendered as
-        <literal>^M</literal>), and Windows programs combine
-        all of the lines of a Unix file into one giant line because
-        no carriage return-linefeed (or <literal>CRLF</literal>)
-        character combination was found to denote the ends of
-        the lines.</para>
+        understand files that contain line endings in a format that
+        differs from the <firstterm>native line-ending
+        style</firstterm> of the operating system on which they are
+        running.  So, typically, Unix programs treat the
+        <literal>CR</literal> character present in Windows files as a
+        regular character (usually rendered as <literal>^M</literal>),
+        and Windows programs combine all of the lines of a Unix file
+        into one giant line because no carriage return-linefeed (or
+        <literal>CRLF</literal>) character combination was found to
+        denote the ends of the lines.</para>
 
       <para>This sensitivity to foreign EOL markers can be
         frustrating for folks who share a file across different
         operating systems.  For example, consider a source code
         file, and developers that edit this file on both Windows and
-        Unix systems.  If all the developers always use tools which
-        preserve the line ending style of the file, no problems
+        Unix systems.  If all the developers always use tools that
+        preserve the line-ending style of the file, no problems
         occur.</para>
 
       <para>But in practice, many common tools either fail to
@@ -1096,7 +1096,7 @@
         original quite literally on every line!  Prior to committing
         his changes, the user has two choices.  Either he can use a
         conversion utility to restore the modified file to the same
-        line ending style that it was in before his edits were made.
+        line-ending style that it was in before his edits were made.
         Or, he can simply commit the file—new EOL markers and
         all.</para>
 
@@ -1104,7 +1104,7 @@
         and unnecessary modifications to committed files.  Wasted
         time is painful enough.  But when commits change every line
         in a file, this complicates the job of determining which of
-        those lines were changed in a non-trivial way.  Where was
+        those lines were changed in a nontrivial way.  Where was
         that bug really fixed?  On what line was a syntax error
         introduced?</para>
 
@@ -1112,7 +1112,7 @@
         <literal>svn:eol-style</literal> property.  When this
         property is set to a valid value, Subversion uses it to
         determine what special processing to perform on the file so
-        that the file's line ending style isn't flip-flopping with
+        that the file's line-ending style isn't flip-flopping with
         every commit that comes from a different operating
         system.  The valid values are:</para>
 
@@ -1128,7 +1128,7 @@
               <literal>svn:eol-style</literal> property set to
               <literal>native</literal>, that file will contain
               <literal>CRLF</literal> EOL markers.  A Unix user
-              checking out a working copy which contains the same
+              checking out a working copy that contains the same
               file will see <literal>LF</literal> EOL markers in his
               copy of the file.</para>
 
@@ -1160,10 +1160,10 @@
           <listitem>
             <para>This causes the file to contain
               <literal>CR</literal> characters for EOL markers,
-              regardless of the operating system in use.  This line
-              ending style is not very common.  It was used on older
-              Macintosh platforms (on which Subversion doesn't even
-              run).</para>
+              regardless of the operating system in use.  This
+              line-ending style is not very common.  It was used on
+              older Macintosh platforms (on which Subversion doesn't
+              even run).</para>
           </listitem>
         </varlistentry>
       </variablelist>
@@ -1177,12 +1177,12 @@
   <sect1 id="svn.advanced.props.special.ignore">
     <title>Ignoring Unversioned Items</title>
 
-    <para>In any given working copy there is a good chance that
+    <para>In any given working copy, there is a good chance that
       alongside all those versioned files and directories are other
-      files and directories which are neither versioned nor intended
+      files and directories that are neither versioned nor intended
       to be.  Text editors litter directories with backup files.
       Software compilers generate intermediate—or even
-      final—files which you typically wouldn't bother to
+      final—files that you typically wouldn't bother to
       version.  And users themselves drop various other files and
       directories wherever they see fit, often in version control
       working copies.</para>
@@ -1194,7 +1194,7 @@
       unversioned trees.  But these not-to-be-versioned files and
       directories can cause some annoyance for Subversion users.  For
       example, because the <command>svn add</command> and <command>svn
-      import</command> commands act recursively by default, and don't
+      import</command> commands act recursively by default and don't
       know which files in a given tree you do and don't wish to
       version, it's easy to accidentally add stuff to version control
       that you didn't mean to.  And because <command>svn
@@ -1204,30 +1204,30 @@
       these things exist.</para>
 
     <para>So Subversion provides two ways for telling it which files
-      you would prefer that it simply disregard.  One of the ways
+      you would prefer for it to simply disregard.  One of the ways
       involves the use of Subversion's runtime configuration system
       (see <xref linkend="svn.advanced.confarea" />), and therefore
-      applies to all the Subversion operations which make use of that
-      runtime configuration, generally those performed on a particular
-      computer, or by a particular user of a computer.  The other way
-      makes use of Subversion's directory property support, is more
+      applies to all the Subversion operations that make use of that
+      runtime configuration—generally those performed on a particular
+      computer or by a particular user of a computer.  The other way
+      makes use of Subversion's directory property support and is more
       tightly bound to the versioned tree itself, and therefore
       affects everyone who has a working copy of that tree.  Both of
       the mechanisms use <firstterm>file patterns</firstterm> (strings
       of literal and special wildcard characters used to match against
-      file names) to decide which files to ignore.</para>
+      filenames) to decide which files to ignore.</para>
 
     <para>The Subversion runtime configuration system provides an
       option, <literal>global-ignores</literal>, whose value is a
       whitespace-delimited collection of file patterns.  The
       Subversion client checks these patterns against the names of the
-      files which are candidates for addition to version control, as
-      well as to unversioned files which the <command>svn
+      files that are candidates for addition to version control, as
+      well as to unversioned files that the <command>svn
       status</command> command notices.  If any file's name matches
       one of the patterns, Subversion will basically act as if the
       file didn't exist at all.  This is really useful for the kinds
       of files that you almost never want to version, such as editor
-      backup files like Emacs' <literal>*~</literal> and
+      backup files such as Emacs' <literal>*~</literal> and
       <literal>.*~</literal> files.</para>
 
     <sidebar>
@@ -1235,12 +1235,12 @@
 
       <para>File patterns (also called <firstterm>globs</firstterm> or
         <firstterm>shell wildcard patterns</firstterm>) are strings of
-        characters that are intended to be matched against file names,
+        characters that are intended to be matched against filenames,
         typically for the purpose of quickly selecting some subset of
         similar files from a larger grouping without having to
         explicitly name each file.  The patterns contain two types of
-        characters:  regular characters which are compared explicitly
-        against potential matches, and special wildcard characters
+        characters:  regular characters, which are compared explicitly
+        against potential matches, and special wildcard characters,
         which are interpreted differently for matching
         purposes.</para>
 
@@ -1254,29 +1254,29 @@
         <varlistentry>
           <term><literal>?</literal></term>
           <listitem>
-            <para>matches any single character</para>
+            <para>Matches any single character.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><literal>*</literal></term>
           <listitem>
-            <para>matches any string of characters, including the
-              empty string</para>
+            <para>Matches any string of characters, including the
+              empty string.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><literal>[</literal></term>
           <listitem>
-            <para>begins a character class definition terminated by
+            <para>Begins a character class definition terminated by
               <literal>]</literal>, used for matching a subset of
-              characters</para>
+              characters.</para>
           </listitem>
         </varlistentry>
       </variablelist>
 
       <para>You can see this same pattern matching behavior at a Unix
         shell prompt.  The following are some examples of patterns
-        being used for various things.</para>
+        being used for various things:</para>
 
       <screen>
 $ ls   ### the book sources
@@ -1314,7 +1314,7 @@
 
     <para>When found on a versioned directory, the
       <literal>svn:ignore</literal> property is expected to contain a
-      list of newline-delimited file patterns which Subversion should
+      list of newline-delimited file patterns that Subversion should
       use to determine ignorable objects in that same directory.
       These patterns do not override those found in the
       <literal>global-ignores</literal> runtime configuration option,
@@ -1371,7 +1371,7 @@
     </sidebar>
 
     <para>The global list of ignore patterns tends to be more a
-      matter of personal taste, and tied more closely to a user's
+      matter of personal taste and ties more closely to a user's
       particular tool chain than to the details of any particular
       working copy's needs.  So, the rest of this section will focus
       on the <literal>svn:ignore</literal> property and its
@@ -1392,7 +1392,7 @@
 </screen>
     
     <para>In this example, you have made some property modifications
-      to <filename>button.c</filename>, but in your working copy you
+      to <filename>button.c</filename>, but in your working copy, you
       also have some unversioned files: the latest
       <filename>calculator</filename> program that you've compiled
       from your source code, a source file named
@@ -1406,12 +1406,12 @@
       log files lying around.  These facts are true for all working
       copies of this project, not just your own.  And you know that
       you aren't interested in seeing those things every time you run
-      <command>svn status</command>, and pretty sure that nobody else
-      is interested in them either.  So you use <command>svn propedit
-      svn:ignore calc</command> to add some ignore patterns to the
-      <filename>calc</filename> directory.  For example, you might add
-      this as the new value of the <literal>svn:ignore</literal>
-      property:</para>
+      <command>svn status</command>, and you are pretty sure that
+      nobody else is interested in them either.  So you use
+      <command>svn propedit svn:ignore calc</command> to add some
+      ignore patterns to the <filename>calc</filename> directory.  For
+      example, you might add this as the new value of the
+      <literal>svn:ignore</literal> property:</para>
 
     <programlisting>
 calculator
@@ -1435,7 +1435,7 @@
       logfiles are still in your working copy; Subversion just isn't
       constantly reminding you that they are present and unversioned.
       And now with all the uninteresting noise removed from the
-      display, you are left with more interesting items—such as
+      display, you are left with more intriguing items—such as
       that source code file <filename>data.c</filename> that you
       probably forgot to add to version control.</para>
 
@@ -1576,7 +1576,7 @@
     <para>Several of the previous descriptions use the phrase
       <quote>last known</quote> or similar wording.  Keep in mind that
       keyword expansion is a client-side operation, and your client
-      only <quote>knows</quote> about changes which have occurred in
+      <quote>knows</quote> only about changes that have occurred in
       the repository when you update your working copy to include
       those changes.  If you never update your working copy, your
       keywords will never expand to different values even if those
@@ -1592,10 +1592,10 @@
         <para>… or maybe even a section of a book …</para>
       </footnote> 
       about how to use keywords, and you don't want Subversion to
-      substitute your beautiful examples of un-substituted keyword
+      substitute your beautiful examples of unsubstituted keyword
       anchors!</para>
 
-    <para>To tell Subversion whether or not to substitute keywords
+    <para>To tell Subversion whether to substitute keywords
       on a particular file, we again turn to the property-related
       subcommands.  The <literal>svn:keywords</literal> property,
       when set on a versioned file, controls which keywords will
@@ -1632,7 +1632,7 @@
       contained a keyword anchor for the <literal>Rev</literal>
       keyword, yet we did not include that keyword in the property
       value we set.  Subversion will happily ignore requests to
-      substitute keywords that are not present in the file, and
+      substitute keywords that are not present in the file and
       will not substitute keywords that are not present in the
       <literal>svn:keywords</literal> property value.</para>
 
@@ -1641,15 +1641,15 @@
       substitute text.  Instead of seeing your keyword anchor
       <literal>$LastChangedDate$</literal>, you'll see its
       substituted result.  That result also contains the name of
-      the keyword, and continues to be bounded by the dollar sign
+      the keyword and continues to be bounded by the dollar sign
       (<literal>$</literal>) characters.  And as we predicted, the
       <literal>Rev</literal> keyword was not substituted because
       we didn't ask for it to be.</para>
 
     <para>Note also that we set the <literal>svn:keywords</literal>
-      property to <quote>Date Author</quote> yet the keyword
+      property to <literal>Date Author</literal>, yet the keyword
       anchor used the alias <literal>$LastChangedDate$</literal>
-      and still expanded correctly.</para>
+      and still expanded correctly:</para>
 
     <screen>
 Here is the latest report from the front lines.
@@ -1662,8 +1662,8 @@
       <filename>weather.txt</filename>, your copy of that file
       will continue to display the same substituted keyword value
       as before—until you update your working copy.  At that
-      time the keywords in your <filename>weather.txt</filename>
-      file will be re-substituted with information that
+      time, the keywords in your <filename>weather.txt</filename>
+      file will be resubstituted with information that
       reflects the most recent known commit to that file.</para>
 
     <sidebar>
@@ -1672,7 +1672,7 @@
       <para>New users are often confused by how the
         <literal>$Rev$</literal> keyword works.  Since the repository
         has a single, globally increasing revision number, many people
-        assume that it is this number which is reflected by the
+        assume that it is this number that is reflected by the
         <literal>$Rev$</literal> keyword's value.  But
         <literal>$Rev$</literal> expands to show the last revision in
         which the file <emphasis>changed</emphasis>, not the last
@@ -1683,23 +1683,22 @@
         files?</para>
 
       <para>To do this, you need external processing.  Subversion
-        ships with a tool called <command>svnversion</command> which
-        was designed for just this purpose.
-        <command>svnversion</command> crawls your working copy and
-        generates as output the revision(s) it finds.  You can use
-        this program, plus some additional tooling, to embed that
-        revision information into your files.  For more information on
-        <command>svnversion</command>, see <xref
+        ships with a tool called <command>svnversion</command>, which
+        was designed for just this purpose.  It crawls your working
+        copy and generates as output the revision(s) it finds.  You
+        can use this program, plus some additional tooling, to embed
+        that revision information into your files.  For more
+        information on <command>svnversion</command>, see <xref
         linkend="svn.ref.svnversion"/>.</para>
 
     </sidebar>
 
     <para>Subversion 1.2 introduced a new variant of the keyword
-      syntax which brought additional, useful—though perhaps
+      syntax, which brought additional, useful—though perhaps
       atypical—functionality.  You can now tell Subversion
       to maintain a fixed length (in terms of the number of bytes
       consumed) for the substituted keyword.  By using a
-      double-colon (<literal>::</literal>) after the keyword name,
+      double colon (<literal>::</literal>) after the keyword name,
       followed by a number of space characters, you define that
       fixed width.  When Subversion goes to substitute your
       keyword for the keyword and its value, it will essentially
@@ -1735,14 +1734,14 @@
     
     <para>The result is not so beautiful.  And you might be
       tempted to then adjust the file after the substitution so
-      that it again looks tabular.  But that only holds as long as
+      that it again looks tabular.  But that holds only as long as
       the keyword values are the same width.  If the last
       committed revision rolls into a new place value (say, from
       99 to 100), or if another person with a longer username
       commits the file, stuff gets all crooked again.  However, if
       you are using Subversion 1.2 or better, you can use the new
-      fixed-length keyword syntax, define some field widths that
-      seem sane, and now your file might look like this:</para>
+      fixed-length keyword syntax and define some field widths that
+      seem sane so your file might look like this:</para>
 
     <screen>
 $Rev::               $:  Revision of last commit
@@ -1751,9 +1750,9 @@
 </screen>
     
     <para>You commit this change to your file.  This time,
-      Subversion notices the new fixed-length keyword syntax, and
+      Subversion notices the new fixed-length keyword syntax and
       maintains the width of the fields as defined by the padding
-      you placed between the double-colon and the trailing dollar
+      you placed between the double colon and the trailing dollar
       sign.  After substitution, the width of the fields is
       completely unchanged—the short values for
       <literal>Rev</literal> and <literal>Author</literal> are
@@ -1776,9 +1775,9 @@
     <warning>
       <para>Be aware that because the width of a keyword field is
         measured in bytes, the potential for corruption of
-        multi-byte values exists.  For example, a username which
-        contains some multi-byte UTF-8 characters might suffer
-        truncation in the middle of the string of bytes which make
+        multibyte values exists.  For example, a username that
+        contains some multibyte UTF-8 characters might suffer
+        truncation in the middle of the string of bytes that make
         up one of those characters.  The result will be a mere
         truncation when viewed at the byte level, but will likely
         appear as a string with an incorrect or garbled final
@@ -1807,14 +1806,14 @@
       structure is copied to your local disk.  Subversion 1.5
       introduces a feature called <firstterm>sparse
       directories</firstterm> (or <firstterm>shallow
-      checkouts</firstterm>) which allows you to easily checkout a
+      checkouts</firstterm>) that allows you to easily check out a
       working copy—or a portion of a working copy—more
       shallowly than full recursion, with the freedom to bring in
       previously ignored files and subdirectories at a later
       time.</para>
 
     <para>For example, say we have a repository with a tree of files
-      and directories named like the members of a human family with
+      and directories with names of the members of a human family with
       pets.  (It's an odd example, to be sure, but bear with us.)  A
       regular <command>svn checkout</command> operation will give us a
       working copy of the whole tree:</para>
@@ -1835,9 +1834,9 @@
 $
 </screen>
 
-    <para>Now, let's checkout the same tree again, but this time,
-      we'll ask Subversion to give us only the topmost direcectory
-      with none of its children at all.</para>
+    <para>Now, let's check out the same tree again, but this time,
+      we'll ask Subversion to give us only the top-most direcectory
+      with none of its children at all:</para>
 
     <screen>
 $ svn checkout file:///var/svn/repos mom-empty --depth empty
@@ -1848,8 +1847,9 @@
     <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 <option>--non-recursive
-      (-N)</option> and <option>--recursive (-R)</option> options.  In
+      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
       obsoletes these two older options.  For starters, it expands the
       supported degrees of depth specification available to users,
@@ -1949,17 +1949,17 @@
       present on many other Subversion commands, too.  In those other
       commands, depth specification is a way to limit the scope of an
       operation to some depth, much like the way the older
-      <option>--non-recursive (-N)</option> and <option>--recursive
-      (-R)</option> options behave.  This means that when operating on
-      a working copy of some depth, and 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 Subversion command with some
-      requested operational depth, the command will maintain the
-      ambient depth of the working copy members while still limiting
-      the scope of the operation to the requested (or default)
-      operational depth.</para>
+      <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,
+      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
+      Subversion command with some requested operational depth, the
+      command will maintain the ambient depth of the working copy
+      members while still limiting the scope of the operation to the
+      requested (or default) operational depth.</para>
 
     <para>In addition to the <option>--depth</option> option, the
       <command>svn update</command> and <command>svn switch</command>
@@ -2090,7 +2090,7 @@
       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
+      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
       model.</para>
@@ -2267,15 +2267,16 @@
 
       <para>There are a number of new things demonstrated in the
         previous example.  First, notice that Harry passed the
-        <option>--message (-m)</option> option to <command>svn
-        lock</command>.  Similar to <command>svn commit</command>, the
-        <command>svn lock</command> command can take comments (either
-        via <option>--message (-m)</option> or <option>--file
-        (-F)</option>) to describe the reason for locking the file.
-        Unlike <command>svn commit</command>, however, <command>svn
-        lock</command> will not demand a message by launching your
-        preferred text editor.  Lock comments are optional, but still
-        recommended to aid communication.</para>
+        <option>--message</option> (<option>-m</option>) option to
+        <command>svn lock</command>.  Similar to <command>svn
+        commit</command>, the <command>svn lock</command> command can
+        take comments (either via <option>--message</option>
+        (<option>-m</option>) or <option>--file</option>
+        (<option>-F</option>) to describe the reason for locking the
+        file.  Unlike <command>svn commit</command>, however,
+        <command>svn lock</command> will not demand a message by
+        launching your preferred text editor.  Lock comments are
+        optional, but still recommended to aid communication.</para>
 
       <para>Secondly, the lock attempt succeeded.  This means that the
         file wasn't already locked, and that Harry had the latest
@@ -3057,15 +3058,16 @@
       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 (-r)</option> of which
-      we've spoken so much in this book?  That revision (or set of
-      revisions) is called the <firstterm>operative
-      revision</firstterm> (or <firstterm>operative revision
-      range</firstterm>).  Once a particular line of history has been
-      identified using a path and peg revision, Subversion performs
-      the requested operation using the operative revision(s).  To map
-      this to our Chicagoland streets analogy, if we are told to go to
-      606 N. Main Street in Wheaton,
+    <para>But what of the <option>--revision</option>
+      (<option>-r</option>) of which we've spoken so much in this
+      book?  That revision (or set of revisions) is called the
+      <firstterm>operative revision</firstterm> (or
+      <firstterm>operative revision range</firstterm>).  Once a
+      particular line of history has been identified using a path and
+      peg revision, Subversion performs the requested operation using
+      the operative revision(s).  To map this to our Chicagoland
+      streets analogy, if we are told to go to 606 N. Main Street in
+      Wheaton,
       <footnote>
         <para>606 N. Main Street, Wheaton, Illinois, is the home of
           the Wheaton History Center.  Get it—<quote>History




More information about the svnbook-dev mailing list