[svnbook] r4090 committed - Merge from ^/trunk/en the relevant (to 1.6) portions of r4081-4089.

svnbook at googlecode.com svnbook at googlecode.com
Fri Sep 9 10:27:32 CDT 2011


Revision: 4090
Author:   cmpilato at gmail.com
Date:     Fri Sep  9 08:27:07 2011
Log:      Merge from ^/trunk/en the relevant (to 1.6) portions of  
r4081-4089.
http://code.google.com/p/svnbook/source/detail?r=4090

Modified:
  /branches/1.6/en
  /branches/1.6/en/book/ch05-repository-admin.xml
  /branches/1.6/en/book/ch06-server-configuration.xml
  /branches/1.6/en/book/ch08-embedding-svn.xml

=======================================
--- /branches/1.6/en/book/ch05-repository-admin.xml	Wed Sep  7 08:34:32 2011
+++ /branches/1.6/en/book/ch05-repository-admin.xml	Fri Sep  9 08:27:07 2011
@@ -962,7 +962,7 @@
          problems that could prevent the hook from performing the tasks
          it is designed to perform.</para>

-      <para>There are serveral hooks implemented by the Subversion
+      <para>There are several hooks implemented by the Subversion
          repository, and you can get details about each of them in
          <xref linkend="svn.ref.reposhooks" />.  As a repository
          administrator, you'll need to decide which hooks you wish
=======================================
--- /branches/1.6/en/book/ch06-server-configuration.xml	Tue Aug 30 08:57:18  
2011
+++ /branches/1.6/en/book/ch06-server-configuration.xml	Fri Sep  9 08:27:07  
2011
@@ -551,7 +551,8 @@
          <informalexample>
            <screen>
  $ svnserve -i
-( success ( 1 2 ( ANONYMOUS ) ( edit-pipeline ) ) )
+( success ( 2 2 ( ) ( edit-pipeline svndiff1 absent-entries  
commit-revprops d\
+epth log-revprops atomic-revprops partial-replay ) ) )
  </screen>
          </informalexample>

@@ -1585,17 +1586,17 @@
      <para>The Apache HTTP Server is a <quote>heavy-duty</quote>
        network server that Subversion can leverage.  Via a custom
        module, <command>httpd</command> makes Subversion repositories
-      available to clients via the WebDAV/DeltaV protocol, which is an
-      extension to HTTP 1.1 (see <ulink url="http://www.webdav.org/"/>
-      for more information).  This protocol takes the ubiquitous HTTP
-      protocol that is the core of the World Wide Web, and adds
-      writing—specifically, versioned
+      available to clients via the WebDAV/DeltaV<footnote><para>See
+      <ulink url="http://www.webdav.org/"/>.</para></footnote>
+      protocol, which is an extension to HTTP 1.1.  This protocol
+      takes the ubiquitous HTTP protocol that is the core of the World
+      Wide Web, and adds writing—specifically, versioned
        writing—capabilities.  The result is a standardized,
        robust system that is conveniently packaged as part of the
        Apache 2.0 software, supported by numerous operating systems and
        third-party products, and doesn't require network administrators
        to open up yet another custom port.<footnote><para>They really
-      hate doing that.</para></footnote>  While an Apache-Subversion
+      hate doing that.</para></footnote> While an Apache-Subversion
        server has more features than <command>svnserve</command>, it's
        also a bit more difficult to set up.  With flexibility often
        comes more complexity.</para>
@@ -1910,12 +1911,13 @@
        <sect3 id="svn.serverconfig.httpd.authn.basic">
          <title>Basic authentication</title>

