[PATCH] Various svnbook fixes

Max Bowsher maxb at ukf.net
Wed Aug 17 06:31:28 CDT 2005


Michael W Thelen wrote:
> Øyvind A. Holm wrote:
>> I’ve had a working copy with lots of small fixes to the book lying
>> around for ages, with more small tweaks added over time, so maybe it’s
>> about time I pass it on. No word wrapping is done to make the patch
>> cleaner. There is no formal log message in this stage of the review,
>> it’s much less work to sort that out afterwards when the patch has been
>> filtered a bit. It’s only trivial changes anyway. But some explanation
>> can be done:
>
> It's been a while since this patch, but it looks like the changes
> haven't been applied or reviewed other than the "using RCS as a backend"
> changes.  Should I file this as a patch issue in the issue tracker?

Miscellaneous cleanup patches tend to get forgotten in the issue tracker.
I've cleaned up the patch and updated it (mostly) to apply to the current 
source.

Let's discuss it - here's my thoughts.


Index: appa.xml
===================================================================
--- appa.xml (revision 1614)
+++ appa.xml (working copy)
@@ -25,7 +25,7 @@
     <title>Revision Numbers Are Different Now</title>

     <para>In CVS, revision numbers are per-file.  This is because CVS
-      uses RCS as a backend; each file has a corresponding RCS file in
+      stores its data in RCS files; each file has a corresponding RCS file 
in
       the repository, and the repository is roughly laid out according
       to the structure of your project tree.</para>


New wording as suggested by Ben. OK to apply?


Index: src/en/book/ch01.xml
===================================================================
--- src/en/book/ch01.xml (revision 1533)
+++ src/en/book/ch01.xml (working copy)
@@ -453,9 +453,11 @@

     <para>This command creates a new directory
       <filename>/path/to/repos</filename> which contains a Subversion
-      repository.  Make sure that this directory lives on a local
+      repository.  If you are creating a Berkeley DB repository (i.e.
+      using the <option>--fs-type=bdb</option> option with the
+      <command>svnadmin</command> command), make sure that this directory 
lives on a local
       disk, <emphasis>not</emphasis> a network share.  This new
-      directory mainly contains a collection of Berkeley DB database
+      directory mainly contains a collection of database
       files.  You won't see your versioned files if you peek inside.
       For more information about repository creation and maintenance,
       see <xref linkend="svn.reposadmin"/>.</para>

The mention of network shares has gone from ch01 entirely. This change does 
not apply.


Index: ch02.xml
===================================================================
--- ch02.xml (revision 1614)
+++ ch02.xml (working copy)
@@ -54,7 +54,7 @@
       example, a client can ask historical questions like, <quote>What
       did this directory contain last Wednesday?</quote> or <quote>Who
       was the last person to change this file, and what changes did
-      they make?</quote> These are the sorts of questions that are at
+      he make?</quote> These are the sorts of questions that are at
       the heart of any <firstterm>version control system</firstterm>:
       systems that are designed to record and track changes to data
       over time.

The use of 'they' as a gender-agnostic singular pronoun is pretty common, if 
perhaps not strictly grammatical. I would leave it.

@@ -531,8 +531,8 @@
           number selects an entire tree, a particular state of the
           repository after some committed change.  Another way to
           think about it is that revision N represents the state of
-          the repository filesystem after the Nth commit.  When a
-          Subversion user talks about <quote>revision 5 of
+          the repository filesystem after the Nth commit.  When
+          Subversion users talk about <quote>revision 5 of
           <filename>foo.c</filename></quote>, they really mean
           <quote><filename>foo.c</filename> as it appears in revision 
5.</quote>
           Notice that in general, revisions N and M of a file do

Ditto, I don't feel that this is necessary.


Index: ch03.xml
===================================================================
--- ch03.xml (revision 1614)
+++ ch03.xml (working copy)
@@ -178,7 +178,7 @@

 $ svn diff --revision HEAD
 # compares your working file (with local mods) to the latest version
-# in the repository.
+# in the repository

 $ svn diff --revision BASE:HEAD foo.c
 # compares your <quote>pristine</quote> foo.c (no local mods) with the

Good for consistency, but if _this_ full stop is going away, so should the 
others ~15 lines below.

@@ -1713,7 +1713,7 @@
         <varlistentry>
           <term><command>svn log</command></term>
           <listitem>
-            <para>Shows you broad information: log messages attached
+            <para>Shows you broad information: log messages with date and 
author information attached
               to revisions, and which paths changed in each
               revision.</para>
           </listitem>

Good, I think
.

Index: ch04.xml
===================================================================
--- ch04.xml (revision 1614)
+++ ch04.xml (working copy)
@@ -644,7 +644,7 @@
               tree-changes.</para>
           </footnote>
           The <command>svn merge</command> command, however, can express
