[PATCH] Review notes on Subversion book: chapters 5 and 6

Eric Hanchrow offby1 at blarg.net
Fri Mar 16 13:52:38 CDT 2007

Index: ch05-repository-admin.xml
--- ch05-repository-admin.xml	(revision 2737)
+++ ch05-repository-admin.xml	(working copy)
@@ -92,8 +92,8 @@
-          <para>A file whose contents are a single integer value that
-            dictates the version number of the repository layout.</para>
+          <para>A file that contains a single integer that
+            indicates the version number of the repository layout.</para>
@@ -144,12 +144,12 @@
       creating and configuring a repository are fairly straightforward
       tasks.  There are a few preliminary decisions you'll want to
       make, but the actual work involved in any given setup of a
-      Subversion repository is pretty straightforward, tending towards
+      Subversion repository is pretty straightforward, <!-- do we
+      really want to say this? --> tending towards
       mindless repetition if you find yourself setting up multiples of
       these things.</para>
-    <para>Some of things you'll want to consider up front, though, are
-      as follows:</para>
+    <para>Some things you'll want to consider up front, though, are:</para>
@@ -390,8 +390,8 @@
         at all because only one of the available back-ends will work
         in this scenario.</para>
-      <para>To try to address each and every possible way to deploy
-        Subversion is both not possible and outside the scope of this
+      <para>Addressing each possible way to deploy
+        Subversion is both impossible, and outside the scope of this
         book.  We simply encourage you to evaluate your options using
         these pages and other sources as your reference material, and
         plan ahead.</para>
@@ -419,7 +419,10 @@
             however, assumes that the reader is thinking
-        —a versioned filesystem implementation that uses the
+       —a versioned filesystem implementation <!-- this implies
+       that BDB, somehow, _doesn't_ use the native OS filesystem to
+       store data, which isn't true -->
+                                                    that uses the
         native OS filesystem to store data.</para>
       <para><xref linkend="svn.reposadmin.basics.backends.tbl-1" />
@@ -708,7 +711,7 @@
           waiting for a response.</para>
         <para>The most important distinction, however, is FSFS's
-          inability to be <quote>wedged</quote> when something goes
+          imperviousness to <quote>wedging</quote> when something goes
           wrong.  If a process using a Berkeley DB database runs into
           a permissions problem or suddenly crashes, the database can
           be left in an unusable state until an administrator recovers
@@ -843,7 +846,13 @@
         report what is about to happen and to prevent it from
         happening at all.  Other hooks (the <quote>post hooks</quote>)
         run after the completion of a repository event, and are useful
-        for reporting purposes only.  Each hook is handed enough
+        for reporting purposes only. <!-- not strictly true; the
+        post-commit hook often causes an "svn up" to run somewhere.
+        You _might_ claim that that's an example of reporting, but
+        that would be straining the definition of "reporting".
+        Perhaps we should say something like "... are useful only for
+        things that examine, rather than modify, the repos" -->
+                                      Each hook is handed enough
         information to tell what that event is (or was), the specific
         repository changes proposed (or completed), and the username
         of the person who triggered the event.</para>
@@ -886,6 +895,9 @@
         need to supply a program whose basename is the name of the
         hook, and whose extension is one of the special extensions
         recognized by Windows for executable programs, such as
+        <!-- even though .com is, strictly speaking, supported on
+        Windows, I suspect in practice it's a bad idea to create .com
+        files.  So maybe we shouldn't mention them at all. -->
         <filename>.exe</filename> or <filename>.com</filename> for
         programs, and <filename>.bat</filename> for batch
@@ -902,6 +914,9 @@
           and/or use absolute paths to programs.</para>
+      <!-- "will attempt to"?  Are there cases when this can fail?  if
+      so, what are they?  If not, why not just say "Subversion
+      executes hooks as ..." -->
       <para>Subversion will attempt to execute hooks as the same user
         who owns the process which is accessing the Subversion
         repository.  In most cases, the repository is being accessed
