Ben's review of chapter 8
C. Michael Pilato
cmpilato at red-bean.com
Tue Feb 27 01:17:58 CST 2007
Ben Collins-Sussman wrote:
> * 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.
I intentionally chose not to do this long ago because the text says that
we'll be referring to the libraries by their extension-less Unix
filenames. I felt like that gave me the flexibility to not constantly
wrap them in "literal" or "filename" tags. (Technically, I probably
should be referring to them like svn_wc and svn_client, but I think our
Unix-default audience would respond better to having the "lib" prefix there.
> * 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.
I considered it (and it used to be there, actually), but I think it's
far too useful a diagram to have buried in a chapter written solely for
folks developing against Subversion APIs, don't you? I don't like it's
placement in the preface either, for that matter. I was hoping to move
it to the fundamental concepts chapter as part of our re-working of
that, showing how Subversion does version control.
Let's leave it alone for now and revisit this when we have a chance to
step back from a mostly-finished book and take a wide-angle look at the
thing.
> * 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.
+1
> * 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!")
Yep. And actually, I think the Ruby bindings are useful, too. I'll add
both.
> * 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.
Sure, I can give that shot.
> * 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'
+1. (By the way, I asked Fitz about the official name of that service,
but his response was something different, like "Project Hosting at
Google Code" -- something that just didn't flow well.)
> * Repository Access Layer
>
> "Charged with marshalling data" --> that's the U.K. spelling.
> U.S. spelling is 'marshaling'.
Oops. Yep.
> "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?
+1
> * 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.
Ok. (Note to self, it's at "tools/examples/minimal_client.c")
> * 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!)
Don't I do this already? Oh, you mean explicitly point out our compat
guarantees for APIs. Good. +1
> * The APR Library
>
> Put 'apr_pool_t' in <literal> or something, just like we do with
> 'apr_foo()' functions?
It's in <structname> tags, but renders boringly. I'll fix the stylesheet.
> 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.
Sure.
--
C. Michael Pilato <cmpilato at red-bean.com>
"The Christian ideal has not been tried and found wanting. It has
been found difficult; and left untried." -- G. K. Chesterton
More information about the svnbook-dev
mailing list