[PATCH] Review: patches through chapter 2

Eric Hanchrow offby1 at blarg.net
Fri Mar 16 13:49:39 CDT 2007

This is a bazillion different changes; I'm reading the book start to
finish and whining^Wmaking constructive suggestions about anything and

Index: tools/svnbook.el
--- tools/svnbook.el	(revision 2735)
+++ tools/svnbook.el	(working copy)
@@ -42,7 +42,9 @@
         (replace-match ">" nil t))
+(when (not (boundp 'sgml-catalog-files))
+  (setq sgml-catalog-files '()))
+(add-to-list 'sgml-catalog-files '("/usr/local/prod/sgml/dblite/catalog") t)
 (setq sgml-omittag-transparent t
       sgml-trace-entity-lookup nil
       sgml-live-element-indicator t
@@ -52,7 +54,6 @@
       ;; NOTE: I removed the -u from sgml-validate-command to get rid of stupid errors in the DTDs. -Fitz
       sgml-set-face t
       sgml-mode-hook (quote (auto-fill-mode))
-      sgml-catalog-files (append sgml-catalog-files '("/usr/local/prod/sgml/dblite/catalog"))
       sgml-auto-activate-dtd t)
Index: en/HACKING
--- en/HACKING	(revision 2735)
+++ en/HACKING	(working copy)
@@ -1,5 +1,5 @@
 This style guide is intended to be *an addition to* the O'Reilly and
-Associates style guide at http://www.ora.com/oreilly/author/stylesheet.html
+Associates style guide at http://www.oreilly.com/oreilly/author/stylesheet.html
Index: en/book/appc-webdav.xml
--- en/book/appc-webdav.xml	(revision 2735)
+++ en/book/appc-webdav.xml	(working copy)
@@ -238,7 +238,7 @@
     <para>The original WebDAV standard has been widely successful.
       Every modern computer operating system has a general WebDAV
       client built-in (details to follow), and a number of popular
-      standalone applications are also able to speak WebDAV —
+      standalone applications are also able to speak WebDAV—
       Microsoft Office, Dreamweaver, and Photoshop to name a few.  On
       the server end, the Apache webserver has been able to provide
       WebDAV services since 1998 and is considered the de-facto
Index: en/book/ch00-preface.xml
--- en/book/ch00-preface.xml	(revision 2735)
+++ en/book/ch00-preface.xml	(working copy)
@@ -37,6 +37,7 @@
     flexible.  And for the most part, almost all newly-started
     open-source projects now choose Subversion instead of CVS.</para>
+  <!-- Just 1.4?  Not 1.5, 1.6, and so on? -->
   <para>This book is written to document the 1.4 series of the
     Subversion version control system.  We have made every attempt to
     be thorough in our coverage.  However, Subversion has a thriving
@@ -57,11 +58,11 @@
       use Subversion to manage their data.  While Subversion runs on a
       number of different operating systems, its primary user
       interface is command-line based.  That command-line tool
-      (<command>svn</command>) and auxiliary program are the focus of
+      (<command>svn</command>), and some auxiliary programs, are the focus of
       this book.</para>
     <para>For consistency, the examples in this book assume the reader
-      is using a Unix-like operating system and relatively comfortable
+      is using a Unix-like operating system, and is relatively comfortable
       with Unix and command-line interfaces.  That said, the
       <command>svn</command> program also runs on non-Unix platforms
       like Microsoft Windows.  With a few minor exceptions, such as
@@ -145,7 +146,7 @@
             learn how to do more advanced things with Subversion, such
             as how to use branches and perform merges (<xref
             linkend="svn.branchmerge"/>), how to use Subversion's
-            property support ((<xref linkend="svn.advanced"/>), how to
+            property support (<xref linkend="svn.advanced"/>), how to
             configure runtime options (<xref
             linkend="svn.customization"/>), and other things.  These
             chapters aren't critical at first, but be sure to read
@@ -303,7 +304,7 @@
           <term><xref linkend="svn.serverconfig"/></term>
             <para>Explains how to configure your Subversion server and
-              the three ways to access your repository:
+              the ways to access your repository, including:
               <literal>HTTP</literal>, the <literal>svn</literal>
               protocol, and local disk access.  It also covers the details
               of authentication, authorization and anonymous
@@ -421,6 +422,7 @@
     <para>The online home of this book's development and most of the
       volunteer-driven translation efforts around it is <ulink
       url="http://svnbook.red-bean.com"/>.  There, you can find links
+      <!-- what's the difference between a "snapshot" and a "tagged version"? -->
       to the latest snapshots and tagged versions of the book in
       various formats, as well as instructions for accessing the
       book's Subversion repository (where lives its DocBook XML source
@@ -580,7 +582,11 @@
     <title>What is Subversion?</title>
-    <para>Subversion is a free/open-source version control system.
+    <!-- I'd like to set off the phrase "version control system"
+    somehow, because the next sentence talks _only_ about it, and not
+    about the phrase "free/open-source".  But I'm not sure how to do
+    that while conforming to this document's standard style. -->
+    <para>Subversion is a free/open-source <firstterm>version control system</firstterm>.
       That is, Subversion manages files and directories, and the
       changes made to them, over time.  This allows you to recover
       older versions of your data, or examine the history of how your
@@ -591,6 +597,7 @@
       be used by people on different computers.  At some level, the
       ability for various people to modify and manage the same set of
       data from their respective locations fosters collaboration.
+      <!-- it's not clear to me what "conduit" we're referring to -->
       Progress can occur more quickly without a single conduit through
       which all modifications must occur.  And because the work is
       versioned, you need not fear that quality is the trade-off for
Index: en/book/ch03-advanced-topics.xml
--- en/book/ch03-advanced-topics.xml	(revision 2735)
+++ en/book/ch03-advanced-topics.xml	(working copy)
@@ -926,7 +926,7 @@
           it, this RFC describes the concept of media types and
           subtypes, and recommends a syntax for the representation of
           those types.  Today, MIME media types—or, MIME
-          types— are used almost universally across e-mail
+          types—are used almost universally across e-mail
           applications, Web servers, and other software as the de
           facto mechanism for clearing up the file content
@@ -2593,7 +2593,7 @@
       to give the project a name.
         <para><quote>You're not supposed to name it.  Once you name it,
-          you start getting attached to it.</quote> — Mike
+          you start getting attached to it.</quote>—Mike
       Let's say you called your software Frabnaggilywort.  At this
Index: en/book/ch05-repository-admin.xml
--- en/book/ch05-repository-admin.xml	(revision 2735)
+++ en/book/ch05-repository-admin.xml	(working copy)
@@ -419,7 +419,7 @@
             however, assumes that the reader is thinking
-        —a versioned filesystem implementation that uses the
+       —a versioned filesystem implementation that uses the
         native OS filesystem to store data.</para>
       <para><xref linkend="svn.reposadmin.basics.backends.tbl-1" />
Index: en/book/ch01-fundamental-concepts.xml
--- en/book/ch01-fundamental-concepts.xml	(revision 2735)
+++ en/book/ch01-fundamental-concepts.xml	(working copy)
@@ -1,3 +1,13 @@
+<!-- note that when I say "on IRC", I mean "on the #svn channel on
+irc.freenode.org" -->
+<!-- a general note: we're using the word "merge" in two somewhat
+  different ways.  One way describes what happens when we "svn up" a
+  file that has uncommitted changes; the other way of course describes
+  what happens when we do "svn merge".  I fear this may confuse
+  people.  Naturally I can't think of how to alleviate that confusion
+  :-| -->
 <chapter id="svn.basic">
   <title>Fundamental Concepts</title>
@@ -54,6 +64,7 @@
       was the last person to change this file, and what changes did
       he make?</quote> These are the sorts of questions that are at
       the heart of any <firstterm>version control system</firstterm>:
+      <!-- isn't "record and track" redundant? :-) -->
       systems that are designed to record and track changes to data
       over time.
@@ -187,6 +198,7 @@
     <sect2 id="svn.basic.vsn-models.copy-merge">
       <title>The Copy-Modify-Merge Solution</title>
+      <!-- I'd say "most other version control systems" -->
       <para>Subversion, CVS, and a number of other version control
         systems use a <firstterm>copy-modify-merge</firstterm> model as an
         alternative to locking.  In this model, each user's client
@@ -207,6 +219,10 @@
         later, the repository informs him that his file A is
         <firstterm>out-of-date</firstterm>.  In other words, that file
         A in the repository has somehow changed since he last copied
+        <!-- I fear that using the term "merge" here might lead
+        newbies to think that they should type "svn merge" in this
+        situation, which of course isn't the case: they instead need
+        to type "svn up". -->
         it.  So Harry asks his client to <firstterm>merge</firstterm>
         any new changes from the repository into his working copy of
         file A.  Chances are that Sally's changes don't overlap with
@@ -252,6 +268,9 @@
         communication.  When users communicate poorly, both syntactic
         and semantic conflicts increase.  No system can force users to
         communicate perfectly, and no system can detect semantic
+        <!-- one isn't lulled "into a promise"; I'd say "lulled into a
+        false sense of security that ..." or "lulled into thinking
+        that ..." -->
         conflicts.  So there's no point in being lulled into a false
         promise that a locking system will somehow prevent conflicts;
         in practice, locking seems to inhibit productivity more than
@@ -277,7 +296,7 @@
         <para>While Subversion is still primarily a copy-modify-merge
           system, it still recognizes the need to lock an occasional
-          file ands provide mechanisms for this.  This feature is
+          file, and thus provide mechanisms for this.  This feature is
           discussed later in this book, in
           <xref linkend="svn.advanced.locking"/>.</para>
@@ -332,6 +351,7 @@
         Windows platforms will need to use an unofficially
         <quote>standard</quote> syntax for accessing repositories
         that are on the same machine, but on a different drive than
+        <!-- file://localhost/X:/path/to/repos works too -->
         the client's current working drive.  Either of the two
         following URL path syntaxes will work where
         <literal>X</literal> is the drive on which the repository
@@ -362,7 +382,11 @@
-      <para>Finally, it should be noted that the Subversion client will
+      <!-- isn't this behavior dependent upon the various LC_
+      environment variables?  If so, might it be useful to include a
+      footnote that says so, and points to the section that explains
+      in detail? -->
+      <para>Finally, the Subversion client will
         automatically encode URLs as necessary, just like a web browser
         does.  For example, if a URL contains a space or upper-ASCII
@@ -457,6 +481,8 @@
 Makefile  integer.c  button.c  .svn/
+      <!-- maybe instead, say "The letter A's in the left margin", and
+      perhaps emphasize the letter "a" in the word "adding" -->
       <para>The list of letter A's indicates that Subversion is adding
         a number of items to your working copy.  You now have a
         personal copy of the repository's <filename>/calc</filename>
@@ -465,6 +491,9 @@
         extra information needed by Subversion, as mentioned
+      <!-- this sidebar seems a tad out of place.  Might not a
+      better place for it be the end of svn.basic.in-action, where we
+      already talked about URLs in some detail? -->
       <sidebar id="svn.basic.in-action.wc.sb-1">
         <title>Repository URLs</title>
@@ -488,6 +517,8 @@
+                <!-- should this be 'file://' instead - i.e., two
+                slashes instead of three?  Nit-picky, I admit. -->
                 <entry>direct repository access (on local disk)</entry>
@@ -508,6 +539,13 @@
+                <!-- svn+ssh:// isn't as similar to svn:// as https://
+                is to http://.  People on IRC are occasionally
+                suprised to learn that svn+ssh does _not_ contact a
+                daemon, but instead starts up its own "one-shot"
+                svnserve process.  This statement might further that
+                confusion.  Naturally I can't think of any way to
+                improve it that is short enough :-| -->
                 <entry>same as <literal>svn://</literal>, but through
                   an SSH tunnel.</entry>
@@ -525,7 +563,7 @@
       <para>Suppose you make changes to <filename>button.c</filename>.
         Since the <filename>.svn</filename> directory remembers the
-        file's modification date and original contents, Subversion can
+        file's original modification date and contents, Subversion can
         tell that you've changed the file.  However, Subversion does
         not make your changes public until you explicitly tell it to.
         The act of publishing your changes is more commonly known as
@@ -556,6 +594,9 @@
         unchanged; Subversion only modifies working copies at the
         user's request.</para>
+      <!-- if, above, you still refer to this process as "merging",
+      then it would be good to say something like "this is the
+      'merging' step we referred to above" -->
       <para>To bring her project up to date, Sally can ask
         Subversion to <firstterm>update</firstterm> her working copy,
         by using the Subversion <command>update</command> command.
@@ -582,7 +623,10 @@
         in the <filename>.svn</filename> directory, and further
         information in the repository, to decide which files need to
         be brought up to date.</para>
+      <!-- this probably isn't the place, but you might want to
+        mention that this process doesn't send any more information
+        over the network than needed.  People on IRC occasionally ask
+        about this.  -->
@@ -593,9 +637,11 @@
       <para>An <command>svn commit</command> operation publishes
         changes to any number of files and directories as a single
         atomic transaction.  In your working copy, you can change
-        files' contents, create, delete, rename and copy files and
-        directories, and then commit a complete set of changes as an
+        files' contents; create, delete, rename and copy files and
+        directories; and then commit a complete set of changes as an
         atomic transaction.</para>
+      <!-- might we mention properties here too?  They're another type
+           of change that can be made. -->
       <para>By <quote>atomic transaction</quote>, we mean simply this:
         either all of the changes happen in the repository, or none of
@@ -715,6 +761,10 @@
+      <!-- It's not clear to me if subversion looks at any other
+      information, in particular, the file's size or contents.  It
+      might be worthwhile mentioning such other tests, if they
+      exist.  -->
       <para>Given this information, by talking to the repository,
         Subversion can tell which of the following four states a
         working file is in:</para>
@@ -774,6 +824,12 @@
               changes.  If Subversion can't complete the merge in a
               plausible way automatically, it leaves it to the user to
               resolve the conflict.</para>
+            <!-- at some point it might be worth mentioning that if,
+              by coincidence, the local changes match those on the
+              server, not only will the merge succeed, but the file
+              will suddenly appear to be not modified.  This is of
+              course correct behavior, but I suspect it might surprise
+              some people. -->
@@ -892,7 +948,7 @@
           contained in a subdirectory, or perhaps you'd like to figure
           out when a bug first came into existence in a specific file.
           This is the <quote>time machine</quote> aspect of a version
-          control system — the feature which allows you to move
+          control system—the feature which allows you to move
           any portion of your working copy forward and backward in
Index: en/book/ch06-server-configuration.xml
--- en/book/ch06-server-configuration.xml	(revision 2735)
+++ en/book/ch06-server-configuration.xml	(working copy)
@@ -409,7 +409,7 @@
             <xref linkend="svn.serverconfig.multimethod"/>.)  Note
             that this is also one of the reasons we warn against
             accessing repositories via <literal>svn+ssh://</literal>
-            URLs — from a security standpoint, it's effectively
+            URLs—from a security standpoint, it's effectively
             the same as local users accessing
             via <literal>file://</literal>, and can entail all the
             same problems if the administrator isn't careful.</para>
@@ -2088,7 +2088,7 @@
             the <quote>default</quote> MIME type,
             typically <literal>text/plain</literal>.  This can be
             frustrating, however, if a user wishes repository files to
-            render as something more meaningful — for example,
+            render as something more meaningful—for example,
             it might be nice to have a <filename>foo.html</filename> file
             in the repository actually render as HTML when
@@ -2219,7 +2219,7 @@
           even the simplest Subversion client operation generates
           multiple network requests.  It's very difficult to look at
           the <filename>access_log</filename> and deduce what the
-          client was doing — most operations look like a series
+          client was doing—most operations look like a series
           of cryptic <literal>PROPPATCH</literal>, <literal>GET</literal>,
           <literal>PUT</literal>, and <literal>REPORT</literal>
           requests.  To make things worse, many client operations send
Index: en/book/ch04-branching-and-merging.xml
--- en/book/ch04-branching-and-merging.xml	(revision 2735)
+++ en/book/ch04-branching-and-merging.xml	(working copy)
@@ -1038,7 +1038,7 @@
           file.  This can lead to problems, especially because the
           same thing happens with renamed files.  A lesser-known fact
           about Subversion is that it lacks <quote>true
-          renames</quote> — the <command>svn move</command>
+          renames</quote>—the <command>svn move</command>
           command is nothing more than an aggregation of <command>svn
           copy</command> and <command>svn delete</command>.</para>
@@ -1064,7 +1064,7 @@
           operation has deleted the latest version
           of <filename>integer.c</filename> file (the one containing
           Sally's latest changes), and blindly added your
-          new <filename>whole.c</filename> file — which is a
+          new <filename>whole.c</filename> file—which is a
           duplicate of the <emphasis>older</emphasis> version
           of <filename>integer.c</filename>.  The net effect is that
           merging your <quote>rename</quote> to the branch has removed
@@ -1401,8 +1401,8 @@
         particular revision tree, and the second coordinate is a path
         within that tree.  So every version of your file or directory
         can be defined by a specific coordinate pair.  (Remember the
-        familiar <quote>peg revision</quote> syntax — foo.c at 224
-        — mentioned back in
+        familiar <quote>peg revision</quote> syntax—foo.c at 224
+       —mentioned back in
         <xref linkend="svn.advanced.pegrevs"/>.) </para>
       <para>First, you might need to use <command>svn log</command> to
Index: en/book/ch02-basic-usage.xml
--- en/book/ch02-basic-usage.xml	(revision 2735)
+++ en/book/ch02-basic-usage.xml	(working copy)
@@ -98,6 +98,10 @@
+      <!-- it might also be worth emphasizing - even though the example
+      above clearly shows it - that the repo does *not* get a new
+      directory named "mytree".  I occasionally find people on IRC are
+      surprised by this.  -->
       <para>Note that after the import is finished, the original tree
         is <emphasis>not</emphasis> converted into a working copy.  To
         start working, you still need to <command>svn
@@ -125,7 +129,7 @@
       <para>You'll learn more about tags and branches in <xref
-      linkend="svn.branchmerge"/>.  For details and how to setup
+      linkend="svn.branchmerge"/>.  For details, and how to set up
       multiple projects, see <xref
       linkend="svn.branchmerge.maint.layout"/> and <xref
       linkend="svn.reposadmin.projects.chooselayout"/> to read more
@@ -147,8 +151,8 @@
       copy</quote> of it on your local machine.  This copy contains
       the <literal>HEAD</literal> (latest revision) of the Subversion
       repository that you specify on the command line:</para>
+    <!-- well, unless you specify a "-r" option, of course. -->
 $ svn checkout http://svn.collab.net/repos/svn/trunk
 A    trunk/Makefile.in
@@ -209,6 +213,9 @@
       repository by specifying the subdirectory in the checkout
+    <!-- are you sure you want to introduce the "-r" option here,
+    without describing it?  It might make a reader think that it's
+    needed in order to check out a subdirectory. -->
 $ svn checkout -r 8810 \
@@ -223,27 +230,27 @@
     <para>Since Subversion uses a <quote>copy-modify-merge</quote>
       model instead of <quote>lock-modify-unlock</quote> (see <xref
-      linkend="svn.basic.vsn-models"/>), you're already able to start
+      linkend="svn.basic.vsn-models"/>), you can start right in
       making changes to the files and directories in your working
       copy.  Your working copy is just like any other collection of
       files and directories on your system.  You can edit and change
       them, move them around, you can even delete the entire working
       copy and forget about it.</para>
-      <note>
+      <warning>
         <para>While your working copy is <quote>just like any other
           collection of files and directories on your system</quote>,
           you can edit files at will, but you must tell Subversion
-          about <emphasis>everything else</emphasis>that you do.  For
+          about <emphasis>everything else</emphasis> that you do.  For
           example, if you want to copy or move an item in a working
           copy, you should use <command>svn copy</command> or
           <command>svn move</command> instead of the copy and move
           commands provided by your operating system.  We'll talk more
           about them later in this chapter.</para>
-      </note>
+      </warning>
-    <para>Unless you're ready to commit a new file or directory, or
+    <para>Unless you're ready to commit the addition of a new file or directory, or
       changes to existing ones, there's no need to further notify the
       Subversion server that you've done anything.</para>
@@ -257,9 +264,12 @@
         an important directory.  Whatever you do, don't delete or
         change anything in the administrative area!  Subversion
         depends on it to manage your working copy.</para>
+      <!-- that warning is useful on its own, but how about telling me
+        how to recover if I _have_ deleted that directory?  Believe
+        me, it happens.  -->
+    <!-- as above, I think the "-r" option here is a distraction. -->
     <para>While you can certainly check out a working copy with the
       URL of the repository as the only argument, you can also specify
       a directory after your repository URL.  This places your working
@@ -288,6 +298,7 @@
       <para>When you perform a Subversion operation that requires you
         to authenticate, by default Subversion caches your
+        <!-- perhaps say "for convenience - so that you don't have to enter them again" -->
         authentication credentials on disk.  If you're concerned about
         caching your Subversion passwords,<footnote><para>Of course,
         you're not terribly worried—first because you know that
@@ -438,7 +449,7 @@
         to each item to let you know what actions Subversion performed
         to bring your working copy up-to-date.  To find out what these
         letters mean, see <xref linkend
-        ="svn.ref.svn.c.update"/></para>
+        ="svn.ref.svn.c.update"/>.</para>
@@ -467,8 +478,8 @@
         text files—and just as efficiently too.  For tree
         changes, you can ask Subversion to <quote>mark</quote> files
         and directories for scheduled removal, addition, copying, or
-        moving.  While these changes may take place immediately in
-        your working copy, no additions or removals will happen in the
+        moving.  These changes take place immediately in
+        your working copy, but no additions or removals happen in the
         repository until you commit them.</para>
       <para>Here is an overview of the five Subversion subcommands
@@ -487,9 +498,9 @@
         <para>When a symlink is committed into a Subversion
           repository, Subversion remembers that the file was in fact a
-          symlink, as well as to what object the symlink
+          symlink, as well as the object to which the symlink
           <quote>points</quote>.  When that symlink is checked out to
-          another working copy on a supporting system, Subversion
+          another working copy on a non-Windows system, Subversion
           reconstructs a real filesystem-level symbolic link from the
           versioned symlink.  But that doesn't in any way limit the
           usability of working copies on systems such as Windows which
@@ -526,16 +537,17 @@
               repository.  If <filename>foo</filename> is a file or
               link, it is immediately deleted from your working copy.
               If <filename>foo</filename> is a directory, it is not
-              deleted, but Subversion schedules it for deletion.  When
+              deleted, but versioned files under it are, and
+              Subversion schedules it, and versioned directories under it, for deletion.  When
               you commit your changes, <filename>foo</filename> will
-              be removed from your working copy and the repository.
+              be entirely removed from your working copy and the repository.
               <footnote><para>Of course, nothing is ever totally
               deleted from the repository—just from the
               <literal>HEAD</literal> of the repository.  You can get
               back anything you delete by checking out (or updating
-              your working copy) a revision earlier than the one in
+              your working copy to) a revision earlier than the one in
               which you deleted it. Also see <xref
-              linkend="svn.branchmerge.commonuses.resurrect"/>></para></footnote></para>
+              linkend="svn.branchmerge.commonuses.resurrect"/>.</para></footnote></para>
@@ -623,11 +635,11 @@
         <title>Look Ma! No Network!</title>
-        <para>The commands (<command>svn status</command>,
+        <para>The commands <command>svn status</command>,
           <command>svn diff</command>, and <command>svn
-          revert</command>) can be used without any network access
-          (assuming, of course, that your repository is across the
-          network and not local).  This makes it easy to manage your
+          revert</command> can be used without any network access
+          even if your repository <emphasis>is</emphasis> across the
+          network.  This makes it easy to manage your
           changes-in-progress when you are somewhere without a network
           connection, such as travelling on an airplane, riding a
           commuter train or hacking on the beach.<footnote><para>And
@@ -654,6 +666,7 @@
       <para>Subversion has been optimized to help you with this task,
         and is able to do many things without communicating with the
         repository.  In particular, your working copy contains a
+        <!-- "secret"?  nah.  "hidden", maybe. -->
         secret cached <quote>pristine</quote> copy of each version
         controlled file within the <filename>.svn</filename> area.
         Because of this, Subversion can quickly show you how your
@@ -689,14 +702,15 @@
-        <para>If you run <command>svn status</command> at the top of
-          your working copy with no arguments, it will detect all file
+        <para>If you run <command>svn status</command>, with no arguments, at the top of
+          your working copy, it will detect all file
           and tree changes you've made.  Below are a few examples of
           the most common status codes that <command>svn
           status</command> can return.  (Note that the text following
           <literal>#</literal> is not
           actually printed by <command>svn status</command>.)</para>
+        <!-- conflicts can come from merges, too, of course. -->
 A       stuff/loot/bloo.h   # file is scheduled for addition
 C       stuff/loot/lump.c   # file has textual conflicts from an update
@@ -705,9 +719,9 @@
         <para>In this output format <command>svn status</command>
-          prints six columns of characters, followed by several
-          whitespace characters, followed by a file or directory name.
-          The first column tells the status of a file or directory
+          prints six characters -- letters or whitespace -- followed by several
+          more whitespace characters, followed by a file or directory name.
+          The letter tells the status of a file or directory
           and/or its contents.  The codes we listed are:</para>
@@ -726,6 +740,7 @@
               <para>The file <filename>item</filename> is in a state
                 of conflict.  That is, changes received from the
+                <!-- again, it could conflict due to a merge, too -->
                 server during an update overlap with local changes
                 that you have in your working copy.  You must resolve
                 this conflict before committing your changes to the
@@ -761,6 +776,10 @@
 D      stuff/fish.c
+        <!-- Ooh, this is subtle.  -v apparently changes _both_ the
+        files that "status" reports on (at least, if you haven't
+        specified a file name), _and_ the information that appears for
+        each file.  Is it worth mentioning this here?  -->
         <para><command>svn status</command> also has a
           <option>--verbose (-v)</option> switch, which will show you
           the status of <emphasis>every</emphasis> item in your
@@ -780,16 +799,18 @@
         <para>This is the <quote>long form</quote> output of
-          <command>svn status</command>.  The first column remains the
-          same, but the second column shows the working-revision of
+          <command>svn status</command>.  The letters in the first column mean the
+          <!-- what does "working-revision" mean?  If you don't want
+          to define it here, then we should probably wrap it in <firstterm/>. -->
+          same as in the above, but the second column shows the working-revision of
           the item.  The third and fourth columns show the revision in
-          which the item last changed, and who changed it (these
-          columns are not to be confused with the columns of
-          characters that we just discussed).</para>
+          which the item last changed, and who changed it.</para>
         <para>None of the above invocations to <command>svn
-          status</command> contact the repository, they work only
-          locally by comparing the metadata in the
+          status</command> contact the repository—instead, they 
+          compare the metadata in the
           <filename>.svn</filename> directory with the working copy.
           Finally, there is the <option>--show-updates (-u)</option>
           option, which contacts the repository and adds information
@@ -813,8 +834,10 @@
           server changes on <filename>README</filename> before you
           commit, or the repository will reject your commit for being
           out-of-date.  (More on this subject later.)</para>
+        <!-- how about a link to the section where this is discussed,
+          instead of simply saying "later"? -->
-          <para><command>svn status</command> displays much more
+          <para><command>svn status</command> can display much more
             information about the files and directories in your
             working copy than we've shown here—for an exhaustive
             description of svn status and its output, see <xref
@@ -830,8 +853,8 @@
           <command>svn diff</command> command.  You can find out
           <emphasis>exactly</emphasis> how you've modified things by
           running <command>svn diff</command> with no arguments, which
-          prints out file changes in unified diff
-          format:</para>
+          prints out file changes in <firstterm>unified diff
+          format</firstterm>:</para>
 $ svn diff
@@ -881,11 +904,19 @@
           addition are displayed as all added-text, and files
           scheduled for deletion are displayed as all deleted
+        <!-- shouldn't we then ensure that we have a scheduled-add file,
+          and a scheduled-delete file, in the above example?  If we
+          already have one, and I'm overlooking it, then say something
+          like "... files scheduled for deletion, like stuff/fish.c,
+          are displayed ..."-->
-        <para>Output is displayed in <firstterm>unified diff
-          format</firstterm>.  That is, removed lines are prefaced
-          with a <literal>-</literal> and added lines are prefaced
-          with a <literal>+</literal>.  <command>svn diff</command>
+        <para>Output is displayed in unified diff
+          format.  That is, removed lines are prefaced
+          <!-- I deleted the word "a" in two places because I fear
+          that it will be confused with the "A" output by "svn st",
+          which we just described. -->
+          with <literal>-</literal> and added lines are prefaced
+          with <literal>+</literal>.  <command>svn diff</command>
           also prints filename and offset information useful to the
           <command>patch</command> program, so you can generate
           <quote>patches</quote> by redirecting the diff output to a
@@ -955,7 +986,7 @@
 ?      foo
-      <note>
+      <warning>
         <para><command>svn revert</command>
           <replaceable>ITEM</replaceable> has exactly the same
           effect as deleting <replaceable>ITEM</replaceable> from
@@ -965,7 +996,7 @@
           has one very noticeable difference—it doesn't have
           to communicate with the repository to restore your
-      </note>
+      </warning>
       <para>Or perhaps you mistakenly removed a file from version
@@ -1015,7 +1046,7 @@
       <para>But the <computeroutput>C</computeroutput> stands for
-        conflict.  This means that the changes from the server overlapped
+        <computeroutput>c</computeroutput>onflict.  This means that the changes from the server overlapped
         with your own, and now you have to manually choose between
@@ -1359,7 +1390,7 @@
           decide that you want to cancel your commit, you can just
           quit your editor without saving changes.  If you've already
           saved your commit message, simply delete the text, save
-          again, then quit.</para>
+          again, then abort.</para>
 $ svn commit
@@ -1379,6 +1410,17 @@
         that, the entire commit will fail with a message informing you
         that one or more of your files is out-of-date:</para>
+      <!-- frustratingly (and surprisingly), the "out of date" message
+      depends on the access method.  The one in the example below is
+      for http:// access, but file:// access yields this instead:
+        ../svn-live/subversion/libsvn_client/commit.c:867: (apr_err=160028)
+        svn: Commit failed (details follow):
+        ../svn-live/subversion/libsvn_repos/commit.c:127: (apr_err=160028)
+        svn: Out of date: 'yow' in transaction '2-1'
+      So we should probably note that the text of the message might
+      vary somewhat :-| -->
 $ svn commit -m "Add another rule"
 Sending        rules.txt
@@ -1396,7 +1438,7 @@
         to manage your repository and working copy, but most of your
         day-to-day use of Subversion will involve only the commands
         that we've discussed so far in this chapter.  We will,
-        however, cover a few more commands that you'll use just fairly
+        however, cover a few more commands that you'll use fairly
@@ -1443,8 +1485,8 @@
           <term><command>svn cat</command></term>
-            <para>This is used to retrieve any file as it existed in a
-              particular revision number and display it on your
+            <para>Retrieves a file as it existed in a
+              particular revision number, and displays it on your
@@ -1591,15 +1633,15 @@
-          <para>Examine local changes</para>
+          <para>Examining local changes</para>
-          <para>Compare your working copy to the repository</para>
+          <para>Comparing your working copy to the repository</para>
-          <para>Compare repository to repository</para>
+          <para>Comparing repository to repository</para>
@@ -1640,6 +1682,12 @@
           working copy is compared to the specified revision in the
+        <!-- might this example be a tad more illuminating if we were
+        to pass some revision _other_ than 3?  So that it yields
+        different output than the above example?  If not, why not
+        mumble something about "note how the output is the same as
+        above, since the revision we specified is the same as that
+        chosen by default in the above"-->
 $ svn diff -r 3 rules.txt
 Index: rules.txt
@@ -1700,13 +1748,9 @@
-        <para>Not only can you use <command>svn diff</command> to
-          compare files in your working copy to the repository, but if
-          you supply a URL argument, you can examine the differences
-          between items in the repository without even having a
-          working copy.  This is especially useful if you wish to
-          inspect changes in a file when you don't have a working copy
-          on your local machine:</para>
+        <para>Lastly, you can compare repository revisions even when
+          you don't have a working copy on your local machine, just by
+          including the appropriate URL on the command line:</para>
 $ svn diff -c 5 http://svn.example.com/repos/example/trunk/text/rules.txt
@@ -1813,7 +1857,7 @@
-      <warning>
+      <tip>
         <para>Many Subversion newcomers attempt to use the above
           <command>svn update</command> example to <quote>undo</quote>
           committed changes, but this won't work as you can't commit
@@ -1821,12 +1865,12 @@
           the changed files have newer revisions.  See <xref
           linkend="svn.branchmerge.commonuses.resurrect"/> for a
           description of how to <quote>undo</quote> a commit.</para>
-          </warning>
+          </tip>
       <para>Lastly, if you're building a release and wish to bundle up
-        your files from Subversion but don't want those pesky .svn
-        directories in the way, then you can use svn export to create
-        a local copy of all or part of your repository sans .svn
+        your files from Subversion but don't want those pesky <filename>.svn</filename>
+        directories in the way, then you can use <command>svn export</command> to create
+        a local copy of all or part of your repository sans <filename>.svn</filename>
         directories.  As with <command>svn update</command> and
         <command>svn checkout</command>, you can also pass the
         <option>--revision</option> switch to <command>svn
@@ -1849,7 +1893,7 @@
   <!-- ================================================================= -->
   <!-- ================================================================= -->
   <sect1 id="svn.tour.cleanup">
-    <title>Sometimes You Just Need to Cleanup</title>
+    <title>Sometimes You Just Need to Clean Up</title>
     <para>When Subversion modifies your working copy (or any
       information within <filename>.svn</filename>), it tries to do
@@ -1857,7 +1901,7 @@
       Subversion writes its intentions to a log file.  Next it
       executes the commands in the log file to apply the requested
       change, holding a lock on the relevant part of the working
-      copy while it works — to prevent other Subversion clients
+      copy while it works—to prevent other Subversion clients
       from accessing the working copy in mid-change.  Finally,
       Subversion removes the log file.  Architecturally, this is
       similar to a journaled filesystem.  If a Subversion operation

Most of what ends up in my essays I only thought of when I sat
down to write them.  That's why I write them.
        -- Paul Graham

More information about the svnbook-dev mailing list