@@ -920,10 +935,11 @@
         <xref linkend="svn.ref.reposhooks" />.  As a repository
         administrator, you'll need to decide which of hooks you wish
         to implement (by way of providing an appropriately named and
-        permissioned hook program), and how.  This decision needs to
-        be made with the bigger picture of how repository is deployed
-        in mind.  For example, if you are using server configuration
-        stuffs to determine which usernames are permitted to commit
+        permissioned hook program), and how.  When you make this
+        decision, keep in mind
+        the big picture of how your repository is deployed.
+        For example, if you are using server configuration
+        to determine which users are permitted to commit
         changes to your repository, then you don't need to do this
         sort of access control via the hook system.</para>
@@ -938,7 +954,7 @@
         linkend="svn.developer" />.</para>
-        <para>While hook scripts can be leveraged to do almost
+        <para>While hook scripts can do almost
           anything, there is one dimension in which hook script
           authors should show restraint: do <emphasis>not</emphasis>
           modify a commit transaction using hook scripts.  While it
@@ -952,7 +968,7 @@
           behavior.  Instead of modifying the transaction, you should
           simply <emphasis>validate</emphasis> the transaction in the
           <filename>pre-commit</filename> hook and reject the commit
-          if it does not meet the desired requirements.  As an added
+          if it does not meet the desired requirements.  As a
           bonus, your users will learn the value of careful,
           compliance-minded work habits.</para>
@@ -979,15 +995,10 @@
         applications and database environments have different
         requirements, and so they have provided a mechanism for
         overriding at runtime many of the configuration values for the
-        Berkeley DB environment.  Berkeley checks for the presence of
+        Berkeley DB environment: bdb checks for the presence of
         a file named <filename>DB_CONFIG</filename> in the environment
-        directory, and parses the options found in that file for use
-        with that particular Berkeley DB environment.</para>
-      <para>The Berkeley DB configuration file for a BDB-backed
-        repository is located in the repository's
-        <filename>db</filename> subdirectory, at
-        <filename>db/DB_CONFIG</filename>.  Subversion itself creates
+        directory (namely, the repository's
+        <filename>db</filename> subdirectory), and parses the options found in that file .  Subversion itself creates
         this file when it creates the rest of the repository.  The
         file initially contains some default options, as well as
         pointers to the Berkeley DB online documentation so you can
@@ -1013,7 +1024,7 @@
   <sect1 id="svn.reposadmin.maint">
     <title>Repository Maintenance</title>
-    <para>Maintaining a Subversion repository can be a daunting task,
+    <para>Maintaining a Subversion repository can be daunting,
       mostly due to the complexities inherent in systems which have a
       database backend.  Doing the task well is all about knowing the
       tools—what they are, when to use them, and how to use
@@ -1062,7 +1073,7 @@
         <para>We've already mentioned <command>svnadmin</command>'s
           <literal>create</literal> subcommand (see <xref
           linkend="svn.reposadmin.basics.creating"/>).  Most of the
-          others we will cover as they become topically relevant later
+          others we will cover later
           in this chapter.  And you can consult <xref
           linkend="svn.ref.svnadmin" /> for a full rundown of
           subcommands and what each of them offers.</para>
@@ -1075,6 +1086,9 @@
         <para><command>svnlook</command> is a tool provided by
           Subversion for examining the various revisions and
+          <!-- we haven't introduced transactions yet.  Should we thus
+          use <firstterm>, or include a link to a section that
+          discusses them in detail, or what? -->
           transactions in a repository.  No part of this program
           attempts to change the repository.  <command>svnlook</command>
           is typically used by the repository hooks for reporting the
@@ -1161,6 +1175,8 @@
             <para>The date, followed by a newline.</para>
+          <!-- it might be worth noting that the number of characters
+          is not necessarily the same as the number of bytes. -->
             <para>The number of characters in the log message,
               followed by a newline.</para>
@@ -1315,7 +1331,7 @@
           recover</command> reflects the common use cases of the
           <command>db_recover</command> utility.</para>
-        <para>There are still a few Berkeley DB utilities that you
+        <para>However, there are still a few Berkeley DB utilities that you
           might find useful.  The <command>db_dump</command> and
           <command>db_load</command> programs write and read,
           respectively, a custom file format which describes the keys
@@ -1323,7 +1339,10 @@
           databases are not portable across machine architectures,
           this format is a useful way to transfer those databases from
           machine to machine, irrespective of architecture or
