[svnbook commit] r2679 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Sun Feb 11 19:49:59 CST 2007
Author: cmpilato
Date: Sun Feb 11 19:49:59 2007
New Revision: 2679
Modified:
trunk/src/en/book/ch-developer-info.xml
trunk/src/en/book/ch-repository-admin.xml
trunk/src/en/book/ch-server-configuration.xml
Log:
* src/en/book/ch-repository-admin.xml
* src/en/book/ch-server-configuration.xml
* src/en/book/ch-developer-info.xml
Commit up some stuff I did on the plane back from San Francisco. I
don't really remember the details.
Modified: trunk/src/en/book/ch-developer-info.xml
==============================================================================
--- trunk/src/en/book/ch-developer-info.xml (original)
+++ trunk/src/en/book/ch-developer-info.xml Sun Feb 11 19:49:59 2007
@@ -6,20 +6,22 @@
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. And the interface is
- available not only to other C programs, but also to programs
- written in higher-level languages such as Python or Java.</para>
+ 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 or
+ Java.</para>
<para>This chapter is for those who wish to interact with Subversion
- through its public API or various language bindings. If you wish
- to write robust wrapper scripts around Subversion functionality to
- simplify your own life, are trying to develop more complex
- integrations between Subversion and other pieces of software, or
- just have an interest in Subversion's various library modules and
- what they offer, this chapter is for you. If, however, you don't
- foresee yourself participating with Subversion at such a level,
- feel free to skip this chapter with the confidence that your
- experience as a Subversion user will not be affected.</para>
+ through its public API or its various language bindings. If you
+ wish to write robust wrapper scripts around Subversion
+ functionality to simplify your own life, are trying to develop
+ more complex integrations between Subversion and other pieces of
+ software, or just have an interest in Subversion's various library
+ modules and what they offer, this chapter is for you. If,
+ however, you don't foresee yourself participating with Subversion
+ at such a level, feel free to skip this chapter with the
+ confidence that your experience as a Subversion user will not be
+ affected.</para>
<!-- ================================================================= -->
@@ -35,11 +37,11 @@
of Subversion's libraries in <xref
linkend="svn.developer.layerlib.tbl-1"/>. For the sake of
consistency, we will refer to the libraries by their
- extensionless Unix library names (e.g.: libsvn_fs, libsvn_wc,
- mod_dav_svn).</para>
+ extensionless Unix library names (libsvn_fs, libsvn_wc,
+ mod_dav_svn, etc.).</para>
<table id="svn.developer.layerlib.tbl-1">
- <title>A Brief Inventory of the Subversion Libraries</title>
+ <title>Brief Inventory of the Subversion Libraries</title>
<tgroup cols="2">
<thead>
<row>
@@ -139,20 +141,22 @@
Layer—libsvn_ra_local connects to the repository directly;
the other three do so over a network. The libsvn_fs_base and
libsvn_fs_fs libraries are another pair of libraries that
- implement the same functionality in different ways—they
+ implement the same functionality in different ways—both
are plugins to the common libsvn_fs library.</para>
<para>The client itself also highlights the benefits of modularity
- in the Subversion design. While Subversion itself comes with
- only a command-line client program, there are several third
- party programs which provide various forms of client GUI. These
- GUIs use the same APIs that the stock command-line client does.
- Subversion's libsvn_client library is a one-stop shop for most
- of the functionality necessary for designing a working
- Subversion client (see <xref
- linkend="svn.developer.layerlib.client"/>), and this played a
- large role in the proliferation of available Subversion clients
- and IDE integrations.</para>
+ in the Subversion design. Subversion's libsvn_client library is
+ a one-stop shop for most of the functionality necessary for
+ designing a working 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 which provide various forms of graphical client UI.
+ 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
+ integrations and, by extension, to the tremendous adoption rate
+ of Subversion itself.</para>
<!-- =============================================================== -->
<sect2 id="svn.developer.layerlib.repos">
@@ -179,11 +183,16 @@
available abstract storage backends—either a Berkeley DB
database environment, or a flat-file representation. (To
learn more about the two repository back-ends, see <xref
- linkend="svn.reposadmin.basics.backends"/>.) However, there
- has been considerable interest by the development community in
+ linkend="svn.reposadmin.basics.backends"/>.) There has even
+ been considerable interest by the development community in
giving future releases of Subversion the ability to use other
back-end database systems, perhaps through a mechanism such as
- Open Database Connectivity (ODBC).</para>
+ Open Database Connectivity (ODBC). In fact, Google did just
+ this before launching the Projects service of Google Code,
+ announcing in mid-2006 that members of its Open Source team
+ had written a new proprietary Subversion filesystem plugin
+ which used their Bigtable ultra-scalable database for its
+ storage.</para>
<para>The filesystem API exported by libsvn_fs contains the
kinds of functionality you would expect from any other
@@ -1152,45 +1161,7 @@
format for storing the property names and values.</para>
</sect2>
- </sect1>
-
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <!-- ================================================================= -->
- <sect1 id="svn.developer.webdav">
- <title>WebDAV</title>
- <para>WebDAV (shorthand for <quote>Web-based Distributed Authoring
- and Versioning</quote>) is an extension of the standard HTTP
- protocol designed to make the web into a read/write medium,
- instead of the basically read-only medium that exists today.
- The theory is that directories and files can be shared—as
- both readable and writable objects—over the web. RFCs
- 2518 and 3253 describe the WebDAV/DeltaV extensions to HTTP, and
- are available (along with a lot of other useful information) at
- <ulink url="http://www.webdav.org/"/>.</para>
-
- <para>A number of operating system file browsers are already able
- to mount networked directories using WebDAV. On Win32, the
- Windows Explorer can browse what it calls Web Folders (which are
- just WebDAV-ready network locations) as if they were regular
- shared folders. Mac OS X also has this capability, as do the
- Nautilus and Konqueror browsers (under GNOME and KDE,
- respectively).</para>
-
- <para>How does all of this apply to Subversion? The mod_dav_svn
- Apache module uses HTTP, extended by WebDAV and DeltaV, as one
- of its network protocols. Subversion uses mod_dav_svn to map
- between Subversion's versioning concepts and those of RFCs 2518
- and 3253.
- </para>
-
- <para>For a more thorough discussion of WebDAV, how it works, and
- how Subversion uses it, see <xref linkend="svn.webdav"/>. Among
- other things, that appendix discusses the degree to which
- Subversion adheres to the generic WebDAV specification, and how
- that affects interoperability with generic WebDAV
- clients.</para>
</sect1>
</chapter>
Modified: trunk/src/en/book/ch-repository-admin.xml
==============================================================================
--- trunk/src/en/book/ch-repository-admin.xml (original)
+++ trunk/src/en/book/ch-repository-admin.xml Sun Feb 11 19:49:59 2007
@@ -51,23 +51,23 @@
(such as the Windows Explorer) or command-line based filesystem
navigation tools, the Subversion repository is just another
directory full of stuff. There are some subdirectories with
- some human-readable configuration files in them, and a
- subdirectory with some not-so-human-readable data files, and so
- on. As in other areas of the Subversion design, modularity is
- given high regard, and hierarchical organization is preferred to
- cluttered chaos. So a shallow glance into a typical repository
- from a nuts-and-bolts perspective is sufficient to reveal the
- basic components of the repository:</para>
+ human-readable configuration files in them, some subdirectories
+ with some not-so-human-readable data files, and so on. As in
+ other areas of the Subversion design, modularity is given high
+ regard, and hierarchical organization is preferred to cluttered
+ chaos. So a shallow glance into a typical repository from a
+ nuts-and-bolts perspective is sufficient to reveal the basic
+ components of the repository:</para>
<screen>
$ ls repos
conf/ dav/ db/ format hooks/ locks/ README.txt
</screen>
- <para>Briefly, here's a legend which will help you interpret
- exactly what you're seeing. (Don't get bogged down in the
- terminology, though—detailed coverage of these components
- exists elsewhere in this and other chapters.)</para>
+ <para>Here's a quick fly-by overview of what exactly you're seeing
+ in this directory listing. (Don't get bogged down in the
+ terminology—detailed coverage of these components exists
+ elsewhere in this and other chapters.)</para>
<variablelist>
<varlistentry>
@@ -86,10 +86,7 @@
<varlistentry>
<term>db</term>
<listitem>
- <para>The data store for all of your versioned data. This
- directory is either a Berkeley DB environment (full of DB
- tables and other things), or is an FSFS environment
- containing revision files.</para>
+ <para>The data store for all of your versioned data.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -109,30 +106,30 @@
<varlistentry>
<term>locks</term>
<listitem>
- <para>A directory for Subversion's repository locking
- data, used for tracking accessors to the repository.</para>
+ <para>A directory for Subversion's repository lock
+ files, used for tracking accessors to the repository.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>README.txt</term>
<listitem>
- <para>A file which merely informs its readers that they
- are looking at a Subversion repository.</para>
+ <para>A file whose contents merely inform its readers that
+ they are looking at a Subversion repository.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Of course, when accessed via the Subversion libraries, this
otherwise unremarkable collection of files and directories
- suddenly becomes, among other things, an implementation of a
- virtual, versioned filesystem. This filesystem has its own
- notions of directories and files, very similar to the notions of
- such things held by real filesystems (such as NTFS, FAT32, ext3,
- and so on). But this is a special filesystem—it hangs
- these directories and files from revisions, keeping all the
- changes you've ever made to them safely stored and forever
- accessible. This is where the entirety of your versioned data
- lives.</para>
+ suddenly becomes an implementation of a virtual, versioned
+ filesystem, complete with customizable event triggers. This
+ filesystem has its own notions of directories and files, very
+ similar to the notions of such things held by real filesystems
+ (such as NTFS, FAT32, ext3, and so on). But this is a special
+ filesystem—it hangs these directories and files from
+ revisions, keeping all the changes you've ever made to them
+ safely stored and forever accessible. This is where the
+ entirety of your versioned data lives.</para>
</sect1>
@@ -181,15 +178,15 @@
<title>Choosing a Data Store</title>
<para>As of Subversion 1.1, Subversion provides two options for
- the type of underlying data store (often referred to as
+ the type of underlying data store—often referred to as
<quote>the back-end</quote> or, somewhat confusingly,
- <quote>the (versioned) filesystem</quote>) that each
+ <quote>the (versioned) filesystem</quote>—that each
repository uses. One type of data store keeps everything in a
- Berkeley DB database; repositories that use this type are
- often referred to as being <quote>BDB-backed</quote>. The
- other type stores data in ordinary flat files, using a custom
- format. Subversion developers have adopted the habit of
- referring to this latter data storage mechanism as
+ Berkeley DB database environment; repositories that use this
+ type are often referred to as being <quote>BDB-backed</quote>.
+ The other type stores data in ordinary flat files, using a
+ custom format. Subversion developers have adopted the habit
+ of referring to this latter data storage mechanism as
<firstterm>FSFS</firstterm>
<footnote>
<para>Often pronounced <quote>fuzz-fuzz</quote>, if Jack
@@ -658,20 +655,30 @@
changes to your repository, then you don't need to do this
sort of access control via the hook system.</para>
+ <para>There is no shortage of Subversion hook programs and
+ scripts freely available either from the Subversion community
+ itself or elsewhere. These scripts cover a wide range of
+ utility—basic access control, policy adherence checking,
+ issue tracker integration, email- or RSS-based commit
+ notification, and beyond. See <xref linkend="svn.3rdparty" />
+ for discussion of some of the most commonly used hook
+ programs. Or, if you wish to write your own, see <xref
+ linkend="svn.developer" />.</para>
+
<warning>
- <para>Do not attempt to modify the transaction using hook
- scripts. A common example of this would be to automatically
- set properties such as <literal>svn:eol-style</literal> or
- <literal>svn:mime-type</literal> during the commit. While
- this might seem like a good idea, it causes problems. The
- main problem is that the client does not know about the
- change made by the hook program, and there is no way to
- inform the client that it is out-of-date. This
+ <para>While hook scripts can be leveraged to do almost
+ anything, there is one dimension in which hook script
+ authors should show restraint: do <emphasis>not</emphasis>
+ modify a commit transaction using hook scripts. While it
+ might be tempting to use hook scripts to automatically
+ correct errors or shortcomings or policy violations present
+ in the files being committed, doing so can cause problems.
+ Subversion's keeps client-side caches of certain bits of
+ repository data, and if you change a commit transaction in
+ this way, those cache become indetectably stale. This
inconsistency can lead to surprising and unexpected
- behavior.</para>
-
- <para>Instead of attempting to modify the transaction, it is
- much better to <emphasis>check</emphasis> the transaction in
+ behavior. Instead of modifying the transaction, it is much
+ better to <emphasis>validate</emphasis> the transaction in
the <filename>pre-commit</filename> hook and reject the
commit if it does not meet the desired requirements.</para>
</warning>
@@ -694,14 +701,14 @@
access patterns, might require a different set of
configuration option values.</para>
- <para>The folks at Sleepycat (the producers of Berkeley DB)
- understand that different databases have different
- requirements, and so they have provided a mechanism for
- overriding at runtime many of the configuration values for the
- Berkeley DB environment. Berkeley checks for the presence of
- a file named <filename>DB_CONFIG</filename> in each
- environment directory, and parses the options found in that
- file for use with that particular Berkeley environment.</para>
+ <para>The producers of Berkeley DB understand that different
+ databases have different requirements, and so they have
+ provided a mechanism for overriding at runtime many of the
+ configuration values for the Berkeley DB environment.
+ Berkeley checks for the presence of a file named
+ <filename>DB_CONFIG</filename> in each environment directory,
+ and parses the options found in that file for use with that
+ particular Berkeley environment.</para>
<para>The Berkeley configuration file for your repository is
located in the <filename>db</filename> environment directory,
@@ -1504,9 +1511,10 @@
subdirectory of your repository. This subdirectory is a
regular Berkeley DB environment directory, and can therefore
be used in conjunction with any of the Berkeley database
- tools (you can see the documentation for these tools at
- Sleepycat's website,
- <ulink url="http://www.sleepycat.com/"/>).</para>
+ tools (you can see the documentation for these tools at the
+ Berkeley DB website, <ulink
+ url="http://www.oracle.com/technology/documentation/berkeley-db/db/"
+ />).</para>
<para>For day-to-day Subversion use, these tools are
unnecessary. Most of the functionality typically needed for
@@ -2282,7 +2290,7 @@
generating a faulty backup, since someone might be currently
writing to the database.</para>
- <para>In the case of Berkeley DB, Sleepycat documents describe a
+ <para>In the case of Berkeley DB, the documentation describes a
certain order in which database files can be copied that will
guarantee a valid backup copy. And a similar ordering exists
for FSFS data. Better still, you don't have to implement
Modified: trunk/src/en/book/ch-server-configuration.xml
==============================================================================
--- trunk/src/en/book/ch-server-configuration.xml (original)
+++ trunk/src/en/book/ch-server-configuration.xml Sun Feb 11 19:49:59 2007
@@ -2010,14 +2010,14 @@
<para>Your web browser only speaks ordinary HTTP. That
means it only knows how to GET public URLs, which
represent the latest versions of files and directories.
- According to the WebDAV/DeltaV spec, each server defines a
- private URL syntax for older versions of resources, and
- that syntax is opaque to clients. To find an older
- version of a file, a client must follow a specific
- procedure to <quote>discover</quote> the proper URL; the
- procedure involves issuing a series of WebDAV PROPFIND
- requests and understanding DeltaV concepts. This is
- something your web browser simply can't do.</para>
+ According to the WebDAV/DeltaV specification, each server
+ defines a private URL syntax for older versions of
+ resources, and that syntax is opaque to clients. To find
+ an older version of a file, a client must follow a
+ specific procedure to <quote>discover</quote> the proper
+ URL; the procedure involves issuing a series of WebDAV
+ PROPFIND requests and understanding DeltaV concepts. This
+ is something your web browser simply can't do.</para>
<para>So to answer the question, one obvious way to see
older revisions of files and directories is by passing the
More information about the svnbook-dev
mailing list