Ben's review of chapter 8
Ben Collins-Sussman
sussman at red-bean.com
Sun Feb 25 23:04:37 CST 2007
* Broad general comments:
* Whenever a library is mentioned by name in a paragraph, should we
use <literal> or something? Because we tend to do that for
mod_dav_svn in other chapters. I wonder if it would make the
library name stand out better as well.
* Can we show the 10,000 foot diagram at the beginning of the
chapter? I've always thought of that diagram as less about
traffic flow, and more about library layers. I think it would go
perfectly with the opening table of libraries.
* We have a nice explanation about how users should 'read the header
files' to learn how to use the APIs, but we should also explicitly
point them to our HACKING file, which has critical bits of info
like how to use pools correctly, how to throw svn_error_t's, etc.
* Nitpicky suggestions:
* Intro
"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." --> let's put perl in this list too, to
be fair, since it gets at least as much use as the python and java
bindings. ("cult of svk!")
* Layered Library Design
Maybe the initial table of libraries would look better as a
<variablelist>? A bit more conversational and relaxed? It seems
like tables are only really useful when you more than 2 columns.
* Repository Layer
"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."
--> Needs some rewording.
* when you read the sentence, it kinda sounds like you're
saying Google "did just this" -- implemented an ODBC
backend. Maybe change to "did something like this"?
* the service is actually called either "Google Code
Project Hosting" or the "project hosting service on
Google Code".
* put 'ultra-scalable' before 'Bigtable'
* Repository Access Layer
"Charged with marshalling data" --> that's the U.K. spelling.
U.S. spelling is 'marshaling'.
"libsvn_ra_svn speaks a proprietary network protocol with the
svnserve program" --> 'proprietary' sounds like it's
closed-source or a trade secret or something, maybe use 'custom'
or 'private', like we do elsewhere in the book?
* Client Layer
We say that the svn source code has a 'standard' commandline
client to examine, but I think it would be great to explicitly
point out the existence of minimal-client.c. It's a heck of a
lot easier to learn from, and we point newbies to it all the
time.
* Sidebar: "Binding Directly"
We should also point out that wrapping a commandline client is
fragile -- if the output changes slightly between versions, the
wrapper breaks easily. If they use the APIs, then things will
never break. (After an upgrade, you may be using deprecated
APIs, but at least they'll still work!)
* The APR Library
Put 'apr_pool_t' in <literal> or something, just like we do with
'apr_foo()' functions?
Also, can we add a brief explanation of what memory pools are,
and why they're a nice thing? Most coders haven't seen such
things before -- they only know malloc/free, or depend on garbage
collection. Pools live in that rare in-between world.
* Python code: nice job, dude. It's great to see the pool stuff
*gone* from the sample python code.
More information about the svnbook-dev
mailing list