-          operating system.  Also, the <command>db_stat</command>
+          operating system. <!-- why on Earth would I use db_dump instead
+          of "svnadmin dump"?  You should probably explain that,
+          or else don't even mention them. -->
+                             Also, the <command>db_stat</command>
           utility can provide useful information about the status of
           your Berkeley DB environment, including detailed statistics
           about the locking and storage subsystems.</para>
@@ -1345,6 +1364,8 @@
         misspelling or some misinformation, perhaps).  If the
         repository is configured (using the
         <literal>pre-revprop-change</literal> and
+        <!-- I don't think post-revprop-change is necessary to allow
+        changes to log messages -->
         <literal>post-revprop-change</literal> hooks; see <xref
         linkend="svn.reposadmin.create.hooks"/>) to accept changes to this log
         message after the commit is finished, then the user can
@@ -1366,12 +1387,13 @@
 $ svnadmin setlog myrepos newlog.txt -r 388
-      <para>The <command>svnadmin setlog</command> command alone is
+      <para>The <command>svnadmin setlog</command> command, by
+        default, is
         still bound by the same protections against modifying
         unversioned properties as a remote client is—the
         <literal>pre-</literal> and
         <literal>post-revprop-change</literal> hooks are still
-        triggered, and therefore must be setup to accept changes of
+        triggered, and therefore must be set up to accept changes of
         this nature.  But an administrator can get around these
         protections by passing the <option>--bypass-hooks</option>
         option to the <command>svnadmin setlog</command> command.</para>
@@ -1396,7 +1418,7 @@
         past few years, disk usage is still a valid concern for
         administrators seeking to version large amounts of data.
         Every bit of version history information stored in the live
-        repository is information that needs to be backed up
+        repository needs to be backed up
         elsewhere, perhaps multiple times as part of rotating backup
         schedules.  It is useful to know what pieces of Subversion's
         repository data need to remain on the live site, which need to
@@ -1406,7 +1428,7 @@
       <sect3 id="svn.reposadmin.maint.diskspace.deltas">
         <title>How Subversion saves disk space</title>
-        <para>To keep the size of the repository as small as possible,
+        <para>To keep the repository small,
           Subversion uses <firstterm>deltification</firstterm> (or,
           <quote>deltified storage</quote>) within the repository
           itself.  Deltification involves encoding the representation
@@ -1418,11 +1440,11 @@
           enough space to say, <quote>I look just like this other
           piece of data over here, except for the following couple of
           changes</quote>.  The result is that most of the repository
-          data that tends to be sizable—namely, the contents of
+          data that tends to be bulky—namely, the contents of
           versioned files—is stored at a much smaller size than
           the original <quote>fulltext</quote> representation of that
           data.  And for repositories created with Subversion 1.4 or
-          later, the space saving get even better—now those
+          later, the space saving is even better—now those
           fulltext representations of file contents are themselves
@@ -1452,7 +1474,7 @@
           directory changes associated with it.  This could happen for
           several reasons: perhaps the client operation was
           inelegantly terminated by the user, or a network failure
-          might have occurred in the middle of an operation, etc.
+          occurred in the middle of an operation.
           Regardless of the reason, dead transactions can happen.
           They don't do any real harm, other than consuming disk
           space.  A fastidious administrator may nonetheless wish to
@@ -1476,7 +1498,8 @@
           created the transaction, when it was created, what types of
           changes were made in the transaction—information that
           is helpful in determining whether or not the transaction is
-          a safe candidate for removal!  If so, the transaction's name
+          a safe candidate for removal!  If you do indeed want to
+          remove a transaction, its name
           can be passed to <command>svnadmin rmtxns</command>, which
           will perform the cleanup of the transaction.  In fact, the
           <literal>rmtxns</literal> subcommand can take its input
@@ -1569,21 +1592,21 @@
           before modifying the actual database files.  These files
           capture all the actions taken along the route of changing
           the database from one state to another—while the
-          database files reflect at any given time some state, the log
-          files contain all the many changes along the way between
-          states.  As such, they can grow and accumulate quite
+          database files, at any given time, reflect a particular state, the log
+          files contain all the many changes along the way <emphasis>between</emphasis>
+          states.  Thus, they can grow and accumulate quite
         <para>Fortunately, beginning with the 4.2 release of Berkeley
           DB, the database environment has the ability to remove its
