[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