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

cmpilato noreply at red-bean.com
Wed Aug 15 00:01:14 CDT 2007


Author: cmpilato
Date: Wed Aug 15 00:01:11 2007
New Revision: 2854

Log:
Tweaks from Eric Hanchrow, plus some new stuff on language bindings.

Modified:
   trunk/src/en/book/ch07-customizing-svn.xml
   trunk/src/en/book/ch08-embedding-svn.xml

Modified: trunk/src/en/book/ch07-customizing-svn.xml
==============================================================================
--- trunk/src/en/book/ch07-customizing-svn.xml	(original)
+++ trunk/src/en/book/ch07-customizing-svn.xml	Wed Aug 15 00:01:11 2007
@@ -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>
@@ -332,7 +333,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
@@ -416,7 +417,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
@@ -474,7 +475,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 (where lower-numbered locations take 
+                precedence over higher-numbered locations) is:</para>
               <orderedlist>
                 <listitem>
                   <para>Command-line option <literal>--editor-cmd</literal></para>
@@ -697,7 +699,7 @@
         in which programs present data to the user, as well as the way
         in which they accept user input.</para>
 
-      <para>On Unix-like systems, you can check the values of the
+      <para>On most Unix-like systems, you can check the values of the
         locale-related runtime configuration options by running the
         <command>locale</command> command:</para>
 
@@ -931,16 +933,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
@@ -1018,8 +1020,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"/> 

Modified: trunk/src/en/book/ch08-embedding-svn.xml
==============================================================================
--- trunk/src/en/book/ch08-embedding-svn.xml	(original)
+++ trunk/src/en/book/ch08-embedding-svn.xml	Wed Aug 15 00:01:11 2007
@@ -1,11 +1,11 @@
 <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
-    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
+  <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
     programmatically control Subversion.  Additionally, Subversion's
     API is available not only to other C programs, but also to
     programs written in higher-level languages such as Python, Perl,
@@ -31,8 +31,9 @@
 
     <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
-      examine these layers shortly, but first, let's briefly summarize
+      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
       names (libsvn_fs, libsvn_wc, mod_dav_svn, etc.).</para>
@@ -187,7 +188,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 +273,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,7 +297,7 @@
         <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!
         <footnote>