-          own unused log files without any external procedures.  Any
+          own unused log files automatically.  Any
           repositories created using an <command>svnadmin</command>
           which is compiled against Berkeley DB version 4.2 or greater
           will be configured for this automatic log file removal.  If
           you don't want this feature enabled, simply pass the
           <option>--bdb-log-keep</option> option to the
           <command>svnadmin create</command> command.  If you forget
-          to do this, or change your mind at a later time, simple edit
+          to do this, or change your mind at a later time, simply edit
           the <filename>DB_CONFIG</filename> file found in your
           repository's <filename>db</filename> directory, comment out
           the line which contains the <literal>set_flags
@@ -1605,6 +1628,8 @@
           list-unused-dblogs</command> command to list the unused
           log files:</para>
+        <!-- why does this example use xargs, whereas an earlier
+        example about rmtxns used backticks? -->
 $ svnadmin list-unused-dblogs /path/to/repos
@@ -1620,8 +1645,8 @@
             as part of a backup or disaster recovery plan should
             <emphasis>not</emphasis> make use of the log file
             autoremoval feature.  Reconstruction of a repository's
-            data from log files can only be accomplished when the log
-            files are all available.  If some of the log files are
+            data from log files can only be accomplished when <emphasis>all</emphasis> the log
+            files are available.  If some of the log files are
             removed from disk before the backup system has a chance to
             copy them elsewhere, the incomplete set of backed-up log
             files is essentially useless.</para>
@@ -1684,7 +1709,7 @@
         can permanently destroy a database environment.  A
         sufficiently paranoid repository administrator will have made
         off-site backups of the repository data in some fashion, but
-        head off to the tape backup storage closet just yet.</para>
+        don't head off to the tape backup storage closet just yet.</para>
       <para>Instead, use the following recipe to attempt to
         <quote>unwedge</quote> your repository:</para>
@@ -1736,6 +1761,8 @@
       <para>If the previous procedure, for some reason, does not
         successfully unwedge your repository, you should do two
+        <!-- do our readers know what "move out of the way" means?
+        Should we explain in detail? -->
         things.  First, move your broken repository out of the way and
         restore your latest backup of it.  Then, send an email to the
         Subversion user list (at
@@ -1750,7 +1777,7 @@
       <title>Migrating Repository Data Elsewhere</title>
       <para>A Subversion filesystem has its data spread throughout
-        various back-end data store files in a fashion generally
+        files in the repository, in a fashion generally
         understood by (and of interest to) only the Subversion
         developers themselves.  However, circumstances may arise that
         call for all, or some subset, of that data to be copied or
@@ -1762,7 +1789,8 @@
         on disk) is a portable, flat file format that describes the
         various revisions in your repository—what was changed,
         by whom, when, and so on.  This dump stream is the primary
-        mechanism used to marshal versioned history—in whole or
+        mechanism used to <!-- do our readers know the term "marshal"? -->
+                          marshal versioned history—in whole or
         in part, with or without modification—between
         repositories.  And Subversion provides the tools necessary for
         creating and loading these dump streams—the
@@ -1774,10 +1802,10 @@
           human-readable portions and a familiar structure (it
           resembles an RFC-822 format, the same type of format used
           for most email), it is <emphasis>not</emphasis> a plaintext
-          file format.  The format should be treated as a binary file
-          format, highly sensitive to meddling.  Many text editor
-          tools will corrupt the file's contents, often due to
-          automatic line ending character conversion.</para>
+          file format: It is a binary file
+          format, highly sensitive to meddling.  For example, many text editors
+          will corrupt the file by automatically converting
+          line endings.</para>
       <para>There are many reasons for dumping and loading Subversion
@@ -1797,10 +1825,10 @@
         re-deploying a Berkeley DB repository on a new OS or CPU
         architecture, switching between the Berkeley DB and FSFS
         back-ends, or (as we'll cover in <xref
-        linkend="svn.reposadmin.maint.filtering" /> purging versioned
+        linkend="svn.reposadmin.maint.filtering" />), purging versioned
         data from repository history.</para>
-      <para>Whatever your reason for migration repository history,
+      <para>Whatever your reason for migrating repository history,
         using the <command>svnadmin dump</command> and
         <command>svnadmin load</command> subcommands is
         straightforward.  <command>svnadmin dump</command> will output
