[svnbook] r4087 committed - Read-thru edits....

svnbook at googlecode.com svnbook at googlecode.com
Fri Sep 9 10:02:04 CDT 2011

Revision: 4087
Author:   cmpilato at gmail.com
Date:     Fri Sep  9 08:01:33 2011
Log:      Read-thru edits.

* en/book/ch07-customizing-svn.xml
   Add docs for the new 'diff-extensions' runtime configuration option.

* en/book/ch08-embedding-svn.xml
   Fix reference to "libsvn_ra_dav".  Remove the "Inside the Working
   Copy Administration Area" section (and a crossreference to it).
   Update Python example to demonstrate callbacks/batons, and add text
   around this.  Add "Functions and Batons" section.



--- /trunk/en/book/ch07-customizing-svn.xml	Tue Sep  6 14:02:35 2011
+++ /trunk/en/book/ch07-customizing-svn.xml	Fri Sep  9 08:01:33 2011
@@ -219,6 +219,7 @@

@@ -643,6 +644,21 @@
                  <xref linkend="svn.advanced.externaldifftools"/> for
                  more details on using such programs.</para>
+          </varlistentry>
+          <varlistentry>
+            <term><literal>diff-extensions</literal></term>
+            <listitem>
+              <para>Like the <option>--extensions</option>
+                (<option>-x</option>) command-line option, this
+                specifies additional options passed to the file
+                content differencing engine.  The set of meaningful
+                extension options differs depending on whether the
+                client is using Subversion's internal differencing
+                engine or an external mechanism.  See the output
+                of <userinput>svn help diff</userinput> for details.
+                The default value for this option
+                is <literal>-u</literal>.</para>
+            </listitem>
--- /trunk/en/book/ch08-embedding-svn.xml	Tue Aug  9 07:57:26 2011
+++ /trunk/en/book/ch08-embedding-svn.xml	Fri Sep  9 08:01:33 2011
@@ -31,12 +31,13 @@

      <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 (see <xref
-      linkend="svn.intro.architecture.dia-1" /> in the Preface).  We will  
-      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 (<filename>libsvn_fs</filename>,  
+      Repository Access (RA) layer, or the Client layer (see
+      <xref linkend="svn.intro.architecture.dia-1" /> in the Preface).
+      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
+      (<filename>libsvn_fs</filename>, <filename>libsvn_wc</filename>,
        <filename>mod_dav_svn</filename>, etc.).</para>

@@ -433,12 +434,13 @@
  $ svn --version
-svn, version 1.6.0
-   compiled Mar 21 2009, 17:27:36
-Copyright (C) 2000-2009 CollabNet.
+svn, version 1.7.0
+   compiled Nov 15 2011, 10:10:24
+Copyright (C) 2011 The Apache Software Foundation.
+This software consists of contributions made by many people; see the NOTICE
+file for more information.
  Subversion is open source software, see http://subversion.apache.org/
-This product includes software developed by CollabNet  

  The following repository access (RA) modules are available:

@@ -462,13 +464,13 @@
          functionality necessary for sending and receiving versioned
          data to and from the repository.  And each of the available RA
          plug-ins is able to perform that task using a specific
-        protocol—<filename>libsvn_ra_dav</filename> speaks
-        HTTP/WebDAV (optionally using SSL encryption) with an Apache
-        HTTP Server that is running the
-        <filename>mod_dav_svn</filename> Subversion server module;
-        <filename>libsvn_ra_svn</filename> speaks a custom network
-        protocol with the <command>svnserve</command> program; and so
-        on.</para>
+        protocol—<filename>libsvn_ra_neon</filename>
+        and <filename>libsvn_ra_serf</filename> speak HTTP/WebDAV
+        (optionally using SSL encryption) with an Apache HTTP Server
+        that is running the <filename>mod_dav_svn</filename>
+        Subversion server module; <filename>libsvn_ra_svn</filename>
+        speaks a custom network protocol with the
+        <command>svnserve</command> program; and so on.</para>

        <para>For those who wish to access a Subversion repository
          using still another protocol, that is precisely why the
@@ -499,18 +501,15 @@
        <para>Subversion's working copy library,
          <filename>libsvn_wc</filename>, is directly responsible for
          managing the data in the working copies.  To accomplish this,
-        the library stores administrative information about each
-        working copy directory within a special subdirectory.  This
+        the library stores administrative information about the
+        working copy within a special subdirectory.  This
          subdirectory, named <filename>.svn</filename>, is present in
-        each working copy directory and contains various other files
+        each working copy and contains various other files
          and directories that record state and provide a private
          workspace for administrative action.  For those familiar with
          CVS, this <filename>.svn</filename> subdirectory is similar in
          purpose to the <filename>CVS</filename> administrative
-        directories found in CVS working copies.  For more information
-        about the <filename>.svn</filename> administrative area, see
-        <xref linkend="svn.developer.insidewc"/> later in this
-        chapter.</para>
+        directories found in CVS working copies.</para>

        <para>The Subversion client library,
          <filename>libsvn_client</filename>, has the broadest
@@ -587,128 +586,6 @@

-  <!-- =================================================================  
-  <!-- =================================================================  
-  <!-- =================================================================  
-  <sect1 id="svn.developer.insidewc">
-    <title>Inside the Working Copy Administration Area</title>
-    <para>As we mentioned earlier, each directory of a Subversion
-      working copy contains a special subdirectory called
-      <filename>.svn</filename> that houses administrative data about
-      that working copy directory.  Subversion uses the information in
-      <filename>.svn</filename> to keep track of things such as:</para>
-    <itemizedlist>
-      <listitem>
-        <para>Which repository location(s) are represented by the
-          files and subdirectories in the working copy
-          directory</para>
-      </listitem>
-      <listitem>
-        <para>What revision of each of those files and directories is
-          currently present in the working copy</para>
-      </listitem>
-      <listitem>
-        <para>Any user-defined properties that might be attached
-          to those files and directories</para>
-      </listitem>
-      <listitem>
-        <para>Pristine (unedited) copies of the working copy
-          files</para>
-      </listitem>
-    </itemizedlist>
-    <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 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 hiding from the average
-      user.  In this section, we expose some of these implementation
-      details sheerly to appease your overwhelming curiosity.</para>
-    <!-- ===============================================================  
-    <sect2 id="svn.developer.insidewc.entries">
-      <title>The Entries File</title>
-      <para>Perhaps the single most important file in the
-        <filename>.svn</filename> directory is the
-        <filename>entries</filename> file.  It
-        contains the bulk of the administrative
-        information about the versioned items in a working copy
-        directory.  This one file tracks the repository
-        URLs, pristine revision, file checksums, pristine text and
-        property timestamps, scheduling and conflict state
-        information, last-known commit information (author, revision,
-        timestamp), local copy history—practically everything
-        that a Subversion client is interested in knowing about a
-        versioned (or to-be-versioned) resource!</para>
-      <para>Folks familiar with CVS's administrative directories will
-        have recognized at this point that Subversion's
-        <filename>.svn/entries</filename> file serves the purposes of,
-        among other things, CVS's <filename>CVS/Entries</filename>,
-        <filename>CVS/Root</filename>, and
-        <filename>CVS/Repository</filename> files combined.</para>
-      <para>The format of the <filename>.svn/entries</filename> file
-        has changed over time.  Originally an XML file, it now uses a
-        custom—though still human-readable—file format.
-        While XML was a great choice for early developers of
-        Subversion who were frequently debugging the file's contents
-        (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.  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>
-    <!-- ===============================================================  
-    <sect2 id="svn.developer.insidewc.base-and-props">
-      <title>Pristine Copies and Property Files</title>
-      <para>As mentioned before, the <filename>.svn</filename>
-        directory also holds the pristine <quote>text-base</quote>
-        versions of files.  You can find those 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, more efficient
-        transmission of changes to the server—but they come 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.  However, the situation gets uglier as the size of
-        your versioned files grows.  Some attention is being given to
-        making the presence of the <quote>text-base</quote> an option.
-        Ironically, though, it is as your versioned files' sizes get
-        larger that the existence of the <quote>text-base</quote>
-        becomes more crucial—who wants to transmit a huge file
-        across a network just because she wants to commit a tiny
-        change to it?</para>
-      <para>Similar in purpose to the <quote>text-base</quote> files
-        are the property files and their pristine
-        <quote>prop-base</quote> copies, located in
-        <filename>.svn/props</filename> and
-        <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.</para>
-    </sect2>
-  </sect1>
    <!-- =================================================================  
    <!-- =================================================================  
    <!-- =================================================================  
@@ -846,6 +723,23 @@

+    <!-- ===============================================================  
+    <sect2 id="svn.developer.usingapi.funcsbatons">
+      <title>Functions and Batons</title>
+      <para>To facilite <quote>streamy</quote> (asyncronous) behavior
+        and provide consumers of the Subversion C API with hooks for
+        handling information in customizable ways, many functions in
+        the API accept pairs of parameters: a pointer to a callback
+        function, and a pointer to a blob of memory called
+        a <firstterm>baton</firstterm> that carries context
+        information for that callback function.  Batons are typically
+        C structures with additional information that the callback
+        function needs but which is not given directly to the callback
+        function by the driving API function.</para>
+    </sect2>
      <!-- ===============================================================  
      <sect2 id="svn.developer.usingapi.urlpath">
        <title>URL and Path Requirements</title>
@@ -873,8 +767,8 @@

        <para>Also, Subversion APIs require all URL parameters to be
          properly URI-encoded.  So, instead of passing
-        <uri>file:///home/username/My File.txt</uri> as the URL of a
-        file named <filename>My File.txt</filename>, you need to pass
+        <uri>file:///home/username/My File.txt</uri> as the URL of a
+        file named <filename>My File.txt</filename>, you need to pass
          <uri>file:///home/username/My%20File.txt</uri>.  Again,
          Subversion supplies helper functions that your application can
          use—<function>svn_path_uri_encode()</function> and
@@ -1263,7 +1157,7 @@
      return code_map.get(status, '?')

-def do_status(wc_path, verbose):
+def do_status(wc_path, verbose, prefix):
      # Build a client context baton.
      ctx = svn.client.svn_client_create_context()

@@ -1274,7 +1168,10 @@
          # the status crawl
          text_status = generate_status_code(status.text_status)
          prop_status = generate_status_code(status.prop_status)
-        print '%s%s  %s' % (text_status, prop_status, path)
+        prefix_text = ''
+        if prefix is not None:
+            prefix_text = prefix + " "
+        print '%s%s%s  %s' % (prefix_text, text_status, prop_status, path)

      # Do the status crawl, using _status_callback() as our callback  
      revision = svn.core.svn_opt_revision_t()
@@ -1287,8 +1184,12 @@
      """Print usage message, and exit with ERRORCODE."""
      stream = errorcode and sys.stderr or sys.stdout
      stream.write("""Usage: %s OPTIONS WC-PATH
+  Print working copy status, optionally with a bit of prefix text.
    --help, -h    : Show this usage message
+  --prefix ARG  : Print ARG, followed by a space, before each line of  
    --verbose, -v : Show all statuses, even uninteresting ones
  """ % (os.path.basename(sys.argv[0])))
@@ -1296,13 +1197,17 @@
  if __name__ == '__main__':
      # Parse command-line options.
-        opts, args = getopt.getopt(sys.argv[1:], "hv", ["help", "verbose"])
+        opts, args = getopt.getopt(sys.argv[1:], "hv",
+                                   ["help", "prefix=", "verbose"])
      except getopt.GetoptError:
      verbose = 0
+    prefix = None
      for opt, arg in opts:
          if opt in ("-h", "--help"):
+        if opt in ("--prefix"):
+            prefix = arg
          if opt in ("-v", "--verbose"):
              verbose = 1
      if len(args) != 1:
@@ -1313,7 +1218,7 @@

      # Do the real work.
-        do_status(wc_path, verbose)
+        do_status(wc_path, verbose, prefix)
      except svn.core.SubversionException, e:
          sys.stderr.write("Error (%d): %s\n" % (e.apr_err, e.message))
@@ -1323,13 +1228,34 @@
        <para>As was the case in
          <xref linkend="svn.developer.usingapi.otherlangs.ex-1" />,
          this program is pool-free and uses, for the most part, normal
-        Python datatypes.  Also note that the path passed to this
-        program (like the last one) gets run through
-        <function>svn_path_canonicalize()</function>, because to
-        <emphasis>not</emphasis> do so runs the risk of triggering the
-        underlying Subversion C library's assertions about such
-        things, which translates into rather immediate and
-        unceremonious program abortion.</para>
+        Python datatypes.</para>
+      <warning>
+        <para>Run user-provided paths
+          through <function>svn_path_canonicalize()</function> before
+          passing them to other API functions.  Failure to do so can
+          trigger assertions in the underlying Subversion C library
+          which translate into rather immediate and unceremonious
+          program abortion.</para>
+      </warning>
+      <para>Of particular interest to users of the Python flavor of
+        Subversion's API is the implementation of callback functions.
+        As previously mentioned, Subversion's C API makes liberal use
+        of the callback function/baton paradigm.  API functions which
+        in C accept a function and baton pair only accept a callback
+        function parameter in Python.  How, then, does the caller pass
+        arbitrary context information to the callback function?  In
+        Python, this is done by taking advantage of Python's scoping
+        rules and default argument values.  You can see this in action
+        in <xref linkend="svn.developer.usingapi.otherlangs.ex-2" />.
+        The <function>svn_client_status2()</function> function is
+        given a callback function
+        (<function>_status_callback()</function>) but no
+        baton—<function>_status_callback()</function> gets
+        access to the user-provided prefix string because that
+        variable falls into the scope of the function
+        automatically.</para>


More information about the svnbook-dev mailing list