-          tree-changes by directly applying them to your working
+          changes in tree structure and properties by directly applying 
them to your working
           copy.</para>

       </sidebar>

De-jargonizing! Good!

@@ -885,7 +885,7 @@
           Somebody can then run <command>svn log -r9238</command> to
           read about the exact changeset which fixed the bug, and run
           <command>svn diff -r9237:9238</command> to see the patch
-          itself.  And Subversion's merge command also uses revision
+          itself.  And Subversion's <command>merge</command> command also 
uses revision
           numbers.  You can merge specific changesets from one branch
           to another by naming them in the merge arguments:
           <command>svn merge -r9237:9238</command> would merge

Here we need to determine a convention. Does a subcommand name without a 
leading "svn" go in <command/> tags? Think especially of the case of "diff" 
which is a unix command in its own right. Elsewhere in the book, these have 
been put into <literal/> tags... which might actually end up formatted the 
same, now I think about it. Further instances of this kind of change are 
snipped from this email.

@@ -1010,18 +1010,18 @@
...
           notice that they're unrelated and first attempt to delete
           the old file, then add the new file;  you would see a
-          <literal>D  foo.c</literal> followed by a <literal>A
-          foo.c</literal>.</para>
+          <literal>D  foo.c</literal> followed by a
+          <literal>A  foo.c</literal>.</para>

Good. Do we need to check for more cases like this?

...
@@ -1319,7 +1319,7 @@
         directory, it may be gone from the <literal>HEAD</literal>
         revision, but the object still exists in earlier revisions.
         One of the most common questions new users ask is, <quote>How
-        do I get my old file or directory back?</quote></para>
+        do I get my old file or directory back?</quote>.</para>

       <para>The first step is to define exactly <emphasis
         role="bold">which</emphasis> item you're trying to resurrect.

Yes.

...
@@ -1910,7 +1910,7 @@
         changes made to your working copy, and you'd like a
         collaborator to see them.  Instead of running <command>svn
         diff</command> and sending a patch file (which won't capture
-        tree changes), you can instead use <command>svn copy</command>
+        tree changes, symlink changes or changes in properties), you can 
instead use <command>svn copy</command>
         to <quote>upload</quote> your working copy to a private area
         of the repository.  Your collaborator can then either checkout
         a verbatim copy of your working copy, or use <command>svn

Yes.

@@ -1983,8 +1983,8 @@
         working copies.  If a user has a working copy of a particular
         repository directory, your <command>svn move</command>
         operation might remove the path from the latest revision.
-        When the user next runs <command>svn update</command>, they'll
-        be told that their working copy represents a path that no
+        When the user next runs <command>svn update</command>, she will
+        be told that her working copy represents a path that no
         longer exists, and the user will be forced to <command>svn
         switch</command> to the new location.
         </para>

Ditto previous comments on "they", but un-contracting is good.

@@ -2039,7 +2039,7 @@
         branch.  In software development, though, it's also common to
         have two <quote>main</quote> branches running side-by-side for
         very long periods.  For example, suppose it's time to release
-        a stable <filename>calc</filename> project to the public, and
+        a stable version of the <filename>calc</filename> project to the 
public, and
         you know it's going to take a couple of months to shake bugs
         out of the software.  You don't want people to add new
         features to the project, but you don't want to tell all

Yes.

Index: ch05.xml
===================================================================
--- ch05.xml (revision 1614)
+++ ch05.xml (working copy)
@@ -1120,7 +1120,7 @@
           other queries, displaying subsets of bits of information
           we've mentioned previously, reporting which paths were
           modified in a given revision or transaction, showing textual
-          and property differences made to files and directories, and
+          and property differences made to files, symlinks and directories, 
and
           so on.  The following is a brief description of the current
           list of subcommands accepted by <command>svnlook</command>,
           and the output of those subcommands:</para>

Symlinks can sort of be considered a kind of file... and leaving it out here 
avoids confusing people who don't know about symlinks.

...
@@ -2020,7 +2020,7 @@
           equal to the size of the original data, it only takes up
           enough space to say, <quote>I look just like this other
           piece of data over here, except for the following couple of
-          changes.</quote> Specifically, each time a new version of a
+          changes</quote>. Specifically, each time a new version of a
           file is committed to the repository, Subversion encodes the
           previous version (actually, several previous versions) as a
           delta against the new version.  The result is that most of

Yes.

@@ -2237,7 +2237,7 @@
         requested range of revisions.  Note that <command>svnadmin
         dump</command> is reading revision trees from the repository
         just like any other <quote>reader</quote> process would