@@ -1830,7 +1858,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
@@ -1885,8 +1913,7 @@
         course, you should use these options with care—if your
         post-commit hook sends emails to a mailing list for each new
         commit, you might not want to spew hundreds or thousands of
-        commit emails in rapid succession at that list for each of the
-        loaded revisions!  You can read more about the use of hook
+        commit emails in rapid succession at that list!  You can read more about the use of hook
         scripts in <xref
@@ -1898,7 +1925,7 @@
 $ svnadmin create newrepos
-$ svnadmin dump myrepos | svnadmin load newrepos
+$ svnadmin dump oldrepos | svnadmin load newrepos
       <para>By default, the dump file will be quite large—much
@@ -1942,7 +1969,7 @@
         revision.  For one thing, there is no previous revision in the
         dump file!  And secondly, Subversion cannot know the state of
         the repository into which the dump data will be loaded (if it
-        ever, in fact, occurs).  To ensure that the output of each
+        ever is).  To ensure that the output of each
         execution of <command>svnadmin dump</command> is
         self-sufficient, the first dumped revision is by default a
         full representation of every directory, file, and property in
@@ -1984,7 +2011,7 @@
         nightly to append dump file data for all the revisions that
         were added to the repository since the last time the script
         ran.  Used like this, <command>svnadmin dump</command> can be
-        one way to backup changes to your repository over time in case
+        one way to back up changes to your repository over time in case
         of a system crash or some other catastrophic event.</para>
       <para>The dump format can also be used to merge the contents of
@@ -2192,8 +2219,8 @@
         <para>If you do plan on manually editing the dump file to
           remove a top-level directory, make sure that your editor is
-          not set to automatically convert end-lines to the native
-          format (e.g. \r\n to \n) as the content will then not agree
+          not set to automatically convert end-of-line characters to the native
+          format (e.g. \r\n to \n), as the content will then not agree
           with the metadata.  This will render the dump file
@@ -2308,6 +2335,9 @@
         readily available.  If you suspect that you have any copies
         of this sort in your repository, you might want to rethink
         your set of included/excluded paths.</para>
+      <!-- ick.  Can you point to a detailed explanation of 1) how to
+        recognize this situation if I accidentally stumble into it,
+        and 2) what to do about it? -->
       <para>Finally, <command>svndumpfilter</command> takes path
         filtering quite literally.  If you are trying to copy the
@@ -2665,7 +2695,7 @@
         time throughout the lifetime of the repository, and don't
         leave an audit trail that indicates when they were changed,
         replication processes have to pay special attention to them.
-        If you've already mirror the first 15 revisions of a
+        If you've already mirrored the first 15 revisions of a
         repository and someone then changes a revision property on
         revision 12, <command>svnsync</command> won't know to go back
         and patch up its copy of revision 12.  You'll need to tell it
@@ -2729,11 +2759,12 @@
         linkend="svn.ref.svn.c.switch" />.  There is a possible danger
         here, though, in that if the primary and mirror repositories
         aren't in close synchronization, a working copy up-to-date
-        with and pointing to the primary repository will, if relocated
+        with, and pointing to, the primary repository will, if relocated
         to point to an out-of-date mirror, become confused about the
         apparent sudden loss of revisions it fully expects to be
+      <!-- How would I recognize this "confusion" if I saw it?  How do
+        I recover from it? -->
       <para>Finally, be aware that the revision-based replication
         provided by <command>svnsync</command> is only
         that—replication of revisions.  It does not include such
@@ -2764,7 +2795,7 @@
         incremental.  A full backup of the repository involves
         squirreling away in one sweeping action all the information
         required to fully reconstruct that repository in the event of
-        a catastrophe.  Usually, it means quite literally the
+        a catastrophe.  Usually, it means, quite literally, the
         duplication of the entire repository directory (which includes
         either a Berkeley DB or FSFS environment).  Incremental
         backups are lesser things, backups of only the portion of the
@@ -2821,8 +2852,8 @@
         regular basis.  For example, you might consider using
         <command>hot-backup.py</command> from a program scheduler
         (such as <command>cron</command> on Unix systems) which will
