[svnbook commit] r1647 - trunk/src/zh/book

rocksun svnbook-dev at red-bean.com
Sat Aug 27 09:29:32 CDT 2005

Author: rocksun
Date: Sat Aug 27 09:29:30 2005
New Revision: 1647

* zh/book/ch08.xml: Add UTF BOM, finished, need more check up. 

Modified: trunk/src/zh/book/ch08.xml
--- trunk/src/zh/book/ch08.xml	(original)
+++ trunk/src/zh/book/ch08.xml	Sat Aug 27 09:29:30 2005
@@ -419,155 +419,56 @@
   <sect1 id="svn-ch-8-sect-2">
-    <para>Developing applications against the Subversion library APIs
-      is fairly straightforward.  All of the public header files live
-      in the <filename>subversion/include</filename> directory of the
-      source tree.  These headers are copied into your system
-      locations 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.</para>
-    <para>The first thing you might notice is that Subversion's
-      datatypes and functions are namespace protected.  Every public
-      Subversion symbol name begins with <literal>svn_</literal>,
-      followed by a short code for the library in which the symbol is
-      defined (such as <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 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 code, they use a double
-      underscore (<literal>__</literal>).  Functions that are private
-      to a given source file have no special prefixing, and are declared
-      <literal>static</literal>.  Of course, a compiler isn't
-      interested in these naming conventions, but they help to clarify
-      the scope of a given function or datatype.</para>
+    <para>使用Subversion库API开发应用看起来相当的直接,所有的公共头文件放在源文件的<filename>subversion/include</filename>目录,从源代码编译和安装Subversion本身,需要这些头文件拷贝到系统位置。这些头文件包括了所有用户可以访问的功能和类型。
+   </para>
+    <para>你首先应该注意Subversion的数据类型和方法是命名空间保护的,每一个公共Subversion对象名以<literal>svn_</literal>开头,然后紧跟一个这个对象定义(如<literal>wc</literal>、<literal>client</literal>和<literal>fs</literal>其他)所在的库的简短编码,然后是一个下划线(<literal>_</literal>)和后面的对象名称。半公开的方法(库使用,但是但库之外代码不可以使用并且只可以在库自己的目录看到)与这个命名模式不同,并不是库代码之后紧跟一个下划线,他们是用两个下划线(<literal>__</literal>)。给定源文件的私有方法没有特殊前缀,使用<literal>static</literal>声明。当然,一个编译器不会关心命名习惯,只是用来区分给定方法或数据类型。
+   </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-2.1">
-      <title>The Apache Portable Runtime Library</title>
-      <para>Along with Subversion's own datatype, you will see many
-        references to datatypes that begin with
-        <literal>apr_</literal>—symbols from the Apache
-        Portable Runtime (APR) library.  APR is Apache's portability
-        library, originally carved out of its server code as an
-        attempt to separate the OS-specific bits from the
-        OS-independent portions of the code.  The result was a library
-        that provides a generic API for performing operations that
-        differ mildly—or wildly—from OS to OS.  While the
-        Apache HTTP Server was obviously the first user of the APR
-        library, the Subversion developers immediately recognized the
-        value of using APR as well.  This means that there are
-        practically no OS-specific code portions in Subversion itself.
-        Also, it means that the Subversion client compiles and runs
-        anywhere that the server does.  Currently this list includes
-        all flavors of Unix, Win32, BeOS, OS/2, and Mac OS X.</para>
+      <title>Apache便携运行库</title>
+      <para>伴随Subversion自己的数据类型,你会看到许多<literal>apr_</literal>开头的数据类型引用—来自Apache便携运行库(APR)的对象。APR是Apache便携运行库,源自为了服务器代码的多平台性,尝试将不同的操作系统特定字节与操作系统无关代码隔离。结果就提供了一个基础API的库,只有一些适度区别—或者是广泛的—来自各个操作系统。Apache HTTP服务器很明显是APR库的第一个用户,Subversion开发者立刻发现了使用APR库的价值。意味着Subversion没有操作系统特定的代码,也意味着Subversion客户端可以在Server存在的平台编译和运行。当前这个列表包括,各种类型的Unix、Win32、OS/2和Mac OS X。
+     </para>
-      <para>In addition to providing consistent implementations of
-        system calls that differ across operating systems,
+      <para>除了提供了跨平台一致的系统调用,
-          <para>Subversion uses ANSI system calls and datatypes as much
-            as possible.</para>
+          <para>Subversion使用尽可能多ANSI系统调用和数据类型。
+          </para>
-        APR gives Subversion immediate access to many custom
-        datatypes, such as dynamic arrays and hash tables.  Subversion
-        uses these types extensively throughout the codebase.  But
-        perhaps the most pervasive APR datatype, found in nearly every
-        Subversion API prototype, is the
-        <literal>apr_pool_t</literal>—the APR memory pool.
-        Subversion uses pools internally for all its memory allocation
-        needs (unless an external library requires a different memory
-        management schema for data passed through its API),
+        APR给Subversion对多种数据类型有快速的访问,如动态数组和哈希表。Subversion在代码中广泛使用这些类型,但是或许大多数普遍深入的APR数据类型可以在所有的Subversion的API原型中发现,是<literal>apr_pool_t</literal>—APR内存池,Subversion使用内部缓冲池用来进行内存分配(除非外部库在API传递参数时需要一个不同的内存管理模式),
-          <para>Neon and Berkeley DB are examples of such libraries.</para>
+          <para>Neon和Berkeley DB就是这种库的例子。</para>
-        and while a person coding against the Subversion APIs is
-        not required to do the same, they are 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> to initialize the
-        APR subsystem, and then must acquire a pool for use with
-        Subversion API calls.  See <xref linkend="svn-ch-8-sect-5"/>
-        for more information.</para>
+        而且一个人如果针对Subversion的API编码不需要做同样的事情,他们可以在需要时给API提供缓冲池,这意味着Subversion的API使用者也必须链接到APR,必须调用<function>apr_initialize()</function>来初始化APR字系统,然后必须得到一个缓冲池用来进行Subversion的API调用。详情见<xref linkend="svn-ch-8-sect-5"/>。
+       </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-2.2">
-      <title>URL and Path Requirements</title>
+      <title>URL和路径需求</title>
+      <para>因为分布式版本控制操作是Subversion存在的重点,有意义来关注一下国际化(i18n)支持。毕竟,当<quote>分布式</quote>或许意味着<quote>横跨办公室</quote>,它也意味着<quote>横跨全球</quote>。为了更容易一点,Subversion的所有公共接口只接受路径参数,这些参数是传统的,使用UTF-8编码。这意味着,举个例子,任何新的使用libsvn_client接口客户端库,在把这些参数传递给Subversion库前,需要首先将路径从本地代码转化为UTF-8代码,然后将Subversion传递回来的路径转换为本地代码,很幸运,Subversion提供了一组任何程序可以使用的转化方法(见<filename>subversion/include/svn_utf.h</filename>)。</para>
-      <para>With remote version control operation as the whole point
-        of Subversion's existence, it makes sense that some attention
-        has been paid to internationalization (i18n) support.  After
-        all, while <quote>remote</quote> might mean <quote>across the
-        office</quote>, it could just as well mean <quote>across the
-        globe.</quote> To facilitate this, all of Subversion's public
-        interfaces that accept path arguments expect those paths to be
-        canonicalized, and encoded in UTF-8.  This means, for example,
-        that any new client binary that drives the libsvn_client
-        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 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>
-      <para>Also, Subversion APIs require all URL parameters to be
-        properly URI-encoded.  So, instead of passing <systemitem
-        class="url">file:///home/username/My File.txt</systemitem> as
-        the URL of a file named <literal>My File.txt</literal>, you
-        need to pass <systemitem
-        class="url">file:///home/username/My%20File.txt</systemitem>.
-        Again, Subversion supplies helper functions that your
-        application can
-        use—<function>svn_path_uri_encode</function> and
-        <function>svn_path_uri_decode</function>, for URI encoding and
-        decoding, respectively.</para>
+      <para>同样,Subversion的API需要所有的URL参数是正确的URI编码,所以,我们不会传递<systemitem
+        class="url">file:///home/username/My File.txt</systemitem>作为<literal>My File.txt</literal>的URL,而会传递<systemitem
+        class="url">file:///home/username/My%20File.txt</systemitem>。再次,Subversion提供了一些你可以使用的助手方法—<function>svn_path_uri_encode</function>和<function>svn_path_uri_decode</function>,分别用来URI的编码和解码。
+       </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-2.3">
-      <title>Using Languages Other than C and C++</title> 
+      <title>使用C和C++以外的语言</title> 
+      <para>除C语言以外,如果你对使用其他语言结合Subversion库感兴趣—如Python脚本或是Java应用—Subversion通过简单包裹生成器(SWIG)提供了最初的支持。Subversion的SWIG绑定位于<filename>subversion/bindings/swig</filename>,并且慢慢的走向成熟进入可用状态。这个绑定允许你直接调用Subversion的API方法,使用包裹器会把脚本数据类型转化为Subversion需要的C语言库类型。</para>
+      <para>通过语言绑定访问Subversion的API有一个明显的好处—简单性。通常来讲,Python和Perl之类的语言比C和C++更加的灵活和简单,这些语言的高级数据类型和上下文驱动类型更加易于处理用户提供的信息,就像你知道的,人们精于把程序搞坏,脚本语言可以更优雅的处理这些错误信息,当然,灵活性经常带来性能的损失,这就是为什么使用紧密优化的,C基础的接口和库组件,然后与一种高效的、灵活的绑定语言,是这样的吸引人。</para>
-      <para>If you are interested in using the Subversion libraries in
-        conjunction with something other than a C program—say a
-        Python script or Java application—Subversion has some
-        initial support for this via the Simplified Wrapper and
-        Interface Generator (SWIG).  The SWIG bindings for Subversion
-        are located in <filename>subversion/bindings/swig</filename>
-        and are slowly maturing into a usable state.  These bindings
-        allow you to call Subversion API functions indirectly, using
-        wrappers that translate the datatypes native to your
-        scripting language into the datatypes needed by Subversion's
-        C libraries.</para>
-      <para>There is an obvious benefit to accessing the Subversion
-        APIs via a language binding—simplicity.  Generally
-        speaking, languages such as Python and Perl are much more
-        flexible and easy to use than C or C++.  The sort of
-        high-level datatypes and context-driven type checking provided
-        by these languages are often better at handling information
-        that comes from users.  As you know, humans are proficient at
-        botching up input to a program, and scripting languages tend
-        to handle that misinformation more gracefully.  Of course,
-        often that flexibility comes at the cost of performance.  That
-        is why using a tightly-optimized, C-based interface and
-        library suite, combined with a powerful, flexible binding
-        language, is so appealing.</para>
-      <para>Let's look at an example that uses Subversion's Python
-        SWIG bindings.  Our example will do the same thing as our last
-        example.  Note the difference in size and complexity of the
-        function this time!</para>
+      <para>让我们看看Subversion的Python SWIG绑定的实例,这个例子和前面的例子作同样的事,注意比较方法的长度和复杂性!</para>
       <example id="svn-ch-8-sect-2.3-ex-1">
-        <title>Using the Repository Layer with Python</title>
+        <title>使用Python处理版本库层</title>
 from svn import fs
@@ -605,24 +506,9 @@
-      <para>An implementation in C of the previous example would
-        stretch on quite a bit longer.  The same routine in C would
-        need to pay close attention to memory usage, and need to use
-        custom datatypes for representing the hash of entries and the
-        list of paths.  Python has hashes (called
-        <quote>dictionaries</quote>) and lists as built-in datatypes,
-        and provides a wonderful selection of methods for operating on
-        those types.  And since Python uses reference counting and
-        garbage collection, users of the language don't have to bother
-        themselves with allocating and freeing memory.</para>
-      <para>In the previous section of this chapter, we mentioned the
-        <filename>libsvn_client</filename> interface, and how it
-        exists for the sole purpose of simplifying the process of
-        writing a Subversion client.  The following is a brief example
-        of how that library can be accessed via the SWIG bindings.  In
-        just a few lines of Python, you can check out a fully
-        functional Subversion working copy!</para>
+      <para>前面C语言的实现确实有一点长,另外C语言的例行公事就是必须关注内存使用,并且需要使用自定义的数据类型来表示条目的哈希值和路径列表。Python有哈希(叫做<quote>dictionaries</quote>)并且列表示内置数据类型,并提供了许多操作这些类型的好方法。而且因为Python使用引用计数来进行垃圾收集,这种语言的用户不需要麻烦自己去分配和回收内存。</para>
+      <para>在本章的前面小节,我们提到<filename>libsvn_client</filename>接口,并且解释了它存在的唯一目的是为了简化编写Subversion客户端的过程,下面是一个如何同SWIG绑定访问库的简短例子,简单的几句Python代码,我们就可以检出一个完全功能的Subversion工作拷贝!</para>
       <example id="svn-ch-8-sect-2.3-ex-2">
         <title>A Simple Script to Check Out a Working Copy.</title>
@@ -655,19 +541,9 @@
-      <para>Subversion's language bindings unfortunately tend to lack
-        the level of attention given to the core Subversion modules.
-        However, there have been significant efforts towards creating
-        functional bindings for Python, Perl, and Java.  Once you have
-        the SWIG interface files properly configured, generation of
-        the specific wrappers for all the supported SWIG languages
-        (which currently includes versions of C#, Guile, Java,
-        MzScheme, OCaml, Perl, PHP, Python, Ruby, and Tcl) should
-        theoretically be trivial.  Still, some extra programming is
-        required to compensate for complex APIs that SWIG needs some
-        help generalizing.  For more information on SWIG itself, see
-        the project's website at <systemitem
-        class="url">http://www.swig.org/</systemitem>.</para>
+      <para>非常不幸,Subversion的语言绑定缺乏对核心Subversion模块的关注,但是,使用Python、Perl和Java创建有功能的邦定取得了显著的成就。一旦你的SWIG接口文件正确的配置,对于SWIG支持的语言(我们当前包括的版本有C#、Guile、Java、MzScheme、OCaml、Perl、PHP、Python、Ruby和Tcl)的特定语言绑定的包裹器的生成理论上是非常琐碎的。但是,对复杂API还是需要一些额外的的补充,SWIG需要帮助归纳。对于SWIG的更多信息,见这个项目的网站<systemitem
+        class="url">http://www.swig.org/</systemitem>。
+        </para>
@@ -676,76 +552,48 @@
   <!-- ******************************************************************* -->
   <sect1 id="svn-ch-8-sect-3">
-    <title>Inside the Working Copy Administration Area</title>
+    <title>进入工作拷贝的管理区</title>
-    <para>As we mentioned earlier, each directory of a Subversion
-      working copy contains a special subdirectory called
-      <filename>.svn</filename> which houses administrative data about
-      that working copy directory.  Subversion uses the information in
-      <filename>.svn</filename> to keep track of things like:</para>
+    <para>像我们前面提到的,每个Subversion工作拷贝包含了一个特别的子目录叫做<filename>.svn</filename>,这个目录包含了关于工作拷贝目录的管理数据,Subversion使用<filename>.svn</filename>中的信息来追踪如下的数据:
+   </para>
-        <para>Which repository location(s) are represented by the
-          files and subdirectories in the working copy
-          directory.</para>
+        <para>工作拷贝中展示的目录和文件在版本库中的位置。</para>
-        <para>What revision of each of those files and directories are
-          currently present in the working copy.</para>
+        <para>工作拷贝中当前展示的文件和目录的修订版本。</para>
-        <para>Any user-defined properties that might be attached
-          to those files and directories.</para>
+        <para>所有附加在文件和目录上的用户定义属性。</para>
-        <para>Pristine (un-edited) copies of the working copy
-          files.</para>
+        <para>初始(未编辑)的工作拷贝文件的拷贝。</para>
-    <para>While there are several other bits of data stored in the
-      <filename>.svn</filename> directory, we will examine only a
-      couple of the most important items.</para>
+    <para>然而<filename>.svn</filename>目录中还有一些其他的数据,我们会考察一些最重要的项目。
+    </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-3.1">
-      <title>The Entries File</title>
+      <title>条目文件</title>
-      <para>Perhaps the single most important file in the
-        <filename>.svn</filename> directory is the
-        <filename>entries</filename> file.  The entries file is an XML
-        document which contains the bulk of the administrative
-        information about a versioned resource in a working copy
-        directory.  It is this one file which 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>或许<filename>.svn</filename>目录中最重要的单个文件就是<filename>entries</filename>了,这个条目文件是一个XML文档,包含了关于工作拷贝中的版本化的资源的大多数管理性信息,这个文件保留了版本库URL、原始修订版本、可知的最后提交信息(作者、修订版本和时间戳)和本地拷贝历史—实际上是Subversion客户端关于一个版本化(或者是将要版本化的)资源的所有感兴趣的信息!</para>
-        <title>Comparing the Administrative Areas of Subversion and
-          CVS</title>
+        <title>比较Subversion和CVS的管理区域</title>
-        <para>A glance inside the typical <filename>.svn</filename>
-          directory turns up a bit more than what CVS maintains in its
-          <filename>CVS</filename> administrative directories.  The
-          <filename>entries</filename> file contains XML which
-          describes the current state of the working copy directory,
-          and basically serves the purposes of CVS's
-          <filename>Entries</filename>, <filename>Root</filename>, and
-          <filename>Repository</filename> files combined.</para>
+        <para>扫视一下典型的<filename>.svn</filename>目录会发现比CVS在<filename>CVS</filename>目录中的内容多一些,<filename>entries</filename>文件包含的XML描述了工作拷贝目录的当前状态,而且基本上合并了CVS的<filename>Entries</filename>、<filename>Root</filename>和<filename>Repository</filename>的功能。
+       </para>
-      <para>The following is an example of an actual entries
-        file:</para>
+      <para>如下是一个实际条目文件的例子:
+      </para>
       <example id="svn-ch-8-sect-3-ex-1">
-        <title>Contents of a Typical <filename>.svn/entries</filename>
-          File</title>
+        <title>典型的<filename>.svn/entries</filename>文件内容</title>
 <?xml version="1.0" encoding="utf-8"?>
@@ -787,89 +635,23 @@
-      <para>As you can see, the entries file is essentially a list of
-        entries.  Each <sgmltag>entry</sgmltag> tag represents one of
-        three things: the working copy directory itself (called the
-        <quote>this directory</quote> entry, and noted as having an
-        empty value for its <structfield>name</structfield>
-        attribute), a file in that working copy directory (noted by
-        having its <structfield>kind</structfield> attribute set to
-        <literal>"file"</literal>), or a subdirectory in that working
-        copy (<structfield>kind</structfield> here is set to
-        <literal>"dir"</literal>).  The files and subdirectories whose
-        entries are stored in this file are either already under
-        version control, or (as in the case of the file named
-        <filename>zeta</filename> above) are scheduled to be added to
-        version control when the user next commits this working copy
-        directory's changes.  Each entry has a unique name, and each
-        entry has a node kind.</para>
-      <para>Developers should be aware of some special rules that
-        Subversion uses when reading and writing its
-        <filename>entries</filename> files.  While each entry has a
-        revision and URL associated with it, note that not every
-        <sgmltag>entry</sgmltag> tag in the sample file has explicit
-        <structfield>revision</structfield> or
-        <structfield>url</structfield> attributes attached to it.
-        Subversion allows entries to not explicitly store those two
-        attributes when their values are the same as (in the
-        <structfield>revision</structfield> case) or trivially
-        calculable from
-        <footnote>
-          <para>That is, the URL for the entry is the same as the
-            concatenation of the parent directory's URL and the
-            entry's name.</para>
-        </footnote>
-        (in the <structfield>url</structfield> case) the data stored
-        in the <quote>this directory</quote> entry.  Note also that
-        for subdirectory entries, Subversion stores only the crucial
-        attributes—name, kind, url, revision, and schedule.  In
-        an effort to reduce duplicated information, Subversion
-        dictates that the method for determining the full set of
-        information about a subdirectory is to traverse down into that
-        subdirectory, and read the <quote>this directory</quote> entry
-        from its own <filename>.svn/entries</filename> file.  However,
-        a reference to the subdirectory is kept in its parent's
-        <filename>entries</filename> file, with enough information to
-        permit basic versioning operations in the event that the
-        subdirectory itself is actually missing from disk.</para>
+      <para>就像你能看到的,条目文件本质上是一列条目,每个<sgmltag>entry</sgmltag>标签代表了下面三者之一的事情:工作拷贝目录本身(叫做<quote>本目录</quote>条目,并且<structfield>name</structfield>属性的值为空),工作拷贝目录中的一个文件(通过<structfield>kind</structfield>属性设置为<literal>"file"</literal>来标示),或者是工作拷贝中的一个子目录(<structfield>kind</structfield>这时设置为<literal>"dir"</literal>)。所有在这个文件标记的文件和子目录都是已经纳入版本控制或者是(上面例子中的<filename>zeta</filename>)预定在下次提交加入到版本控制。每个条目都有一个唯一的名字,每个条目有一个kind节点。
+     </para>
+      <para>开发者必须意识到一些Subversion读写<filename>entries</filename>文件的特殊规则,每个条目都有一个修订版本和URL与之关联,注意在上面实例文件中并不是每个<sgmltag>entry</sgmltag>标签都有明确的<structfield>revision</structfield>或<structfield>url</structfield>属性,Subversion允许一些情况不明确的说明这个两个属性,如属性值与<quote>本目录</quote>的值相同(<structfield>revision</structfield>的情况)或者是可以从<quote>本目录</quote>简单计算<footnote>
+          <para>也就是,这个条目的URL就是父目录与名称合并。</para>
+        </footnote>出的来(<structfield>url</structfield>)。注意对于子目录条目,Subversion只保管最重要的信息—名称、类型、URL、修订版本和日程。为了减少重复信息,Subversion指示当要检测目录信息时会跑到这个子目录自己的<filename>.svn/entries</filename>的<quote>本目录</quote>条目。当然了,对这个子目录的引用还是会保存在父目录的<filename>entries</filename>文件,这些信息足以在子目录丢失后执行基本的版本操作。</para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-3.2">
-      <title>Pristine Copies and Property Files</title>
+      <title>原始拷贝和属性文件</title>
+      <para>如我们前面提到的,<filename>.svn</filename>也包含了一些原始的<quote>text-base</quote>文件版本,可以在<filename>.svn/text-base</filename>看到。这些原始文件的好处是多方面的—察看本地修改和区别不需要经过网络访问,减少传递修改时的数据—但是随之而来的代价是每个版本化的文件都在磁盘至少保存两次,现在看来这是对大多数文件可以忽略不计的一个惩罚。但是,当你版本控制的文件增多之后形势会变得很严峻,我们已经注意到了应该可以选择使用<quote>text-base</quote>,但是具有讽刺意味的是,当版本化文件增大时,<quote>text-base</quote>文件的存在会更加重要—谁会希望在提交一个小修改时在网络上传递一个大文件?
+      </para>
-      <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
-        <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, smaller transmission
-        of changes to the server—but comes 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 they want 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.  Each of these
-        property files (<quote>working</quote> and <quote>base</quote>
-        versions) uses a simple <quote>hash-on-disk</quote> file
-        format for storing the property names and values.</para>
+      <para>同<quote>text-base</quote>文件的用途一样的还有属性文件和它们的<quote>prop-base</quote>拷贝,分别位于<filename>.svn/props</filename>和<filename>.svn/prop-base</filename>。因为目录也有属性,所以也有<filename>.svn/dir-props</filename>和<filename>.svn/dir-prop-base</filename>文件。所有的属性文件(<quote>working</quote>和<quote>base</quote>版本)都使用同样的<quote>hash-on-disk</quote>文件格式来排序属性名称和值。</para>
@@ -880,115 +662,39 @@
   <sect1 id="svn-ch-8-sect-4">
-    <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
-      <systemitem
-      class="url">http://www.webdav.org/</systemitem>.</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 WebFolders (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>WebDAV(<quote>Web-based Distributed Authoring
+      and Versioning</quote>的缩写)是一个标准HTTP协议的扩展,把web变成一个可读写的媒体,作为当今基本的只读媒体的替代。原理就是目录和文件时可以共享的—都是可读写的对象—通过web。RFCs2518和3253描述了WebDAV/DeltaV 对于HTTP的扩展,存放于(随之有许多其他有用的信息)<systemitem
+      class="url">http://www.webdav.org/</systemitem>。</para>
+    <para>已经有一些操作系统文件浏览器可以使用WebDAV装配网络目录,在Win32中,Windows浏览器可以像普通共享文件夹一样浏览叫做网络文件夹(只是一个设置好WebDAV的网络位置)的目录,在Mac OS X也有这个能力,就像Nautilus和Konqueror作的(分别对应GNOME和KDE)。
+   </para>
+    <para>这些是如何应用到Subversion中的呢?mod_dav_svn的Apache模块使用HTTP,通过WebDAV和DeltaV扩展,作为它的网络协议之一,Subversion使用mod_dav_svn在Subversion的版本概念和RFCs 2518和3253对应部分建立影射。
-    <para>For a more thorough discussion of WebDAV, how it works, and
-      how Subversion uses it, see <xref linkend="svn-ap-c"/>.  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>
+    <para>关于WebDAV的完全讨论,工作原理和Subversion如何使用,可以看<xref linkend="svn-ap-c"/>。在其他事情中,附录讨论了Subversion与一般的WebDAV规范结合的程度,和这些是如何影响普通WebDAV客户端的交互性。</para>
   <!-- ******************************************************************* -->
   <!-- *** SECTION 5:  PROGRAMMING WITH MEMORY POOLS                   *** -->
   <!-- ******************************************************************* -->
   <sect1 id="svn-ch-8-sect-5">
-    <title>Programming with Memory Pools</title>
+    <title>使用内存池编程</title>
+    <para>几乎每一个使用过C语言的开发者曾经感叹令人畏缩的内存管理,分配足够的内存,并且追踪内存的分配,在不需要时释放内存—这个任务会非常复杂。当然,如果没有正确地做到这一点会导致程序毁掉自己,或者更加严重一点,把电脑搞瘫。幸运的是,Subversion所依赖的APR库为了可携带型提供了<structname>apr_pool_t</structname>类型,代表了应用可以分配内存的池。
+   </para>
-    <para>Almost every developer who has used the C programming
-      language has at some point sighed at the daunting task of
-      managing memory usage.  Allocating enough memory to use, keeping
-      track of those allocations, freeing the memory when you no
-      longer need it—these tasks can be quite complex.  And of
-      course, failure to do those things properly can result in a
-      program that crashes itself, or worse, crashes the computer.
-      Fortunately, the APR library that Subversion depends on for
-      portability provides the <structname>apr_pool_t</structname>
-      type, which represents a pool from which the application may
-      allocate memory.</para>
-    <para>A memory pool is an abstract representation of a chunk of
-      memory allocated for use by a program.  Rather than requesting
-      memory directly from the OS using the standard
-      <function>malloc()</function> and friends, programs that link
-      against APR can simply request that a pool of memory be created
-      (using the <function>apr_pool_create()</function> function).
-      APR will allocate a moderately sized chunk of memory from the
-      OS, and that memory will be instantly available for use by the
-      program.  Any time the program needs some of the pool memory, it
-      uses one of the APR pool API functions, like
-      <function>apr_palloc()</function>, which returns a generic
-      memory location from the pool.  The program can keep requesting
-      bits and pieces of memory from the pool, and APR will keep
-      granting the requests.  Pools will automatically grow in size to
-      accommodate programs that request more memory than the original
-      pool contained, until of course there is no more memory
-      available on the system.</para>
-    <para>Now, if this were the end of the pool story, it would hardly
-      have merited special attention.  Fortunately, that's not the
-      case.  Pools can not only be created; they can also be cleared
-      and destroyed, using <function>apr_pool_clear()</function> and
-      <function>apr_pool_destroy()</function> respectively.  This
-      gives developers the flexibility to allocate several—or
-      several thousand—things from the pool, and then clean up
-      all of that memory with a single function call!  Further, pools
-      have hierarchy.  You can make <quote>subpools</quote> of any
-      previously created pool.  When you clear a pool, all of its
-      subpools are destroyed; if you destroy a pool, it and its
-      subpools are destroyed.</para>
-    <para>Before we go further, developers should be aware that they
-      probably will not find many calls to the APR pool functions we
-      just mentioned in the Subversion source code.  APR pools offer
-      some extensibility mechanisms, like the ability to have custom
-      <quote>user data</quote> attached to the pool, and mechanisms
-      for registering cleanup functions that get called when the pool
-      is destroyed.  Subversion makes use of these extensions in a
-      somewhat non-trivial way.  So, Subversion supplies (and most of
-      its code uses) the wrapper functions
-      <function>svn_pool_create()</function>,
-      <function>svn_pool_clear()</function>, and
-      <function>svn_pool_destroy()</function>.</para>
-    <para>While pools are helpful for basic memory management, the
-      pool construct really shines in looping and recursive scenarios.
-      Since loops are often unbounded in their iterations, and
-      recursions in their depth, memory consumption in these areas of
-      the code can become unpredictable.  Fortunately, using nested
-      memory pools can be a great way to easily manage these
-      potentially hairy situations.  The following example
-      demonstrates the basic use of nested pools in a situation that
-      is fairly common—recursively crawling a directory tree,
-      doing some task to each thing in the tree.</para>
+    <para>一个内存池是程序所需要分配内存的一个抽象表示,不选择使用标准的<function>malloc()</function>从操作系统直接申请内存,而使用向APR申请的池申请创建的(使用<function>apr_pool_create()</function>方法)内存。APR会从操作系统分配合适的内存块这些内存可以立刻在程序里使用,当程序需要更多的池内存时,它会使用APR的池API方法,如<function>apr_palloc()</function>,返回池中的基本内存位置,这个程序可以继续从池中请求内存,在超过最初的池的容量后,APR会自动满足程序的要求扩大池的大小,直到系统没有足够的内存。</para>
+    <para>现在,如果这是池故事的结尾,我们就不应该再作过多的关注,很幸运,不是这个情况。池不可以仅仅被创建;它也可以被清空和销毁,分别使用<function>apr_pool_clear()</function>和<function>apr_pool_destroy()</function>。这给了用户灵活性来分配许多—或者是数千—东西自这个池,然后使用一个命令来清空!更进一步,池由登记,你可以为前一步创建的池创建<quote>子池</quote>。当你清空一个池,所有的子池会被销毁;如果你销毁一个池,它和所有的子池也会被销毁。</para>
+    <para>在我们进一步研究之前,开发者会发现在Subversion源代码中并没有对前面提到的APR池方法有很多的调用,APR提供了许多扩展机制,像使用自定义的附加到池的<quote>用户数据</quote>的能力,注册当池销毁时的所要调用的清理方法的机制,Subversion使用一些不太琐碎的方法来利用这些扩展,所以Subversion提供了(大多数代码使用的)包裹方法<function>svn_pool_create()</function>、<function>svn_pool_clear()</function>和<function>svn_pool_destroy()</function>。</para>
+    <para>尽管池帮助我们基本的内存管理,池的创建确实投射出了循环和迭代场景,因为反复在循环中经常没有界限,在深度迭代中,一定区域的内存消耗变得不可预料,很幸运,使用嵌套的内存池可以简单的管理这种潜在的混乱情形,下面的例子描述了在这个情形下嵌套池的基本使用非常平常—迭代的对目录树的遍历,对树上的每一个部分做一些人物。
+   </para>
     <example id="svn-ch-8-sect-5-ex-1">
-      <title>Effective Pool Usage</title>
+      <title>有效地池使用</title>
 /* Recursively crawl over DIRECTORY, adding the paths of all its file
    children to the FILES array, and doing some task to each path
@@ -1073,27 +779,9 @@
-    <para>The previous example demonstrates effective pool usage in
-      <emphasis>both</emphasis> looping and recursive situations.
-      Each recursion begins by making a subpool of the pool passed to
-      the function.  This subpool is used for the looping region, and
-      cleared with each iteration.  The result is memory usage is
-      roughly proportional to the depth of the recursion, not to total
-      number of file and directories present as children of the
-      top-level directory.  When the first call to this recursive
-      function finally finishes, there is actually very little data
-      stored in the pool that was passed to it.  Now imagine the extra
-      complexity that would be present if this function had to
-      <function>alloc()</function> and <function>free()</function>
-      every single piece of data used!</para>
+    <para>在前一个例子里描述了在循环和迭代情况下有效地池使用,每次迭代会从为传递给池的建立一个子池开始,池在循环区域中使用在每次迭代清理。结果是内存使用比例和深度成比例,而不是顶级目录包含所有的子目录的总数量。当迭代的第一个调用最终结束时,实际上只有很小的传递过来的数据存放在池中,现在想想一下如果在每片数据使用时使用<function>alloc()</function>和<function>free()</function>时会面临的复杂性!</para>
-    <para>Pools might not be ideal for every application, but they are
-      extremely useful in Subversion.  As a Subversion developer,
-      you'll need to grow comfortable with pools and how to wield them
-      correctly.  Memory usage bugs and bloating can be difficult to
-      diagnose and fix regardless of the API, but the pool construct
-      provided by APR has proven a tremendously convenient,
-      time-saving bit of functionality.</para>
+    <para>池并不是对所有的应用是理想的,但是在Subversion中非常有用,作为一个Subversion开发者,你会需要学会适应池并且正确地使用它,内存使用的bug和膨胀可能会非常难于诊断和修正,但是APR提供的pool结构被证明了是非常的方便的,节约时间的功能。</para>
@@ -1101,23 +789,18 @@
   <!-- *** SECTION 6:  CONTRIBUTING TO SUBVERSION                      *** -->
   <!-- ******************************************************************* -->
   <sect1 id="svn-ch-8-sect-6">
-    <title>Contributing to Subversion</title>
+    <title>为Subversion做贡献</title>
-    <para>The official source of information about the Subversion
-      project is, of course, the project's website at <systemitem
-      class="url">http://subversion.tigris.org/</systemitem>.  There
-      you can find information about getting access to the source code
-      and participating on the discussion lists.  The Subversion
-      community always welcomes new members.  If you are
-      interested in participating in this community by contributing
-      changes to the source code, here are some hints on how to get
-      started.</para>
+    <para>Subversion项目的官方信息源当然是项目的网站<systemitem
+      class="url">http://subversion.tigris.org/</systemitem>。这里你可以发现如何得到源代码和参与到讨论列表。Subversion社区一致欢迎新成员,如果你有兴趣通过贡献源代码来参与到社区,以下是一下作为开始的提示。
+     </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-6.1">
-      <title>Join the Community</title>
+      <title>加入社区</title>
-      <para>The first step in community participation is to find a way
+      <para>
+      The first step in community participation is to find a way
         to stay on top of the latest happenings.  To do this most
         effectively, you will want to subscribe to the main developer
         discussion list (<email>dev at subversion.tigris.org</email>) and
@@ -1149,32 +832,16 @@
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-6.2">
-      <title>Get the Source Code</title>
+      <title>取得源代码</title>
-      <para>To edit the code, you need to have the code.  This means
-        you need to check out a working copy from the public
-        Subversion source repository.  As straightforward as that
-        might sound, the task can be slightly tricky.  Because
-        Subversion's source code is versioned using Subversion itself,
-        you actually need to <quote>bootstrap</quote> by getting a
-        working Subversion client via some other method.  The most
-        common methods include downloading the latest binary
-        distribution (if such is available for your platform), or
-        downloading the latest source tarball and building your own
-        Subversion client.  If you build from source, make sure to
-        read the <filename>INSTALL</filename> file in the top level of
-        the source tree for instructions.</para>
-      <para>After you have a working Subversion client, you are now
-        poised to checkout a working copy of the Subversion source
-        repository from <systemitem
-        class="url">http://svn.collab.net/repos/svn/trunk/</systemitem>:
+      <para>为了编辑源代码,你需要得到源代码,这意味着你需要从Subversion源代码版本库检出一个工作拷贝,听起来如此直接,这个任务可能有一点微妙。因为Subversion的源代码使用Subversion本身版本管理,你实际上需要使用别的方法得到工作的Subversion客户端来启动这个过程。最通常的方法是下载最新的二进制分发版本(如果有你的平台的版本存在),或者是下载最新的源程序包并且自己编译Subversion客户端,如果你从源代码编译,确定要阅读源代码顶级目录的<filename>INSTALL</filename>文件作为指导。
+     </para>
+      <para>在你有了工作的Subversion客户端后,你可以泰然自若的从Subversion源代码版本库<systemitem
+        class="url">http://svn.collab.net/repos/svn/trunk/</systemitem>检出一个工作拷贝:
-          <para>Note that the URL checked out in the example above
-            ends not with <literal>svn</literal>, but with a
-            subdirectory thereof called <literal>trunk</literal>.  See
-            our discussion of Subversion's branching and tagging model
-            for the reasoning behind this.</para>
+          <para>注意上面例子中检出的URL并不是以<literal>svn</literal>结尾,而是它的一个叫做<literal>trunk</literal>的子目录,可以看我们对Subversion的分支和标签模型的讨论来理解背后的原因。
+         </para>
@@ -1187,118 +854,48 @@
-      <para>The above command will checkout the bleeding-edge, latest
-        version of the Subversion source code into a subdirectory
-        named <filename>subversion</filename> in your current working
-        directory.  Obviously, you can adjust that last argument as
-        you see fit.  Regardless of what you call the new working copy
-        directory, though, after this operation completes, you will
-        now have the Subversion source code.  Of course, you will
-        still need to fetch a few helper libraries (apr, apr-util,
-        etc.)—see the <filename>INSTALL</filename> file in the
-        top level of the working copy for details.</para>
+      <para>上面的命令会检出一个流血的,最新的Subversion源代码版本到你的叫做<filename>subversion</filename>的当前工作目录。很明显,你可以调整最后的参数改为你需要的。不管你怎么称呼你的新的工作拷贝目录,在操作之后,你现在已经有了Subversion的源代码。当然,你还是需要得到一些帮助库(apr,apr-util等等)—见工作拷贝根目录的<filename>INSTALL</filename>来得到更多细节。
+     </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-6.3">
-      <title>Become Familiar with Community Policies</title>
+      <title>开始熟悉社区政策</title>
-      <para>Now that you have a working copy containing the latest
-        Subversion source code, you will most certainly want to take a
-        cruise through the <filename>HACKING</filename> file in that
-        working copy's top-level directory.  The
-        <filename>HACKING</filename> file contains general
-        instructions for contributing to Subversion, including how to
-        properly format your source code for consistency with the rest
-        of the codebase, how to describe your proposed changes with an
-        effective change log message, how to test your changes, and so
-        on.  Commit privileges on the Subversion source repository are
-        earned—a government by meritocracy.
+      <para>现在你有了包含最新Subversion源代码的工作拷贝,你一定希望来通过工作拷贝顶级目录下的<filename>HACKING</filename>文件来做一次浏览。这个<filename>HACKING</filename>文件包含了如何对Subversion做贡献的说明,包括如何正确地格式化代码与余下的代码基保持一致性,如何使用有效的提交日志描述你的被提议修改,如何测试修改,等等。对Subversion源代码的提交特权是赢得的—被精英所管理。
-          <para>While this may superficially appear as some sort of
-            elitism, this <quote>earn your commit privileges</quote>
-            notion is about efficiency—whether it costs more in
-            time and effort to review and apply someone else's changes
-            that are likely to be safe and useful, versus the
-            potential costs of undoing changes that are
-            dangerous.</para>
+          <para>浅薄的看起来这像是某种高人一等的优越感,<quote>赢得你的提交特权</quote>这个概念关于效率—检查和应用别人的修改是否安全和有用会花费大量的时间和精力,与之相比的是取消危险的代码的潜在代价。</para>
-        The <filename>HACKING</filename> file is an invaluable
-        resource when it comes to making sure that your proposed
-        changes earn the praises they deserve without being rejected
-        on technicalities.</para>
+        <filename>HACKING</filename>文件是一个无价的资源,当它来确定你被提议作的修改取得了赞美表示它们值得不会被学术性拒绝。</para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-6.4">
-      <title>Make and Test Your Changes</title>
+      <title>作出修改并测试</title>
-      <para>With the code and community policy understanding in hand,
-        you are ready to make your changes.  It is best to try to make
-        smaller but related sets of changes, even tackling larger
-        tasks in stages, instead of making huge, sweeping
-        modifications.  Your proposed changes will be easier to
-        understand (and therefore easier to review) if you disturb
-        the fewest lines of code possible to accomplish your task
-        properly.  After making each set of proposed changes, your
-        Subversion tree should be in a state in which the software
-        compiles with no warnings.</para>
+      <para>当理解了代码和社区政策,你已经准备好了作出修改,最好是努力作出小的但是相关的修改,即使在处理大的任务阶段,不要选择作出巨大的扫除试的修改。如果你搞乱最少的代码来完成修改,你被提议的修改就会很容易理解(而且因此应该很容易去审核)。当完成了每个提议的修改集,你的Subversion树一定要处于编译无警告的状态。</para>
-      <para>Subversion has a fairly thorough
+      <para>Subversion有一个相当彻底
-          <para>You might want to grab some popcorn.
-            <quote>Thorough</quote>, in this instance, translates to
-            somewhere in the neighborhood of thirty minutes of
-            non-interactive machine churn.</para>
+          <para>你或许希望抓一些爆米花,在这个情况下,在附近花三十分钟转一下,渡过非交互的机器活动。***</para>
-        regression test suite, and your proposed changes are expected
-        to not cause any of those tests to fail.  By running
-        <command>make check</command> (in Unix) from the top of the
-        source tree, you can sanity-check your changes.  The fastest
-        way to get your code contributions rejected (other than
-        failing to supply a good log message) is to submit changes
-        that cause failure in the test suite.</para>
+        的回归测试套件,你提议的修改期望不会带来任何这种测试失败,通过在源代码根目录运行<command>make check</command>(在Unix)你可以完全测试你的修改。提交会导致测试套间失败的代码是拒绝(或者是提供一个好的日志信息)你贡献的代码的最快方法。</para>
       <!-- ### TODO: Describe building and testing on Windows. -->
-      <para>In the best-case scenario, you will have actually added
-        appropriate tests to that test suite which verify that your
-        proposed changes work as expected.  In fact,
-        sometimes the best contribution a person can make is solely
-        the addition of new tests.  You can write regression tests for
-        functionality that currently works in Subversion as a way to
-        protect against future changes that might trigger failure in
-        those areas.  Also, you can write new tests that demonstrate
-        known failures.  For this purpose, the Subversion test suite
-        allows you to specify that a given test is expected to fail
-        (called an <literal>XFAIL</literal>), and so long as
-        Subversion fails in the way that was expected, a test result
-        of <literal>XFAIL</literal> itself is considered a success.
-        Ultimately, the better the test suite, the less time wasted on
-        diagnosing potentially obscure regression bugs.</para>
+      <para>在最好的情况下,你实际上应该添加适当的测试到测试套件来验证你提议的修改工作正常,实际上,有时候一个人可以做到的最好贡献就是让添加的测试能够独立起来。你可以添加回归测试来保护当前工作的代码在将来修改时这个区域里不会触发失败。另外,你也可以写测试来描述已知的失败,为了这个目的,Subversion测试套件允许你指定一个给定的测试是期望会失败的(叫做<literal>XFAIL</literal>),而且只要Subversion按照预期失败,一个<literal>XFAIL</literal>测试会认为是一个成功。最后,测试组件越好,就会花费更少的时间来诊断潜在晦涩回归bug。
+     </para>
     <!-- ***************************************************************** -->
     <sect2 id="svn-ch-8-sect-6.5">
-      <title>Donate Your Changes</title>
+      <title>捐赠你的修改</title>
-      <para>After making your modifications to the source code,
-        compose a clear and concise log message to describe those
-        changes and the reasons for them.  Then, send an email to the
-        developers list containing your log message and the output of
-        <command>svn diff</command> (from the top of your Subversion
-        working copy).  If the community members consider your changes
-        acceptable, someone who has commit privileges (permission to
-        make new revisions in the Subversion source repository) will
-        add your changes to the public source code tree.  Recall that
-        permission to directly commit changes to the repository is
-        granted on merit—if you demonstrate comprehension of
-        Subversion, programming competency, and a <quote>team
-        spirit</quote>, you will likely be awarded that
-        permission.</para>
+      <para>当完成了对源代码的修改,写一个干净的和细致的日志信息来描述那些修改和原因。然后,发送一个包含日志信息和<command>svn diff</command>(在Subversion工作拷贝顶级目录运行)输出的邮件到开发者列表。如果社区成员认为你的修改可以接受,一些有提交权限(允许在Subversion源代码版本库提交新的修订版本)的用户会添加你的新的修改到公共源代码树。回想对版本库直接的提交权限是赋予那些展现能力的人—如果你展示了对Subversion的理解,编程能力,和<quote>团队精神</quote>,你会很可能授予那个权限。</para>

More information about the svnbook-dev mailing list