@@ -354,7 +355,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 +379,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
@@ -397,22 +398,22 @@
         libsvn_ra module loader library, the RA modules themselves
         (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
-        the mod_dav_svn Apache module with which libsvn_ra_dav
-        communicates or libsvn_ra_svn's server,
-        <command>svnserve</command>.</para>
+        libraries needed by one or more of those RA modules (such as
+        the mod_dav_svn Apache module 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
         <literal>file://</literal>, <literal>http://</literal>,
-        <literal>https://</literal>, or <literal>svn://</literal>) is used
-        to determine which RA module will handle the communications.
-        Each module registers a list of the protocols it knows how to
-        <quote>speak</quote> so that the RA loader can, at runtime,
-        determine which module to use for the task at hand.  You can
-        determine which RA modules are available to the Subversion
-        command-line client, and what protocols they claim to support,
-        by running <command>svn --version</command>:</para>
+        <literal>https://</literal>, <literal>svn://</literal>, or
+        <literal>svn+ssh://</literal>) is used to determine which RA
+        module will handle the communications.  Each module registers
+        a list of the protocols it knows how to <quote>speak</quote>
+        so that the RA loader can, at runtime, determine which module
+        to use for the task at hand.  You can determine which RA
+        modules are available to the Subversion command-line client,
+        and what protocols they claim to support, by running
+        <command>svn --version</command>:</para>
      
       <screen>
 $ svn --version
@@ -521,7 +522,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
@@ -594,13 +595,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 curiosity.</para>
 
@@ -610,9 +610,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
@@ -636,10 +636,13 @@
         (and Subversion's behavior in light of them), the need for
         easy developer debugging has diminished as Subversion has
         matured, and has been replaced by the user's need for snappier
-        performance.  Of course, Subversion's working copy library
-        makes upgrading from one working copy format to another a
-        breeze—it reads the old formats, and writes the
-        new.</para>
+        performance.  Be aware that Subversion's working copy library
+        automatically upgrades working copies from one format to
+        another—it reads the old formats, and writes the
+        new—which saves you the hassle of checking out a new
+        working copy, but can also complicate situations where
+        different versions of Subversion might be trying to use the
+        same working copy.</para>
 
     </sect2>
 
@@ -653,7 +656,7 @@
         <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.
@@ -673,10 +676,7 @@
         <filename>.svn/prop-base</filename> respectively.  Since
         directories can have properties, too, there are also
         <filename>.svn/dir-props</filename> and
-        <filename>.svn/dir-prop-base</filename> files.  Each of these
-        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>
+        <filename>.svn/dir-prop-base</filename> files.</para>
 
     </sect2>
 
@@ -689,20 +689,21 @@
     <title>Using the APIs</title>
 
     <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.  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
-      about ensuring that the public API is
-      well-documented—refer directly to the header files for
-      that documentation.</para>
+      is fairly straightforward.  Subversion is primarily a set of C
+      libraries, with header (.h) files that live in the
+      <filename>subversion/include</filename> directory of the source
+      tree.  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 about ensuring that the public
+      API is well-documented—refer directly to the header files
+      for that documentation.</para>
 
     <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>,
@@ -739,20 +740,20 @@
 
       <para>Along with Subversion's own datatypes, you will see many
         references to datatypes that begin with
-        <literal>apr_</literal>—symbols from the Apache
-        Portable Runtime (APR) library.  APR is Apache's portability
-        library, originally carved out of its server code as an
-        attempt to separate the OS-specific bits from the
-        OS-independent portions of the code.  The result was a library
-        that provides a generic API for performing operations that
-        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.
-        Also, it means that the Subversion client compiles and runs
-        anywhere that the server does.  Currently this list includes
-        all flavors of Unix, Win32, BeOS, OS/2, and Mac OS X.</para>
+        <literal>apr_</literal>—symbols from the Apache Portable
+        Runtime (APR) library.  APR is Apache's portability library,
+        originally carved out of its server code as an attempt to
+        separate the OS-specific bits from the OS-independent portions
+        of the code.  The result was a library that provides a generic
+        API for performing operations that 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 is practically no OS-specific
+        code in Subversion itself.  Also, it means that the Subversion
+        client compiles and runs anywhere that Apache HTTP Server
+        itself does.  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
         system calls that differ across operating systems,
@@ -762,18 +763,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 mechanism for data passed through its API),
         <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
@@ -802,7 +803,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 +815,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
@@ -867,32 +868,16 @@
         Python or Perl script—Subversion has some support for this
         via the Simplified Wrapper and Interface Generator (SWIG).  The
         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>
 
-      <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
-        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,
-        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>
-
-      <para>Unfortunately, Subversion's language bindings tend to lack
-        the level of developer attention given to the core Subversion
-        modules.  However, there have been significant efforts towards
-        creating functional bindings for Python, Perl, and Ruby.  To
-        some extent, the work done preparing the SWIG interface files
-        for these languages is reusable in efforts to generate
+      <para>Significant efforts have been made towards creating
+        functional SWIG-generated bindings for Python, Perl, and Ruby.
+        To some extent, the work done preparing the SWIG interface
+        files for these languages is reusable in efforts to generate
         bindings for other languages supported by SWIG (which include
         versions of C#, Guile, Java, MzScheme, OCaml, PHP, and Tcl,
         among others).  However, some extra programming is required to
@@ -901,6 +886,43 @@
         itself, see the project's website at <ulink
         url="http://www.swig.org/"/>.</para>
 
+      <para>Subversion also has language bindings for Java.  The
+        JavaJL bindings (located in
+        <filename>subversion/bindings/java</filename> in the
+        Subversion source tree) aren't SWIG-based, but are instead a
+        mixture of javah and hand-coded JNI.  JavaHL most covers
+        Subversion client-side APIs, and is specifically targeted at
+        implementors of Java-based Subversion clients and IDE
+        integrations.</para>
+
+      <para>Subversion's language bindings tend to lack the level of
+        developer attention given to the core Subversion modules, but
+        can generally be trusted as production-ready.  A number of
+        scripts and applications, alternative Subversion GUI clients
+        and other third-party tools are successfully using
+        Subversion's language bindings today to accomplish their
+        Subversion integrations.</para>
+
+      <para>It's worth noting here that there are other options for
+        interfacing with Subversion using other languages:  alternative
+        bindings for Subversion which aren't provided by the
+        Subversion development community at all.  You can find links
+        to these alternative bindings on the Subversion project's
+        links page (at <ulink
+        url="http://subversion.tigris.org/links.html" />), but there
+        are a couple of popular ones we feel are especially
+        noteworthy.  First, Barry Scott's PySVN bindings (<ulink
+        url="http://pysvn.tigris.org/" />) are a popular option for
+        binding with Python.  PySVN boasts of a more Pythonic
+        interface than the more C-like APIs provided by Subversion's
+        own Python bindings.  For folks looking for a pure Java
+        implementation of Subversion, check out SVNKit (<ulink
+        url="http://svnkit.com/" />), which is Subversion re-written
+        from the ground up in Java.  You should exercise caution here,
+        though—because SVNKit doesn't use the core Subversion
+        libraries, it's behavior is not guaranteed to match that of
+        Subversion itself.</para>
+
     </sect2>
 
     <!-- =============================================================== -->
@@ -927,8 +949,9 @@
         <programlisting>
 /* Convert a Subversion error into a simple boolean error code.
  *
- * NOTE:  Subversion errors must be consumed because they are allocated
- *        from the global pool, else memory leaking occurs.
+ * NOTE:  Subversion errors must be cleared (using svn_error_clear())
+ *        because they are allocated from the global pool, else memory
+ *        leaking occurs.
  */
 #define INT_ERR(expr)                           \
   do {                                          \
@@ -1037,7 +1060,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, which 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




More information about the svnbook-dev mailing list