-        cause it to run nightly (or at whatever granularity of Time
-        you deem safe enough for you).</para>
+        cause it to run nightly (or at whatever granularity of time
+        you deem safe).</para>
       <para>Some administrators use a different backup mechanism built
         around generating and storing repository dump data.  We
@@ -2831,7 +2862,7 @@
         perform an incremental backup of a given revision or range of
         revisions.  And of course, there is a full backup variation of
         this achieved by omitting the <option>--incremental</option>
-        option to that command.  There is some value in these methods
+        option to that command.  There is some value in these methods,
         in that the format of your backed-up information is
         flexible—it's not tied to a particular platform,
         versioned filesystem type, or release of Subversion or
Index: ch06-server-configuration.xml
--- ch06-server-configuration.xml	(revision 2737)
+++ ch06-server-configuration.xml	(working copy)
@@ -100,6 +100,8 @@
+            <!-- might it be worthwhile to mention that you can get a
+            kind of authorization by using pre-commit hooks? -->
             <entry>Authorization options</entry>
             <entry>read/write access can be granted over whole
               repository, or specified per-path.</entry>
@@ -136,6 +138,14 @@
             <entry>Web viewing</entry>
             <entry>limited built-in support, or via 3rd-party tools
               such as ViewVC</entry>
+            <!-- does viewvc officially support remote repos access?
+              If not, we shouldn't mention it here.  I might be
+              misunderstanding the point of this row - I -think-
+              you're talking about "ways of browsing your repo _that
+              use_ these access methods", as opposed to "ways of
+              browsing your repo _when you use these access methods to
+              do commits, checkouts, and other typical svn
+              operatioins".  See the difference? -->
             <entry>only via 3rd-party tools such as ViewVC</entry>
             <entry>only via 3rd-party tools such as ViewVC</entry>
@@ -262,9 +272,12 @@
             <listitem><para>Requires users to be in same system group, or
+                <!-- this might need clarification.  If users share an
+                ssh key, that only helps if they're also _logging in
+                as the same user_.  Or am I misunderstanding? -->
                 use a shared ssh key.</para></listitem>
-            <listitem><para>Can lead to file permissions
+            <listitem><para>If used improperly, can lead to file permissions
@@ -339,7 +352,7 @@
         <command>svnserve</command> installation for small teams just
         trying to get started with a Subversion server; it's the
         simplest to set up, and has the fewest maintenance issues.
-        Remember, you can always switch to a more complex server
+        You can always switch to a more complex server
         deployment as your needs change.</para>
       <para>Here are some general recommendations and tips, based on
@@ -409,7 +422,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>
@@ -471,12 +484,14 @@
 $               # svnserve is now running, listening on port 3690
+        <!-- is it worth saying pretty much what
+        http://subversion.tigris.org/faq.html#freebsd-listen-host says ?  -->
         <para>When running <command>svnserve</command> in daemon mode,
           you can use the <option>--listen-port=</option> and
           <option>--listen-host=</option> options to customize the
           exact port and hostname to <quote>bind</quote> to.</para>
-      <para>Once the <command>svnserve</command> program is running,
+      <para>Once we successfully start <command>svnserve</command> as above,
         it makes every repository on your system available to the
         network.  A client needs to specify an
         <emphasis>absolute</emphasis> path in the repository URL.  For
@@ -510,9 +525,14 @@
       <sect3 id="svn.serverconfig.svnserve.invoking.inetd">
         <title><command>svnserve</command> via <command>inetd</command></title>
-        <para>If you want <command>inetd</command> launch the process,
-          then you can pass the <option>-i</option>
-          (<option>--inetd</option>) option:</para>
+        <para>If you want <command>inetd</command> to launch the
+          process, then you need to pass the <option>-i</option>
+          (<option>--inetd</option>) option.  Just below, we've shown the
+          output from running <literal>svnserve -i</literal> at the
+          command line, but note that isn't how you actually start the
+          daemon; see the paragraphs following the example for how to
+          configure <command>inetd</command> to
+          start <command>svnserve</command>.</para>
 $ svnserve -i
@@ -563,7 +583,10 @@
           such as <command>RSH</command> or <command>SSH</command> has
           successfully authenticated a user and is now invoking a
           private <command>svnserve</command> process <emphasis>as
