[SvnBook] #64: [PATCH] Hanchrow review [ch7:ch8]
SvnBook
noreply at red-bean.com
Fri Aug 10 21:08:42 CDT 2007
#64: [PATCH] Hanchrow review [ch7:ch8]
-------------------------+--------------------------------------------------
Reporter: cmpilato | Owner: nobody
Type: enhancement | Status: new
Priority: normal | Milestone: 1.5
Component: content | Version: nightly/trunk
Keywords: |
-------------------------+--------------------------------------------------
From: Eric Hanchrow <offby1 at blarg.net>
{{{
Index: ch07-customizing-svn.xml
===================================================================
--- ch07-customizing-svn.xml (revision 2737)
+++ ch07-customizing-svn.xml (working copy)
@@ -19,7 +19,7 @@
controlled by the user. Many of these options are of the kind
that a user would wish to apply to all Subversion operations.
So, rather than forcing users to remember command-line arguments
- for specifying these options, and to use them for each and every
+ for specifying these options, and to use them for every
operation they perform, Subversion uses configuration files,
segregated into a Subversion configuration area.</para>
@@ -128,10 +128,11 @@
</para>
<para>Registry-based configuration options are parsed
- <emphasis>before</emphasis> their file-based counterparts,
- so are overridden by values found in the configuration
- files. In other words, configuration priority is granted in
- the following order on a Windows system:</para>
+ <emphasis>before</emphasis> their file-based counterparts, so
+ are overridden by values found in the configuration files. In
+ other words, subversion looks for configuration information in
+ the following locations on a Windows system; lower-numbered
+ locations take precedence over higher-numbered locations:</para>
<orderedlist>
<listitem>
@@ -321,7 +322,7 @@
<para>This specifies the amount of time, in seconds, to
wait for a server response. If you experience
problems with a slow network connection causing
- Subversion operations to timeout, you should increase
+ Subversion operations to time out, you should increase
the value of this option. The default value is
<literal>0</literal>, which instructs the underlying
HTTP library, Neon, to use its default timeout
@@ -405,7 +406,7 @@
<para>The <filename>config</filename> file contains the rest
of the currently available Subversion run-time options,
those not related to networking. There are only a few
- options in use at this time, but they are again grouped into
+ options in use as of this writing, but they are again grouped
into
sections in expectation of future additions.</para>
<para>The <literal>auth</literal> section contains settings
@@ -463,7 +464,8 @@
in the editor program (see <xref
linkend="svn.advanced.props" />). This option's default
value is empty. The order of priority for determining
the
- editor command is:</para>
+ editor command (again, lower-numbered
+ locations take precedence over higher-numbered locations)
is:</para>
<orderedlist>
<listitem>
<para>Command-line option <literal>--editor-
cmd</literal></para>
@@ -499,7 +501,10 @@
<para>This specifies the absolute path of a differencing
program, used when Subversion generates
<quote>diff</quote> output (such as when using the
- <command>svn diff</command> command). By default
+ <command>svn diff</command> command).
+ <!-- are the other times when subversion consults this
+ - such as "merge"? That would be important to know -->
+ By default
Subversion uses an internal differencing
library—setting this option will cause it to
perform this task using an external program. See
@@ -686,6 +691,9 @@
in which programs present data to the user, as well as the way
in which they accept user input.</para>
+ <!-- I'm fairly sure that some Unix-like systems don't, by
+ default, have a "locale" command installed. So perhaps we
+ should say "On most Unix-like systems ..." -->
<para>On Unix-like systems, you can check the values of the
locale-related runtime configuration options by running the
<command>locale</command> command:</para>
@@ -920,16 +928,16 @@
<para>Subversion calls external diff programs with parameters
suitable for the GNU diff utility, and expects only that the
external program return with a successful error code. For
- most alternative diff program, only the sixth and seventh
- arguments, the paths of the files which represent the left and
- right sides of the diff, respectively, are of interest. Note
+ most alternative diff programs, only the sixth and seventh
+ arguments—the paths of the files which represent the left
and
+ right sides of the diff, respectively—are of interest.
Note
that Subversion runs the diff program once per modified file
covered by the Subversion operation, so if your program runs
in an asynchronous fashion (or <quote>backgrounded</quote>),
you might have several instances of it all running
simultaneously. Finally, Subversion expects that your program
- return an errorcode of 1 if your program detected differences,
- or 0 if it did not—any other errorcode is considered a
+ return an error code of 1 if your program detected differences,
+ or 0 if it did not—any other error code is considered a
fatal error.
<footnote>
<para>The GNU diff manual page puts it this way: <quote>An
@@ -1007,8 +1015,8 @@
depends on the output of your merge program, you wrapper
script must not exit before that output has been delivered to
Subversion. When it finally does exit, it should return an
- errorcode of 0 if the merge was successful, or 1 if unresolved
- conflicts remain in the output—any other errorcode is
+ error code of 0 if the merge was successful, or 1 if unresolved
+ conflicts remain in the output—any other error code is
considered a fatal error.</para>
<para><xref linkend="svn.advanced.externaldifftools.diff3.ex-1"/>
Index: ch08-embedding-svn.xml
===================================================================
--- ch08-embedding-svn.xml (revision 2737)
+++ ch08-embedding-svn.xml (working copy)
@@ -1,8 +1,8 @@
<chapter id="svn.developer">
<title>Embedding Subversion</title>
- <para>Subversion has a modular design, written in C and implemented
- as a collection of libraries. Each library has a well-defined
+ <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), and that
interface is available not only for Subversion itself to use, but
for any software that wishes to embed or otherwise
@@ -31,7 +31,8 @@
<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. We will
+ Repository Access (RA) Layer, or the Client Layer (see <xref
+ linkend="svn.intro.architecture.dia-1" />). 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
@@ -119,6 +120,8 @@
</varlistentry>
</variablelist>
+ <!-- yeah, but you seem to be using the word "commons"
+ synonymously :-) -->
<para>The fact that the word <quote>miscellaneous</quote> only
appears once in the previous list is a good sign. The
Subversion development team is serious about making sure that
@@ -187,7 +190,7 @@
back-end database systems, perhaps through a mechanism such as
Open Database Connectivity (ODBC). In fact, Google did
something similar to this before launching the Google Code
- Project Hosting service, announcing in mid-2006 that members
+ Project Hosting service: they announced in mid-2006 that members
of its Open Source team had written a new proprietary
Subversion filesystem plugin which used their ultra-scalable
Bigtable database for its storage.</para>
@@ -272,8 +275,8 @@
</sidebar>
<para>Most of the functionality provided by the filesystem
- interface is the result of an action that occurs on a
- filesystem path. That is, from outside of the filesystem, the
+ interface deals with actions that occur on individual
+ filesystem paths. That is, from outside of the filesystem, the
primary mechanism for describing and accessing the individual
revisions of files and directories comes through the use of
path strings like <filename>/foo/bar</filename>, just as if
@@ -296,9 +299,9 @@
<graphic fileref="images/ch08dia1.png"/>
</figure>
- <para>The different here is that the Subversion filesystem has a
+ <para>The difference here is that the Subversion filesystem has a
nifty third dimension that most filesystems do not
- have—Time!
+ have—time!
<footnote>
<para>We understand that this may come as a shock to sci-fi
fans who have long been under the impression that Time was
@@ -354,7 +357,7 @@
other important utilities to Subversion. These include the
abilities to:</para>
- <orderedlist>
+ <itemizedlist>
<listitem>
<para>create, open, destroy, and perform recovery steps on a
Subversion repository and the filesystem included in that
@@ -378,7 +381,7 @@
<para>parse that dump format, loading the dumped revisions
into a different Subversion repository.</para>
</listitem>
- </orderedlist>
+ </itemizedlist>
<para>As Subversion continues to evolve, the repository library
will grow with the filesystem library to offer increased
@@ -398,12 +401,18 @@
(which currently includes libsvn_ra_dav, libsvn_ra_local,
libsvn_ra_serf, and libsvn_ra_svn), and any additional
libraries needed by one or more of those RA modules, such as
+ <!-- I simply cannot parse this clause -->
the mod_dav_svn Apache module with which libsvn_ra_dav
communicates or libsvn_ra_svn's server,
<command>svnserve</command>.</para>
<para>Since Subversion uses URLs to identify its repository
resources, the protocol portion of the URL schema (usually
+ <!-- why omit svn+ssh here? I'd suggest we either list
+ _every_ schema we're aware of, or else, list far fewer, so
+ that the list is clearly intended to be incomplete. But this
+ _almost-complete_ list immediately makes me wonder why svn+ssh
+ is missing. -->
<literal>file://</literal>, <literal>http://</literal>,
<literal>https://</literal>, or <literal>svn://</literal>) is
used
to determine which RA module will handle the communications.
@@ -521,7 +530,7 @@
<para>Why should your GUI program bind directly with a
libsvn_client instead of acting as a wrapper around a
command-line program? Besides simply being more efficient,
- this can address potential correctness issues as well. A
+ it can be more correct as well. A
command-line program (like the one supplied with Subversion)
that binds to the client library needs to effectively
translate feedback and requested data bits from C types to
@@ -529,6 +538,10 @@
translation can be lossy. That is, the program may not
display all of the information harvested from the API, or
may combine bits of information for compact
representation.</para>
+ <!-- I swear I read somewhere that the output of the
+ command-line programs was carefully designed to be both
+ human- and machine-readable, which implies that it is also
+ complete and correct. Is this no longer the case? -->
<para>If you wrap such a command-line program with yet another
program, the second program has access only to
@@ -594,13 +607,12 @@
<para>The Subversion working copy administration area's layout and
contents are considered implementation details not really
intended for human consumption. Developers are encouraged to
- use Subversion's public APIs or provided tools to access and
- manipulate the working copy data, as opposed to directly reading
- or modifying the files of which the working copy administrative
- area is comprised. The file formats employed by the working
+ use Subversion's public APIs, or the tools that Subversion
provides, to access and
+ manipulate the working copy data, instead of directly reading
+ or modifying those files. The file formats employed by the working
copy library for its administrative data do change from time to
time—a fact that the public APIs do a great job of
- successfully hiding from the average user. In this section, we
+ hiding from the average user. In this section, we
expose some of these implementation details sheerly to appease
your overwhelming curiousity.</para>
@@ -610,9 +622,9 @@
<para>Perhaps the single most important file in the
<filename>.svn</filename> directory is the
- <filename>entries</filename> file. The entries file is a
- single file which contains the bulk of the administrative
- information about a versioned item in a working copy
+ <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 which tracks the repository
URLs, pristine revision, file checksums, pristine text and
property timestamps, scheduling and conflict state
@@ -640,6 +652,11 @@
makes upgrading from one working copy format to another a
breeze—it reads the old formats, and writes the
new.</para>
+ <!-- that mention of upgrading is a bit tantalizing; there's a
+ lot more to be said (such as: version 1.4 clients silently
+ upgrade wcs made by older clients). Is it worth mentioning
+ anything more? If not, is it then even worth keeping this
+ tantalizing sentence? -->
</sect2>
@@ -647,13 +664,14 @@
<sect2 id="svn.developer.insidewc.base-and-props">
<title>Pristine Copies and Property Files</title>
+ <!-- actually, I don't believe we _did_ mention this before. -->
<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
+ reversion of modified or missing files, more efficient
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.
@@ -677,6 +695,9 @@
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>
+ <!-- is this "hash-on-disk" format somehow different from the
+ format of the text-base file? If so, how? If not, or if the
+ difference isn't worth explaining, why mention it? -->
</sect2>
@@ -691,8 +712,12 @@
<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 tree.
+ <!-- that last sentence, about header files, would probably
+ confuse me if I weren't a C programmer. Ought we assume that
+ the reader is in fact a C programmer? -->
+ These headers are copied into your system
+ locations (for example, <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
@@ -702,7 +727,7 @@
<para>When examining the public header files, the first thing you
might notice is that Subversion's datatypes and functions are
- namespace protected. Every public Subversion symbol name begins
+ namespace protected. That is, 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>,
@@ -748,10 +773,13 @@
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.
+ 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 the server does. Currently this list includes
+ anywhere that the server does.
+ <!-- didn't you mean to say "... anywhere that Apache itself
does"?
+ That's equally true, and more impressive. -->
+ 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
@@ -762,18 +790,18 @@
</footnote>
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
+ uses these types extensively. But
perhaps the most pervasive APR datatype, found in nearly every
Subversion API prototype, is the
<structname>apr_pool_t</structname>—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),
+ management schema for data passed through its API), <!--
"scheme", maybe? -->
<footnote>
<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 are required to provide
+ not required to do the same, they <emphasis>are</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> to initialize the
@@ -792,7 +820,7 @@
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,
+ can result in a program that aborts, or worse,
crashes the computer.</para>
<para>Higher-level languages, on the other hand, take the job of
@@ -802,7 +830,7 @@
doing extremely tight program optimization.</para>
</footnote>
Languages like Java and Python use <firstterm>garbage
- collection</firstterm> principles, allocating memory for
+ collection</firstterm>, allocating memory for
objects when needed, and automatically freeing that memory
when the object is no longer in use.</para>
@@ -814,9 +842,9 @@
friends to allocate enough memory for a given object, you
ask APR to allocate the memory from a memory pool. When
you're finished using the objects you've created in the
- pool, you destroy the pool, effectively de-allocating the
- memory consumed by the objects you allocated from it.
- Rather than keeping track of individual objects which need
+ pool, you destroy the entire pool, effectively de-allocating
the
+ memory consumed by <emphasis>all</emphasis> the objects you
allocated from it.
+ Thus, rather than keeping track of individual objects which
need
to be de-allocated, your program simply considers the
general lifetimes of those objects, and allocates the
objects in a pool whose lifetime (the time between the
@@ -866,9 +894,10 @@
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
+ <!-- perhaps link to http://www.swig.org/ here? -->
SWIG bindings for Subversion are located in
- <filename>subversion/bindings/swig</filename> and whilst still
- maturing, they are in a usable state. These bindings allow you
+ <filename>subversion/bindings/swig</filename>. They are still
+ maturing, but they are usable. 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>
@@ -876,16 +905,33 @@
<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
+ flexible and easy to use than C or C++.
+
+ <!-- input validation is a strange example to demonstrate why
+ Python or Perl is better than C or Cplusplus. Maybe we should
punt,
+ and assume that our reader either already knows the benefits
+ of such languages, or else wouldn't understand them even if we
+ were to explain them. -->
+ 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,
+ to handle that misinformation more gracefully.
+
+ <!-- I'm not even sure that previous statement is true - are
+ you saying, roughly, Python and Perl have better error
+ handling than C or C++? -->
+
+ 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>
+ <!-- I'm leaning towards losing this entire paragraph, on the
+ principle that if our reader doesn't know why Perl or Python
+ might be better than C or C++, it would take too long to
+ explain. -->
<para>Unfortunately, Subversion's language bindings tend to lack
the level of developer attention given to the core Subversion
@@ -900,6 +946,14 @@
translating between languages. For more information on SWIG
itself, see the project's website at <ulink
url="http://www.swig.org/"/>.</para>
+ <!-- yikes. Now you've told me that the bindings are not
+ trustworthy, or something. I'm left mystified: are they worth
+ using, or not? Perhaps we should give our reader some way of
+ verifying for themselves how well a particular language
+ binding works - perhaps point them to the unit tests, and say
+ "these tests are guaranteed to pass in all released versions
+ of Subversion; if they seem to cover the functionality that
+ you need, then you'll have no trouble using that language" -->
</sect2>
@@ -924,6 +978,9 @@
<example id="svn.developer.layerlib.repos.ex-1">
<title>Using the Repository Layer</title>
+ <!-- the word "consumed" in the comment is new to me. Does
+ "errors must be consumed" simply mean "you gotta call
+ svn_error_clear"? If so, please say so. -->
<programlisting>
/* Convert a Subversion error into a simple boolean error code.
*
@@ -1025,6 +1082,8 @@
INT_ERR(err);
}
</programlisting>
+ <!-- now I remember why I no longer program in C if I can
+ avoid it :-| -->
</example>
<para>Note that in <xref
@@ -1037,7 +1096,7 @@
time you commit a transaction (like, for example, sending an
email that describes all the changes made in that transaction
to your developer mailing list), you need to use the
- libsvn_repos-wrapped version of that function was adds the
+ libsvn_repos-wrapped version of that function, because it adds
the
hook triggering functionality—in this case,
<function>svn_repos_fs_commit_txn()</function>. (For more
information regarding Subversion's repository hooks, see <xref
}}}
--
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/64>
SvnBook <http://svnbook.red-bean.com/>
More information about the svnbook-dev
mailing list