-        <para>The easiest way to authenticate a client is via the
-          HTTP Basic authentication mechanism, which simply uses a
-          username and password to verify a user's identity.  Apache
-          provides the <command>htpasswd</command> utility
-          (<ulink  
url="http://httpd.apache.org/docs/current/programs/htpasswd.html"/>)
-          for managing files containing usernames and passwords.</para>
+        <para>The easiest way to authenticate a client is via the HTTP
+          Basic authentication mechanism, which simply uses a username
+          and password to verify a user's identity.  Apache provides
+          the <command>htpasswd</command> utility<footnote><para>See
+          <ulink  
url="http://httpd.apache.org/docs/current/programs/htpasswd.html"
+          />.</para></footnote> for managing files containing
+          usernames and passwords.</para>

          <warning>
            <para>Basic authentication is <emphasis>extremely</emphasis>
@@ -2054,11 +2056,13 @@
          <para>Notice that <literal>AuthType</literal> is now set to
            <literal>Digest</literal>, and we specify a different path
            for <literal>AuthUserFile</literal>.  Digest authentication
-          uses a different file format than Basic authentication;
-          it is created using Apache's <command>htdigest</command>
-          utility (<ulink  
url="http://httpd.apache.org/docs/current/programs/htdigest.html"/>)
-          rather than <command>htpasswd</command>.
-          Digest authentication also has the additional concept of a
+          uses a different file format than Basic authentication; it
+          is created using Apache's <command>htdigest</command>
+          utility<footnote><para>See
+          <ulink  
url="http://httpd.apache.org/docs/current/programs/htdigest.html"
+          />.</para></footnote> rather
+          than <command>htpasswd</command>.  Digest authentication
+          also has the additional concept of a
            <quote>realm</quote>, which must match the value of the
            <literal>AuthName</literal> directive.  The password file
            can be created as follows:</para>
@@ -3468,16 +3472,6 @@
        <literal>rw</literal> permission to certain users on specific
        subdirectories within specific repositories.</para>

-    <para>The asterisk variable (<literal>*</literal>) is also worth
-      special mention because it's the
-      <emphasis>only</emphasis> pattern that matches an anonymous
-      user.  If you've configured your server block to allow a mixture
-      of anonymous and authenticated access, all users start out
-      accessing anonymously.  The server looks for a
-      <literal>*</literal> value defined for the path being accessed;
-      if it can't find one, it demands real authentication from
-      the client.</para>
-
      <para>The access file also allows you to define whole groups of
        users, much like the Unix <filename>/etc/group</filename>
        file:</para>
=======================================
--- /branches/1.6/en/book/ch08-embedding-svn.xml	Tue Aug  9 07:57:26 2011
+++ /branches/1.6/en/book/ch08-embedding-svn.xml	Fri Sep  9 08:27:07 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  
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>,
+      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>

      <variablelist>
@@ -462,13 +463,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
@@ -846,6 +847,23 @@
        </sidebar>
      </sect2>

+    <!-- ===============================================================  
-->
+    <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 +891,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 +1281,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 +1292,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  
function.
      revision = svn.core.svn_opt_revision_t()
@@ -1287,8 +1308,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.
+
  Options:
    --help, -h    : Show this usage message
+  --prefix ARG  : Print ARG, followed by a space, before each line of  
output
    --verbose, -v : Show all statuses, even uninteresting ones
  """ % (os.path.basename(sys.argv[0])))
      sys.exit(errorcode)
@@ -1296,13 +1321,17 @@
  if __name__ == '__main__':
      # Parse command-line options.
      try:
-        opts, args = getopt.getopt(sys.argv[1:], "hv", ["help", "verbose"])
+        opts, args = getopt.getopt(sys.argv[1:], "hv",
+                                   ["help", "prefix=", "verbose"])
      except getopt.GetoptError:
          usage_and_exit(1)
      verbose = 0
+    prefix = None
      for opt, arg in opts:
          if opt in ("-h", "--help"):
              usage_and_exit(0)
+        if opt in ("--prefix"):
+            prefix = arg
          if opt in ("-v", "--verbose"):
              verbose = 1
      if len(args) != 1:
@@ -1313,7 +1342,7 @@

      # Do the real work.
      try:
-        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))
          sys.exit(1)
@@ -1323,13 +1352,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>

      </sect2>
    </sect1>




More information about the svnbook-dev mailing list