-          that user</emphasis>.  The <command>svnserve</command>
+          that user</emphasis>.  (Note that you, the user, will rarely,
+          if ever, have reason to invoke <command>svnserve</command>
+          with the <option>-t</option> at the command line; instead,
+          the <command>SSH</command> daemon does so for you.)  The <command>svnserve</command>
           program behaves normally (communicating via
           <emphasis>stdin</emphasis> and <emphasis>stdout</emphasis>),
           and assumes that the traffic is being automatically
@@ -644,7 +667,7 @@
         <para>Once the service is defined, it can stopped, started, or
-          queried using standard GUI tools (The Services
+          queried using standard GUI tools (the Services
           administrative control panel), or at the command line as
@@ -657,7 +680,7 @@
           deleting its definition:  <literal>sc delete svn</literal>.
           Just be sure to stop the service first!
           The <command>SC.EXE</command> program has many other
-          subcommands and options, run <literal>sc /?</literal> to
+          subcommands and options; run <literal>sc /?</literal> to
           learn more about it.</para>
@@ -676,6 +699,9 @@
         <listitem><para>The server processes the repository's
+            <!-- svn.serverconfig.overview.tbl-1 effectively says that
+            you can't do any authorization via svnserve; why, then,
+            does the server "enforce ... authorization policies"? -->
         <filename>conf/svnserve.conf</filename> file, and begins to
         enforce any authentication and authorization policies defined
@@ -726,7 +752,7 @@
         <literal>]</literal>), comments begin with hashes
         (<literal>#</literal>), and each section contains
         specific variables that can be set (<literal>variable =
-        value</literal>).  Let's walk through this file and learn how
+        value</literal>).  Let's walk through these files and learn how
         to use them.</para>
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -735,8 +761,9 @@
         <para>For now, the <literal>[general]</literal> section of the
           <filename>svnserve.conf</filename> has all the variables you
-          need.  Begin by defining a file which contains usernames and
-          passwords, and an authentication realm:</para>
+          need.  Begin by changing the values of those variables: choose a name for a file which will
+          contain your usernames and
+          passwords, and choose an authentication realm:</para>
@@ -744,6 +771,9 @@
 realm = example realm
+        <!-- what are the restrictions on the realm - may it be any
+        length; may it contain non-ASCII characters, if so, must it
+        use a particular encoding ... ? -->
         <para>The <literal>realm</literal> is a name that you define.
           It tells clients which sort of <quote>authentication
           namespace</quote> they're connecting to; the Subversion
@@ -789,7 +819,7 @@
           and <literal>auth-access</literal> can be set to the values
           <literal>none</literal>, <literal>read</literal>, or
           <literal>write</literal>.  Setting the value to
-          <literal>none</literal> restricts all access of any kind;
+          <literal>none</literal> prohibits both reading and writing;
           <literal>read</literal> allows read-only access to the
           repository, and <literal>write</literal> allows complete
           read/write access to the repository.  For example:</para>
@@ -893,7 +923,7 @@
         <command>ssh</command>, the tunnel-agent.
         <command>svnserve</command> is aware that it's running as the
         user <literal>harry</literal>, and if the client performs a
-        commit, the authenticated username will be attributed as the
+        commit, the authenticated username will be used as the
         author of the new revision.</para>
       <para>The important thing to understand here is that the
@@ -946,7 +976,9 @@
         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,
-        suppose you want to use RSH instead of SSH.  In the
+        suppose you want to use RSH instead of SSH<footnote><para>We
+        don't actually recommend this, since RSH is notably less
+        secure than SSH.</para></footnote>.  In the
         <literal>[tunnels]</literal> section of your
         <filename>config</filename> file, simply define it like
@@ -1034,7 +1066,8 @@
         <para>The first field describes the type of key, the second
-          field is the uuencoded key itself, and the third field is a
+          field is the <!-- well, base64-encoded, actually ... -->
+                       uuencoded key itself, and the third field is a
           comment.  However, it's a lesser known fact that the entire
           line can be preceded by a <literal>command</literal>
@@ -1351,6 +1384,8 @@
         <command>mod_dav_svn</command> to return
         <filename>foo.c</filename> from the Subversion
