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