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