+      <!-- what will the symptom look like?  i.e., assuming someone
+        _does_ make this mistake, what will they see? -->
         <title>Server Names and the COPY Request</title>
@@ -1403,7 +1438,8 @@
         aware that permission-related problems are perhaps the most
         common oversight when configuring a Subversion repository for
         use with Apache.</para>
+      <!-- again, it would be useful to include some examples of
+        common mistakes, along with the output of each -->
     <!-- =============================================================== -->
@@ -1429,7 +1465,7 @@
-          <para>anyone can use their Subversion client to checkout a
+          <para>anyone can use their Subversion client to check out a
             working copy of a repository URL (or any of its
@@ -1459,8 +1495,7 @@
           username and password to verify that a user is who she says
           she is.  Apache provides an <command>htpasswd</command>
           utility for managing the list of acceptable usernames and
-          passwords, those to whom you wish to grant special access to
-          your Subversion repository.  Let's grant commit access to
+          passwords.  Let's grant commit access to
           Sally and Harry.  First, we need to add them to the password
@@ -1547,7 +1582,7 @@
             <para>While self-signed server certificates are still
               vulnerable to a <quote>man in the middle</quote> attack,
-              such an attack is still much more difficult for a casual
+              such an attack is much more difficult for a casual
               observer to pull off, compared to sniffing unprotected
@@ -1622,13 +1657,13 @@
         <para>This dialogue should look familiar; it's essentially the
           same question you've probably seen coming from your web
-          browser (which is just another HTTP client like Subversion!).
+          browser (which is just another HTTP client like Subversion).
           If you choose the (p)ermanent option, the server certificate
           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 automatically remember to trust this certificate
+          Subversion will automatically trust this certificate
           in future negotiations.</para>
         <para>Your run-time <filename>servers</filename> file also gives
@@ -2088,7 +2123,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
@@ -2194,7 +2229,7 @@
         <title>Apache Logging</title>
         <para>Because Apache is an HTTP server at heart, it contains
-          fantastically flexible logging feature.  It's beyond the
+          fantastically flexible logging features.  It's beyond the
           scope of this book to discuss all ways logging can be
           configured, but we should point out that even the most
           generic <filename>httpd.conf</filename> file will cause
@@ -2219,7 +2254,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
@@ -2637,7 +2672,9 @@
       these newly created files won't necessarily be owned by that
       same group, which then creates more permissions problems for
       your users.  A good workaround is to set the group SUID bit on
-      the repository's <filename>db</filename> directory.  This causes
+      the repository's <filename>db</filename> directory. <!-- I'm 99%
+      sure "svnadmin create" does this for you. -->
+                                                           This causes
       all newly-created log files to have the same group owner as the
       parent directory.</para>
@@ -2660,6 +2697,8 @@
       We recommend you choose the server that best meets your needs
       and stick with it!</para>
+    <!-- this is another sidebar that could use an anchor, so that I
+    can easly hand out a URL to it. -->
       <title>The svn+ssh:// server checklist</title>
@@ -2673,19 +2712,25 @@
           <para>All of your SSH users need to be able to read and
-            write to the repository.  Put all the SSH users into a
-            single group.  Make the repository wholly owned by that
-            group, and set the group permissions to read/write.</para>
+            write to the repository, so: put all the SSH users into a
+            single group. </para>
+          <para>
+            Make the repository wholly owned by that
+            group.
+            </para></listitem>
+        <listitem><para>Set the group permissions to read/write.</para></listitem>
+        <listitem>
           <para>Your users need to use a sane umask when accessing the
-            repository.  Make sure that <command>svnserve</command>
+            repository, so: Make sure that <command>svnserve</command>
             (<filename>/usr/bin/svnserve</filename>, or wherever
             it lives in <literal>$PATH</literal>) is actually a
             wrapper script which sets <command>umask 002</command> and
             executes the real <command>svnserve</command>
-            binary.  Take similar measures when using
+            binary.  </para></listitem>
+        <listitem><para>Take similar measures when using
             <command>svnlook</command> and
             <command>svnadmin</command>.  Either run them with a sane
             umask, or wrap them as described above.</para>

It is a truth universally acknowledged, that any language in
possession of a rich syntax, must be in want of a rewrite.
        -- Piers Cawley

More information about the svnbook-dev mailing list