[SvnBook] #64: [PATCH] Hanchrow review [ch7:ch8]

SvnBook noreply at red-bean.com
Fri Aug 10 21:08:42 CDT 2007


#64: [PATCH] Hanchrow review [ch7:ch8]
-------------------------+--------------------------------------------------
 Reporter:  cmpilato     |       Owner:  nobody       
     Type:  enhancement  |      Status:  new          
 Priority:  normal       |   Milestone:  1.5          
Component:  content      |     Version:  nightly/trunk
 Keywords:               |  
-------------------------+--------------------------------------------------
 From: Eric Hanchrow <offby1 at blarg.net>

 {{{
 Index: ch07-customizing-svn.xml
 ===================================================================
 --- ch07-customizing-svn.xml    (revision 2737)
 +++ ch07-customizing-svn.xml    (working copy)
 @@ -19,7 +19,7 @@
        controlled by the user.  Many of these options are of the kind
        that a user would wish to apply to all Subversion operations.
        So, rather than forcing users to remember command-line arguments
 -      for specifying these options, and to use them for each and every
 +      for specifying these options, and to use them for every
        operation they perform, Subversion uses configuration files,
        segregated into a Subversion configuration area.</para>

 @@ -128,10 +128,11 @@
        </para>

        <para>Registry-based configuration options are parsed
 -        <emphasis>before</emphasis> their file-based counterparts,
 -        so are overridden by values found in the configuration
 -        files.  In other words, configuration priority is granted in
 -        the following order on a Windows system:</para>
 +        <emphasis>before</emphasis> their file-based counterparts, so
 +        are overridden by values found in the configuration files.  In
 +        other words, subversion looks for configuration information in
 +        the following locations on a Windows system; lower-numbered
 +        locations take precedence over higher-numbered locations:</para>

        <orderedlist>
          <listitem>
 @@ -321,7 +322,7 @@
                <para>This specifies the amount of time, in seconds, to
                  wait for a server response.  If you experience
                  problems with a slow network connection causing
 -                Subversion operations to timeout, you should increase
 +                Subversion operations to time out, you should increase
                  the value of this option.  The default value is
                  <literal>0</literal>, which instructs the underlying
                  HTTP library, Neon, to use its default timeout
 @@ -405,7 +406,7 @@
          <para>The <filename>config</filename> file contains the rest
            of the currently available Subversion run-time options,
            those not related to networking.  There are only a few
 -          options in use at this time, but they are again grouped into
 +          options in use as of this writing, but they are again grouped
 into
            sections in expectation of future additions.</para>

          <para>The <literal>auth</literal> section contains settings
 @@ -463,7 +464,8 @@
                  in the editor program (see <xref
                  linkend="svn.advanced.props" />).  This option's default
                  value is empty.  The order of priority for determining
 the
 -                editor command is:</para>
 +                editor command (again, lower-numbered
 +                locations take precedence over higher-numbered locations)
 is:</para>
                <orderedlist>
                  <listitem>
                    <para>Command-line option <literal>--editor-
 cmd</literal></para>
 @@ -499,7 +501,10 @@
                <para>This specifies the absolute path of a differencing
                  program, used when Subversion generates
                  <quote>diff</quote> output (such as when using the
 -                <command>svn diff</command> command).  By default
 +                <command>svn diff</command> command).
 +                <!-- are the other times when subversion consults this
 +                - such as "merge"?  That would be important to know -->
 +                                                       By default
                  Subversion uses an internal differencing
                  library—setting this option will cause it to
                  perform this task using an external program.  See
 @@ -686,6 +691,9 @@
          in which programs present data to the user, as well as the way
          in which they accept user input.</para>

 +      <!-- I'm fairly sure that some Unix-like systems don't, by
 +      default, have a "locale" command installed.  So perhaps we
 +      should say "On most Unix-like systems ..." -->
        <para>On Unix-like systems, you can check the values of the
          locale-related runtime configuration options by running the
          <command>locale</command> command:</para>
 @@ -920,16 +928,16 @@
        <para>Subversion calls external diff programs with parameters
          suitable for the GNU diff utility, and expects only that the
          external program return with a successful error code.  For
 -        most alternative diff program, only the sixth and seventh
 -        arguments, the paths of the files which represent the left and
 -        right sides of the diff, respectively, are of interest.  Note
 +        most alternative diff programs, only the sixth and seventh
 +        arguments—the paths of the files which represent the left
 and
 +        right sides of the diff, respectively—are of interest.
 Note
          that Subversion runs the diff program once per modified file
          covered by the Subversion operation, so if your program runs
          in an asynchronous fashion (or <quote>backgrounded</quote>),
          you might have several instances of it all running
          simultaneously.  Finally, Subversion expects that your program
 -        return an errorcode of 1 if your program detected differences,
 -        or 0 if it did not—any other errorcode is considered a
 +        return an error code of 1 if your program detected differences,
 +        or 0 if it did not—any other error code is considered a
          fatal error.
          <footnote>
            <para>The GNU diff manual page puts it this way: <quote>An
 @@ -1007,8 +1015,8 @@
          depends on the output of your merge program, you wrapper
          script must not exit before that output has been delivered to
          Subversion.  When it finally does exit, it should return an
 -        errorcode of 0 if the merge was successful, or 1 if unresolved
 -        conflicts remain in the output—any other errorcode is
 +        error code of 0 if the merge was successful, or 1 if unresolved
 +        conflicts remain in the output—any other error code is
          considered a fatal error.</para>

        <para><xref linkend="svn.advanced.externaldifftools.diff3.ex-1"/>
 Index: ch08-embedding-svn.xml
 ===================================================================
 --- ch08-embedding-svn.xml      (revision 2737)
 +++ ch08-embedding-svn.xml      (working copy)
 @@ -1,8 +1,8 @@
  <chapter id="svn.developer">
    <title>Embedding Subversion</title>

 -  <para>Subversion has a modular design, written in C and implemented
 -    as a collection of libraries.  Each library has a well-defined
 +  <para>Subversion has a modular design: it's implemented
 +    as a collection of libraries written in C.  Each library has a well-
 defined
      purpose and Application Programming Interface (API), and that
      interface is available not only for Subversion itself to use, but
      for any software that wishes to embed or otherwise
 @@ -31,7 +31,8 @@

      <para>Each of Subversion's core libraries can be said to exist in
        one of three main layers—the Repository Layer, the
 -      Repository Access (RA) Layer, or the Client Layer.  We will
 +      Repository Access (RA) Layer, or the Client Layer (see <xref
 +        linkend="svn.intro.architecture.dia-1" />).  We will
        examine these layers shortly, but first, let's briefly summarize
        Subversion's various libraries.  For the sake of consistency, we
        will refer to the libraries by their extensionless Unix library
 @@ -119,6 +120,8 @@
        </varlistentry>
      </variablelist>

 +    <!-- yeah, but you seem to be using the word "commons"
 +    synonymously  :-)  -->
      <para>The fact that the word <quote>miscellaneous</quote> only
        appears once in the previous list is a good sign.  The
        Subversion development team is serious about making sure that
 @@ -187,7 +190,7 @@
          back-end database systems, perhaps through a mechanism such as
          Open Database Connectivity (ODBC).  In fact, Google did
          something similar to this before launching the Google Code
 -        Project Hosting service, announcing in mid-2006 that members
 +        Project Hosting service: they announced in mid-2006 that members
          of its Open Source team had written a new proprietary
          Subversion filesystem plugin which used their ultra-scalable
          Bigtable database for its storage.</para>
 @@ -272,8 +275,8 @@
        </sidebar>

        <para>Most of the functionality provided by the filesystem
 -        interface is the result of an action that occurs on a
 -        filesystem path.  That is, from outside of the filesystem, the
 +        interface deals with actions that occur on individual
 +        filesystem paths.  That is, from outside of the filesystem, the
          primary mechanism for describing and accessing the individual
          revisions of files and directories comes through the use of
          path strings like <filename>/foo/bar</filename>, just as if
 @@ -296,9 +299,9 @@
          <graphic fileref="images/ch08dia1.png"/>
        </figure>

 -      <para>The different here is that the Subversion filesystem has a
 +      <para>The difference here is that the Subversion filesystem has a
          nifty third dimension that most filesystems do not
 -        have—Time!
 +        have—time!
          <footnote>
            <para>We understand that this may come as a shock to sci-fi
              fans who have long been under the impression that Time was
 @@ -354,7 +357,7 @@
          other important utilities to Subversion.  These include the
          abilities to:</para>

 -      <orderedlist>
 +      <itemizedlist>
          <listitem>
            <para>create, open, destroy, and perform recovery steps on a
              Subversion repository and the filesystem included in that
 @@ -378,7 +381,7 @@
            <para>parse that dump format, loading the dumped revisions
              into a different Subversion repository.</para>
          </listitem>
 -      </orderedlist>
 +      </itemizedlist>

        <para>As Subversion continues to evolve, the repository library
          will grow with the filesystem library to offer increased
 @@ -398,12 +401,18 @@
          (which currently includes libsvn_ra_dav, libsvn_ra_local,
          libsvn_ra_serf, and libsvn_ra_svn), and any additional
          libraries needed by one or more of those RA modules, such as
 +        <!-- I simply cannot parse this clause -->
          the mod_dav_svn Apache module with which libsvn_ra_dav
          communicates or libsvn_ra_svn's server,
          <command>svnserve</command>.</para>

        <para>Since Subversion uses URLs to identify its repository
          resources, the protocol portion of the URL schema (usually
 +        <!-- why omit svn+ssh here?  I'd suggest we either list
 +        _every_ schema we're aware of, or else, list far fewer, so
 +        that the list is clearly intended to be incomplete.  But this
 +        _almost-complete_ list immediately makes me wonder why svn+ssh
 +        is missing. -->
          <literal>file://</literal>, <literal>http://</literal>,
          <literal>https://</literal>, or <literal>svn://</literal>) is
 used
          to determine which RA module will handle the communications.
 @@ -521,7 +530,7 @@
          <para>Why should your GUI program bind directly with a
            libsvn_client instead of acting as a wrapper around a
            command-line program?  Besides simply being more efficient,
 -          this can address potential correctness issues as well.  A
 +          it can be more correct as well.  A
            command-line program (like the one supplied with Subversion)
            that binds to the client library needs to effectively
            translate feedback and requested data bits from C types to
 @@ -529,6 +538,10 @@
            translation can be lossy.  That is, the program may not
            display all of the information harvested from the API, or
            may combine bits of information for compact
 representation.</para>
 +        <!-- I swear I read somewhere that the output of the
 +          command-line programs was carefully designed to be both
 +          human- and machine-readable, which implies that it is also
 +          complete and correct.  Is this no longer the case? -->

          <para>If you wrap such a command-line program with yet another
            program, the second program has access only to
 @@ -594,13 +607,12 @@
      <para>The Subversion working copy administration area's layout and
        contents are considered implementation details not really
        intended for human consumption.  Developers are encouraged to
 -      use Subversion's public APIs or provided tools to access and
 -      manipulate the working copy data, as opposed to directly reading
 -      or modifying the files of which the working copy administrative
 -      area is comprised.  The file formats employed by the working
 +      use Subversion's public APIs, or the tools that Subversion
 provides, to access and
 +      manipulate the working copy data, instead of directly reading
 +      or modifying those files.  The file formats employed by the working
        copy library for its administrative data do change from time to
        time—a fact that the public APIs do a great job of
 -      successfully hiding from the average user.  In this section, we
 +      hiding from the average user.  In this section, we
        expose some of these implementation details sheerly to appease
        your overwhelming curiousity.</para>

 @@ -610,9 +622,9 @@

        <para>Perhaps the single most important file in the
          <filename>.svn</filename> directory is the
 -        <filename>entries</filename> file.  The entries file is a
 -        single file which contains the bulk of the administrative
 -        information about a versioned item in a working copy
 +        <filename>entries</filename> file.  It
 +        contains the bulk of the administrative
 +        information about the versioned items in a working copy
          directory.  It is this one file which tracks the repository
          URLs, pristine revision, file checksums, pristine text and
          property timestamps, scheduling and conflict state
 @@ -640,6 +652,11 @@
          makes upgrading from one working copy format to another a
          breeze—it reads the old formats, and writes the
          new.</para>
 +      <!-- that mention of upgrading is a bit tantalizing; there's a
 +        lot more to be said (such as: version 1.4 clients silently
 +        upgrade wcs made by older clients).  Is it worth mentioning
 +        anything more?  If not, is it then even worth keeping this
 +        tantalizing sentence? -->

      </sect2>

 @@ -647,13 +664,14 @@
      <sect2 id="svn.developer.insidewc.base-and-props">
        <title>Pristine Copies and Property Files</title>

 +      <!-- actually, I don't believe we _did_ mention this before. -->
        <para>As mentioned before, the <filename>.svn</filename>
          directory also holds the pristine <quote>text-base</quote>
          versions of files.  Those can be found in
          <filename>.svn/text-base</filename>.  The benefits of these
          pristine copies are multiple—network-free checks for
          local modifications and difference reporting, network-free
 -        reversion of modified or missing files, smaller transmission
 +        reversion of modified or missing files, more efficient
 transmission
          of changes to the server—but comes at the cost of having
          each versioned file stored at least twice on disk.  These
          days, this seems to be a negligible penalty for most files.
 @@ -677,6 +695,9 @@
          property files (<quote>working</quote> and <quote>base</quote>
          versions) uses a simple <quote>hash-on-disk</quote> file
          format for storing the property names and values.</para>
 +      <!-- is this "hash-on-disk" format somehow different from the
 +        format of the text-base file?  If so, how?  If not, or if the
 +        difference isn't worth explaining, why mention it? -->

      </sect2>

 @@ -691,8 +712,12 @@
      <para>Developing applications against the Subversion library APIs
        is fairly straightforward.  All of the public header files live
        in the <filename>subversion/include</filename> directory of the
 -      source tree.  These headers are copied into your system
 -      locations when you build and install Subversion itself from
 +      source tree.
 +      <!-- that last sentence, about header files, would probably
 +      confuse me if I weren't a C programmer.  Ought we assume that
 +      the reader is in fact a C programmer? -->
 +                    These headers are copied into your system
 +      locations (for example, <filename>/usr/local/include</filename>)
 when you build and install Subversion itself from
        source.  These headers represent the entirety of the functions
        and types meant to be accessible by users of the Subversion
        libraries.  The Subversion developer community is meticulous
 @@ -702,7 +727,7 @@

      <para>When examining the public header files, the first thing you
        might notice is that Subversion's datatypes and functions are
 -      namespace protected.  Every public Subversion symbol name begins
 +      namespace protected.  That is, every public Subversion symbol name
 begins
        with <literal>svn_</literal>, followed by a short code for the
        library in which the symbol is defined (such as
        <literal>wc</literal>, <literal>client</literal>,
 @@ -748,10 +773,13 @@
          differ mildly—or wildly—from OS to OS.  While the
          Apache HTTP Server was obviously the first user of the APR
          library, the Subversion developers immediately recognized the
 -        value of using APR as well.  This means that there are
 -        practically no OS-specific code portions in Subversion itself.
 +        value of using APR as well.  This means that there is
 +        practically no OS-specific code in Subversion itself.
          Also, it means that the Subversion client compiles and runs
 -        anywhere that the server does.  Currently this list includes
 +        anywhere that the server does.
 +        <!-- didn't you mean to say "... anywhere that Apache itself
 does"?
 +        That's equally true, and more impressive. -->
 +                                        Currently this list includes
          all flavors of Unix, Win32, BeOS, OS/2, and Mac OS X.</para>

        <para>In addition to providing consistent implementations of
 @@ -762,18 +790,18 @@
          </footnote>
          APR gives Subversion immediate access to many custom
          datatypes, such as dynamic arrays and hash tables.  Subversion
 -        uses these types extensively throughout the codebase.  But
 +        uses these types extensively.  But
          perhaps the most pervasive APR datatype, found in nearly every
          Subversion API prototype, is the
          <structname>apr_pool_t</structname>—the APR memory pool.
          Subversion uses pools internally for all its memory allocation
          needs (unless an external library requires a different memory
 -        management schema for data passed through its API),
 +        management schema for data passed through its API), <!--
 "scheme", maybe? -->
          <footnote>
            <para>Neon and Berkeley DB are examples of such
 libraries.</para>
          </footnote>
          and while a person coding against the Subversion APIs is
 -        not required to do the same, they are required to provide
 +        not required to do the same, they <emphasis>are</emphasis>
 required to provide
          pools to the API functions that need them.  This means that
          users of the Subversion API must also link against APR, must
          call <function>apr_initialize()</function> to initialize the
 @@ -792,7 +820,7 @@
            keeping track of those allocations, freeing the memory when
            you no longer need it—these tasks can be quite
            complex.  And of course, failure to do those things properly
 -          can result in a program that crashes itself, or worse,
 +          can result in a program that aborts, or worse,
            crashes the computer.</para>

          <para>Higher-level languages, on the other hand, take the job of
 @@ -802,7 +830,7 @@
                doing extremely tight program optimization.</para>
            </footnote>
            Languages like Java and Python use <firstterm>garbage
 -          collection</firstterm> principles, allocating memory for
 +          collection</firstterm>, allocating memory for
            objects when needed, and automatically freeing that memory
            when the object is no longer in use.</para>

 @@ -814,9 +842,9 @@
            friends to allocate enough memory for a given object, you
            ask APR to allocate the memory from a memory pool.  When
            you're finished using the objects you've created in the
 -          pool, you destroy the pool, effectively de-allocating the
 -          memory consumed by the objects you allocated from it.
 -          Rather than keeping track of individual objects which need
 +          pool, you destroy the entire pool, effectively de-allocating
 the
 +          memory consumed by <emphasis>all</emphasis> the objects you
 allocated from it.
 +          Thus, rather than keeping track of individual objects which
 need
            to be de-allocated, your program simply considers the
            general lifetimes of those objects, and allocates the
            objects in a pool whose lifetime (the time between the
 @@ -866,9 +894,10 @@
          conjunction with something other than a C program—say a
          Python or Perl script—Subversion has some support for this
          via the Simplified Wrapper and Interface Generator (SWIG).  The
 +        <!-- perhaps link to http://www.swig.org/ here? -->
          SWIG bindings for Subversion are located in
 -        <filename>subversion/bindings/swig</filename> and whilst still
 -        maturing, they are in a usable state.  These bindings allow you
 +        <filename>subversion/bindings/swig</filename>.  They are still
 +        maturing, but they are usable.  These bindings allow you
          to call Subversion API functions indirectly, using wrappers that
          translate the datatypes native to your scripting language into
          the datatypes needed by Subversion's C libraries.</para>
 @@ -876,16 +905,33 @@
        <para>There is an obvious benefit to accessing the Subversion
          APIs via a language binding—simplicity.  Generally
          speaking, languages such as Python and Perl are much more
 -        flexible and easy to use than C or C++.  The sort of
 +        flexible and easy to use than C or C++.
 +
 +        <!-- input validation is a strange example to demonstrate why
 +        Python or Perl is better than C or Cplusplus.  Maybe we should
 punt,
 +        and assume that our reader either already knows the benefits
 +        of such languages, or else wouldn't understand them even if we
 +        were to explain them.  -->
 +                                                        The sort of
          high-level datatypes and context-driven type checking provided
          by these languages are often better at handling information
          that comes from users.  As you know, humans are proficient at
          botching up input to a program, and scripting languages tend
 -        to handle that misinformation more gracefully.  Of course,
 +        to handle that misinformation more gracefully.
 +
 +        <!-- I'm not even sure that previous statement is true - are
 +        you saying, roughly, Python and Perl have better error
 +        handling than C or C++? -->
 +
 +                                                        Of course,
          often that flexibility comes at the cost of performance.  That
          is why using a tightly-optimized, C-based interface and
          library suite, combined with a powerful, flexible binding
          language, is so appealing.</para>
 +        <!-- I'm leaning towards losing this entire paragraph, on the
 +        principle that if our reader doesn't know why Perl or Python
 +        might be better than C or C++, it would take too long to
 +        explain. -->

        <para>Unfortunately, Subversion's language bindings tend to lack
          the level of developer attention given to the core Subversion
 @@ -900,6 +946,14 @@
          translating between languages.  For more information on SWIG
          itself, see the project's website at <ulink
          url="http://www.swig.org/"/>.</para>
 +      <!-- yikes.  Now you've told me that the bindings are not
 +        trustworthy, or something.  I'm left mystified: are they worth
 +        using, or not?  Perhaps we should give our reader some way of
 +        verifying for themselves how well a particular language
 +        binding works - perhaps point them to the unit tests, and say
 +        "these tests are guaranteed to pass in all released versions
 +        of Subversion; if they seem to cover the functionality that
 +        you need, then you'll have no trouble using that language" -->

      </sect2>

 @@ -924,6 +978,9 @@
        <example id="svn.developer.layerlib.repos.ex-1">
          <title>Using the Repository Layer</title>

 +        <!-- the word "consumed" in the comment is new to me.  Does
 +        "errors must be consumed" simply mean "you gotta call
 +        svn_error_clear"?  If so, please say so. -->
          <programlisting>
  /* Convert a Subversion error into a simple boolean error code.
   *
 @@ -1025,6 +1082,8 @@
    INT_ERR(err);
  }
  </programlisting>
 +        <!-- now I remember why I no longer program in C if I can
 +        avoid it :-| -->
        </example>

        <para>Note that in <xref
 @@ -1037,7 +1096,7 @@
          time you commit a transaction (like, for example, sending an
          email that describes all the changes made in that transaction
          to your developer mailing list), you need to use the
 -        libsvn_repos-wrapped version of that function was adds the
 +        libsvn_repos-wrapped version of that function, because it adds
 the
          hook triggering functionality—in this case,
          <function>svn_repos_fs_commit_txn()</function>.  (For more
          information regarding Subversion's repository hooks, see <xref
 }}}

-- 
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/64>
SvnBook <http://svnbook.red-bean.com/>


More information about the svnbook-dev mailing list