-        (<command>svn checkout</command>, for example.)  So it's safe
+        (<command>svn checkout</command>, for example).  So it's safe
         to run this command at any time.</para>

       <para>The other subcommand in the pair, <command>svnadmin

Yes.

@@ -2451,7 +2451,7 @@
         <command>cvs2svn</command> utility (see <xref
         linkend="svn.forcvs.convert"/>) uses the dump format to represent 
the
         contents of a CVS repository so that those contents can be
-        moved in a Subversion repository.</para>
+        copied into a Subversion repository.</para>

     </sect2>

Yes.


Index: ch06.xml
===================================================================
--- ch06.xml (revision 1614)
+++ ch06.xml (working copy)
@@ -5,7 +5,7 @@

     <para>A Subversion repository can be accessed simultaneously by
       clients running on the same machine on which the repository
-      resides using the <literal>file:///</literal> method.  But the
+      resides using the <literal>file://</literal> method.  But the
       typical Subversion setup involves a single server machine being
       accessed from clients on computers all over the office—or,
       perhaps, all over the world.</para>

I think this should stay as is. People who don't care about the details will 
be more likely to get it right, and people who do care will understand that 
the third slash is in recognition of the fact that the file:// URL scheme 
authority component should be left empty.

@@ -398,7 +398,7 @@
       <para>If the client successfully authenticates by any of the
         methods listed above, it will attempt to cache the credentials
         on disk (unless the user has disabled this behavior, as
-        mentioned earlier.)</para>
+        mentioned earlier).</para>

     </sect2>

@@ -512,7 +512,7 @@
           repository directly needs to have proper read and write
           permissions on the entire repository.  If you're not
           careful, this can lead to a number of headaches, especially
-          if you're using a BerkeleyDB database rather than FSFS.  Be
+          if you're using a Berkeley DB database rather than FSFS.  Be
           sure to read <xref 
linkend="svn.serverconfig.multimethod"/>.</para>

         <para>Secondly, when configuring <command>svnserve</command>,
@@ -645,7 +645,7 @@
           client displays it in the authentication prompt, and uses it
           as a key (along with the server's hostname and port) for
           caching credentials on disk (see <xref
-          linkend="svn.serverconfig.netmodel.credcache"/>.)  The
+          linkend="svn.serverconfig.netmodel.credcache"/>).  The
           <literal>password-db</literal> variable points to a separate
           file that contains a list of usernames and passwords, using
           the same familiar format.  For example:</para>
@@ -823,7 +823,7 @@
       <para>You'd think that the story of SSH tunneling would end
         here, but it doesn't.  Subversion allows you to create custom
         tunnel behaviors in your run-time <filename>config</filename>
-        file (see <xref linkend="svn.advanced.confarea"/>.)  For example,
+        file (see <xref linkend="svn.advanced.confarea"/>).  For example,
         suppose you want to use RSH instead of SSH.  In the
         <literal>[tunnels]</literal> section of your
         <filename>config</filename> file, simply define it like
@@ -842,7 +842,7 @@
         scenes.  If you include a username in the URL (for example,
         <literal>svn+rsh://username@host/path</literal>) the client
         will also include that in its command (<command>rsh
-        username at host svnserve -t</command>.)  But you can define new
+        username at host svnserve -t</command>).  But you can define new
         tunneling schemes to be much more clever than that:</para>

 <screen>
@@ -1016,7 +1016,7 @@
       available to clients via the WebDAV/DeltaV protocol, which is an
       extension to HTTP 1.1
       (see <systemitem class="url">http://www.webdav.org/</systemitem>
-      for more information.) This protocol takes the ubiquitous HTTP
+      for more information). This protocol takes the ubiquitous HTTP
       protocol that is the core of the World Wide Web, and adds
       writing—specifically, versioned
       writing—capabilities.  The result is a standardized,
@@ -1497,7 +1497,7 @@
           will be cached in your private run-time
           <filename>auth/</filename> area in just the same way your
           username and password are cached (see <xref
-          linkend="svn.serverconfig.netmodel.credcache"/>.)  If cached, 
Subversion will
+          linkend="svn.serverconfig.netmodel.credcache"/>).  If cached, 
Subversion will
           automatically remember to trust this certificate in future
           negotiations.</para>

@@ -2248,7 +2248,7 @@
 </screen>

     <para>Another common problem is often encountered on Unix-like
-      systems.  As a repository is used, BerkeleyDB occasionally
+      systems.  As a repository is used, Berkeley DB occasionally
       creates new log files to journal its actions.  Even if the
       repository is wholly owned by the <command>svn</command> group,
       these newly created files won't necessarily be owned by that

Yes to all of the above.


Max.




More information about the svnbook-dev mailing list