[svnbook commit] r3221 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Mon Jul 28 22:59:34 CDT 2008
Author: cmpilato
Date: Mon Jul 28 22:59:34 2008
New Revision: 3221
Log:
Enter O'Reilly second-round copyedits.
Modified:
trunk/src/en/book/ch08-embedding-svn.xml
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 Mon Jul 28 22:59:34 2008
@@ -3,13 +3,13 @@
<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),
+ 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,
- Java, or Ruby.</para>
+ Java, and Ruby.</para>
<para>This chapter is for those who wish to interact with Subversion
through its public API or its various language bindings. If you
@@ -30,9 +30,9 @@
<title>Layered Library Design</title>
<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" />). We will examine
+ 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
@@ -76,13 +76,13 @@
loader</para></listitem>
</varlistentry>
<varlistentry>
- <term>libsvn_ra_neon</term>
- <listitem><para>The WebDAV Repository Access
+ <term>libsvn_ra_local</term>
+ <listitem><para>The local Repository Access
module</para></listitem>
</varlistentry>
<varlistentry>
- <term>libsvn_ra_local</term>
- <listitem><para>The local Repository Access
+ <term>libsvn_ra_neon</term>
+ <listitem><para>The WebDAV Repository Access
module</para></listitem>
</varlistentry>
<varlistentry>
@@ -135,13 +135,13 @@
given module with a whole new library that implements the same
API without affecting the rest of the code base. In some sense,
this happens within Subversion already. The
- <filename>libsvn_ra_neon</filename>,
<filename>libsvn_ra_local</filename>,
+ <filename>libsvn_ra_neon</filename>,
<filename>libsvn_ra_serf</filename>, and
<filename>libsvn_ra_svn</filename> libraries each implement the
same interface, all working as plug-ins to
<filename>libsvn_ra</filename>. And all four communicate with
- the Repository Layer—libsvn_ra_local connects to the
+ the Repository layer—<filename>libsvn_ra_local</filename> connects to the
repository directly; the other three do so over a network. The
<filename>libsvn_fs_base</filename> and
<filename>libsvn_fs_fs</filename> libraries are another pair of
@@ -156,8 +156,8 @@
Subversion client (see <xref
linkend="svn.developer.layerlib.client"/>). So while the
Subversion distribution provides only the <command>svn</command>
- command-line client program, there are several third-party
- programs that provide various forms of graphical client UIs.
+ command-line client program, several third-party
+ programs provide various forms of graphical client UIs.
These GUIs use the same APIs that the stock command-line client
does. This type of modularity has played a large role in the
proliferation of available Subversion clients and IDE
@@ -168,7 +168,7 @@
<sect2 id="svn.developer.layerlib.repos">
<title>Repository Layer</title>
- <para>When referring to Subversion's Repository Layer, we're
+ <para>When referring to Subversion's Repository layer, we're
generally talking about two basic concepts—the versioned
filesystem implementation (accessed via
<filename>libsvn_fs</filename>, and supported by its
@@ -178,13 +178,13 @@
<filename>libsvn_repos</filename>). These libraries provide
the storage and reporting mechanisms for the various revisions
of your version-controlled data. This layer is connected to
- the Client Layer via the Repository Access Layer, and is, from
+ the Client layer via the Repository Access layer, and is, from
the perspective of the Subversion user, the stuff at the
<quote>other end of the line.</quote></para>
- <para>The Subversion Filesystem is not a kernel-level filesystem
+ <para>The Subversion filesystem is not a kernel-level filesystem
that one would install in an operating system (such as the
- Linux ext2 or NTFS), but instead is a a virtual filesystem.
+ Linux ext2 or NTFS), but instead is a virtual filesystem.
Rather than storing <quote>files</quote> and
<quote>directories</quote> as real files and directories (the
kind you can navigate through using your favorite shell
@@ -200,7 +200,7 @@
something similar to this before launching the Google Code
Project Hosting service: they announced in mid-2006 that
members of its open source team had written a new proprietary
- Subversion filesystem plug-in that used their ultra-scalable
+ Subversion filesystem plug-in that used Google's ultra-scalable
Bigtable database for its storage.</para>
<para>The filesystem API exported by
@@ -211,7 +211,7 @@
It also has features that are not quite as common, such as the
ability to add, modify, and remove metadata
(<quote>properties</quote>) on each file or directory.
- Furthermore, the Subversion Filesystem is a versioning
+ Furthermore, the Subversion filesystem is a versioning
filesystem, which means that as you make changes to your
directory tree, Subversion remembers what your tree looked
like before those changes. And before the previous changes.
@@ -255,7 +255,7 @@
other words, transactions give you the ability to perform a
set of actions in an all-or-nothing fashion—either all
the actions in the set complete with success, or they all
- get treated as if <emphasis>none</emphasis> of them ever
+ get treated as though <emphasis>none</emphasis> of them ever
happened—and in a way that does not interfere with
other processes acting on the data.</para>
@@ -269,8 +269,8 @@
tree. If that isn't confusing enough, consider the fact
that Subversion uses a database transaction during the
creation of a Subversion transaction (so that if the
- creation of Subversion transaction fails, the database will
- look as if we had never attempted that creation in the first
+ creation of a Subversion transaction fails, the database will
+ look as though we had never attempted that creation in the first
place)!</para>
<para>Fortunately for users of the filesystem API, the
@@ -283,12 +283,12 @@
</sidebar>
- <para>Most of the functionality provided by the filesystem
- interface deals with actions that occur on individual
- filesystem paths. That is, from outside of the filesystem, the
+ <para>Most of the functionality the filesystem
+ interface provides deals with actions that occur on individual
+ filesystem paths. That is, from outside the filesystem, the
primary mechanism for describing and accessing the individual
revisions of files and directories comes through the use of
- path strings such as <filename>/foo/bar</filename>, just as if
+ path strings such as <filename>/foo/bar</filename>, just as though
you were addressing files and directories through your
favorite shell program. You add new files and directories by
passing their paths-to-be to the right API functions. You
@@ -323,8 +323,8 @@
<parameter>root</parameter> argument. This
<literal>svn_fs_root_t</literal> argument describes
either a revision or a Subversion transaction (which is simply
- a revision in the making) and provides that third-dimensional
- context needed to understand the difference between
+ a revision in the making) and provides that third dimension
+ of context needed to understand the difference between
<filename>/foo/bar</filename> in revision 32, and the same
path as it exists in revision 98. <xref
linkend="svn.developer.layerlib.repos.dia-2"/> shows revision
@@ -404,8 +404,8 @@
<sect2 id="svn.developer.layerlib.ra">
<title>Repository Access Layer</title>
- <para>If the Subversion Repository Layer is at <quote>the other
- end of the line,</quote> the Repository Access (RA) Layer is
+ <para>If the Subversion Repository layer is at <quote>the other
+ end of the line,</quote> the Repository Access (RA) layer is
the line itself. Charged with marshaling data between the
client libraries and the repository, this layer includes the
<filename>libsvn_ra</filename> module loader library, the RA
@@ -457,7 +457,7 @@
$
</screen>
- <para>The public API exported by the RA Layer contains
+ <para>The public API exported by the RA layer contains
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
@@ -471,7 +471,7 @@
<para>For those who wish to access a Subversion repository
using still another protocol, that is precisely why the
- Repository Access Layer is modularized! Developers can simply
+ Repository Access layer is modularized! Developers can simply
write a new library that implements the RA interface on one
side and communicates with the repository on the other. Your
new library can use existing network protocols or you can
@@ -514,7 +514,7 @@
<para>The Subversion client library,
<filename>libsvn_client</filename>, has the broadest
responsibility; its job is to mingle the functionality of the
- working copy library with that of the Repository Access Layer,
+ working copy library with that of the Repository Access layer,
and then to provide the highest-level API to any application
that wishes to perform general revision control actions. For
example, the function
@@ -536,7 +536,7 @@
<filename>libsvn_client</filename> API to the same functionality,
data, and callback mechanisms that the command-line client
uses. In fact, the Subversion source code tree contains a
- small C program (which can be found at
+ small C program (which you can find at
<filename>tools/examples/minimal_client.c</filename>) that
exemplifies how to wield the Subversion API to create a simple
client program.</para>
@@ -596,25 +596,25 @@
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 like:</para>
+ <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>
+ directory</para>
</listitem>
<listitem>
- <para>What revision of each of those files and directories are
- currently present in the working copy.</para>
+ <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>
+ to those files and directories</para>
</listitem>
<listitem>
<para>Pristine (unedited) copies of the working copy
- files.</para>
+ files</para>
</listitem>
</itemizedlist>
@@ -639,7 +639,7 @@
<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 that tracks the repository
+ 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,
@@ -678,28 +678,28 @@
<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
+ 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 comes at the
+ 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
+ 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 they want to commit a tiny
+ 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
+ <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>
@@ -719,12 +719,12 @@
libraries, with header (<filename>.h</filename>) 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>)
+ locations (e.g., <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
+ 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
@@ -735,7 +735,7 @@
<literal>wc</literal>, <literal>client</literal>,
<literal>fs</literal>, etc.), followed by a single underscore
(<literal>_</literal>), and then the rest of the symbol name.
- Semi-public functions (used among source files of a given
+ Semipublic functions (used among source files of a given
library but not by code outside that library, and found inside
the library directories themselves) differ from this naming
scheme in that instead of a single underscore after the library
@@ -748,7 +748,7 @@
<para>Another good source of information about programming against
the Subversion APIs is the project's own hacking guidelines,
- which can be found at <ulink
+ which you can find at <ulink
url="http://subversion.tigris.org/hacking.html" />. This
document contains useful information, which, while aimed at
developers and would-be developers of Subversion itself, is
@@ -777,8 +777,8 @@
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
- does. Currently this list includes all flavors of Unix,
+ client compiles and runs anywhere that th eApache HTTP Server
+ 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
@@ -800,7 +800,7 @@
<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 <emphasis>are</emphasis>
+ required to do the same, she <emphasis>is</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>
@@ -870,12 +870,12 @@
<filename>libsvn_client</filename> interface needs to first
convert paths from the locale-specific encoding to UTF-8
before passing those paths to the Subversion libraries, and
- then re-convert any resultant output paths from Subversion
+ then reconvert any resultant output paths from Subversion
back into the locale's encoding before using those paths for
non-Subversion purposes. Fortunately, Subversion provides a
suite of functions (see
- <filename>subversion/include/svn_utf.h</filename>) that can be
- used by any program to do these conversions.</para>
+ <filename>subversion/include/svn_utf.h</filename>) that
+ any program can use to do these conversions.</para>
<para>Also, Subversion APIs require all URL parameters to be
properly URI-encoded. So, instead of passing
@@ -889,10 +889,10 @@
<!-- =============================================================== -->
<sect2 id="svn.developer.usingapi.otherlangs">
- <title>Using Languages Other than C and C++</title>
+ <title>Using Languages Other Than C and C++</title>
<para>If you are interested in using the Subversion libraries in
- conjunction with something other than a C program—say a
+ 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
SWIG bindings for Subversion are located in
@@ -902,7 +902,7 @@
translate the datatypes native to your scripting language into
the datatypes needed by Subversion's C libraries.</para>
- <para>Significant efforts have been made towards creating
+ <para>Significant efforts have been made toward 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
@@ -945,11 +945,11 @@
interface than the more C-like APIs provided by Subversion's
own Python bindings. And if you're looking for a pure Java
implementation of Subversion, check out SVNKit (<ulink
- url="http://svnkit.com/" />), which is Subversion re-written
+ url="http://svnkit.com/" />), which is Subversion rewritten
from the ground up in Java.</para>
<sidebar>
- <title>SVNKit versus javahl</title>
+ <title>SVNKit Versus javahl</title>
<para>In 2005, a small company called TMate announced the
1.0.0 release of JavaSVN—a pure Java implementation of
@@ -976,13 +976,13 @@
already happened once—SVNKit cannot access BDB-backed
Subversion repositories via the <literal>file://</literal>
protocol because there's no pure Java implementation of
- Berkeley DB that is file format-compatible with the native
+ Berkeley DB that is file-format-compatible with the native
implementation of that library.</para>
<para>That said, SVNKit has a well-established track record of
reliability. And a pure Java solution is much more robust
in the face of programming errors—a bug in SVNKit
- might raise an Exception, but a bug in the Subversion core
+ might raise a catchable Java Exception, but a bug in the Subversion core
libraries as accessed via javahl can bring down your entire
Java Runtime Environment. So, weigh the costs when choosing
a Java-based Subversion implementation.</para>
@@ -1124,7 +1124,7 @@
API knows nothing about the repository library's hook
mechanism. If you want your Subversion repository to
automatically perform some set of non-Subversion tasks every
- time you commit a transaction (for example, sending an
+ time you commit a transaction (e.g., sending an
email that describes all the changes made in that transaction
to your developer mailing list), you need to use the
<filename>libsvn_repos</filename>-wrapped version of that
@@ -1141,7 +1141,7 @@
print the various paths reached during the crawl.</para>
<example id="svn.developer.usingapi.otherlangs.ex-1">
- <title>Using the Repository Layer with Python</title>
+ <title>Using the Repository layer with Python</title>
<programlisting>
#!/usr/bin/python
@@ -1231,7 +1231,7 @@
simplifying the process of writing a Subversion client. <xref
linkend="svn.developer.usingapi.otherlangs.ex-2" /> is a brief
example of how that library can be accessed via the SWIG
- Python bindings to recreate a scaled-down version of the
+ Python bindings to re-create a scaled-down version of the
<command>svn status</command> command.</para>
<example id="svn.developer.usingapi.otherlangs.ex-2">
@@ -1327,7 +1327,7 @@
<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 data types. The call to
+ Python datatypes. The call to
<function>svn_client_ctx_t()</function> is deceiving because
the public Subversion API has no such function—this just
happens to be a case where SWIG's automatic language
@@ -1344,6 +1344,31 @@
</sect2>
</sect1>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.developer.summary">
+ <title>Summary</title>
+
+ <para>One of Subversion's greatest features isn't something you
+ get from running its command-line client or other tools. It's
+ the fact that Subversion was designed modularly and provides a
+ stable, public API so that others—like yourself,
+ perhaps—can write custom software that drives Subversion's
+ core logic.</para>
+
+ <para>In this chapter, we took a closer look at Subversion's
+ architecture, examining its logical layers and describing that
+ public API, the very same API that Subversion's own layers use
+ to communicate with each other. Many developers have found
+ interesting uses for the Subversion API, from simple repository
+ hook scripts, to integrations between Subversion and some other
+ application, to completely different version control systems.
+ What unique itch will <emphasis>you</emphasis> scratch with
+ it?</para>
+
+ </sect1>
+
</chapter>
<!--
More information about the svnbook-dev
mailing list