ch03 review

[Ben Collins-Sussman]

Holy Moly, ch03 is LONG.  Great job, Mike!  Things are so much better
expanded and clarified now.  Here are all the problems I saw as I read
over it.

---------------------

"It has other bits of functionality that extend beyond basic file and
directory versioning; beyond just sending and receiving changes to and
from a central repository."

I think the use of a semicolon there is awkward.  I was taught that
semicolons always separate two wholly complete sentences.   I think if
I heard you speak that text and I were transcribing, I'd just write a
comma.

-------------

"Peg and Operative Revisions"


Throughout this section, you use the term 'resource' many times times.
I think it's too jargon-y.  We've all had our heads steeped in DAV
terminology for too many years, so we don't notice.... but I'm pretty
sure that you walked up to a new svn user and said, "so, is that
resource under version control?", they'd wonder what you meant by
'resource'.  I'd just use the phrase "object" or something, which
*does* make sense to a regular person.

---------

Sidebar:  "The Peg Revision Algorithm"

Kill the word 'basically' in the first sentence, it doesn't add any
extra meaning.

------------

"Manipulating Properties" --> Tip Sidebar


You recommend using 'svn propedit' in the tip sidebar, because it
allows users to see what they're overwriting.  I would also mention
that it's also a best practice for setting properties with multi-line
values.  (I can't tell you how often people get stuck trying to figure
out how to set svn:externals!)

-----------------


"Auto-prop support is perhaps the handiest property related tool in
the Subversion toolbox"

You've mentioned the phrase 'automatic property setting feature' a few
sentences back, but 'auto-prop' sounds like undefined jargon.  Either
expand the jargon, or define it at the beginning of the paragraph.


---------------------

"Subversion's command-line programs almost universally behave
identically across all those systems.

Too many adverbs?  "almost universally behave identically" sounds
awkward to me.  Maybe just strike 'almost universally'?  I think that
saying command-line programs "behave identically" across systems is
the simplest idea being communicated here.  Or, if you want to say
that it's not perfect, then maybe the phrase "behave almost
identically".

------------------

"and are not intended to be, themselved versioned."

Typo -- 'themselved'->'themselves'.  Maybe just strike that word
completely?  It's smoother to say '[there] are other files and
directories which are not, and are not intended to be, versioned'.  Or
even better:  '[there] are other files and directories which are not
versioned, nor intended to be.'.

-----------------------

"The Subversion runtime configuration system provides an option,
global-ignores, whose value is a whitespace-delimited collection of
file patterns (or globs)."

I think you need a xref to the relevant section on runtime
config... it's not been discussed yet in the book.

------------------------

Sidebar:  "Keywords and Spurious Differences"

You know what?   I think this whole sidebar is TMI.  I've never heard
a user ask about this problem, or 'predict' that keywords would cause
flip-flopping diffs on each commit.  This sidebar is answerinng a
question that never gets asked, and doing it by explaining boring
implementation details.

However, I *DO* think we need a new sidebar in its place -- somewhere
in the svn:keywords section, at least.  A really, really common FAQ
are new users asking "why isn't there a keyword for the global
repository rev?"  Turns out that they want to use the gloabl rev as
some sort of embedded build-number, and so our stock reply is to 'use
svnversion, that's what it's good for.'   (Of course, there's also a
technical reason we don't have $GlobalRev$, and that's because we'd
have to do insane keyword-substitution-hunting on the ENTIRE working
copy after every commit... eesh, that would suck.)

I beg of you:  replace this sidebar with a $GlobalRev$ sidebar!

-------------------


"Subversion's copy-modify-merge version control model lives and dies by
the granularity of the data merging algorithms employed when trying to
resolve conflicts caused by multiple users modifying the same file
concurrently."

Feels like a run-on sentence.  I mean, it's probably not *technically*
one -- like, it could probably be diagrammed and everything -- but it
really confused me and I had to read it 3 times.  Break it up into 2
sentences or something.


---------------------

"...which is similar to the reserved checkouts mechanisms of other
version control systems."

Put 'reserved checkouts' in quotes or something, since it's version
control terminology, and slang used by other software we're not even
covering!


----------------

"Serializing access to a versioned resource":

"Serializing access to a versioned resource: But allowing a user to
programmatically claim the exclusive right to change to a file in the
repository, that user can be reasonably confident that energy invested
on unmergeable changes won't be wasted; that his commit of those
changes will succeed."


1. Again, s/versioned resource/object|file

2. s/But/By

3. the semicolon thing again, not separating two complete sentences.
   I think you just want an — instead.


---------------

'Creating Locks' section

The examples all have prompts of "[harry]$"  Why are breaking our "$"
convention only in this one section of this one chapter?  Don't we
show Harry and Sally doing different things in other chapters?  Is
there really a problem of disambiguation between Harry and Sally's
actions here, given all the surrounding explanations?

------------

In Externals section: "possibly a particular revision - of a versioned
resource."

Purty please, use 'versioned object', or something.


------------

Externals section:

Again, can we add a new 'tip' sidebar that specifically *recommends*
using 'svn propedit' to set svn:externals?  Merely saying "you can use
'svn propset' or 'svn propedit' to modify" isn't strong
enough... people don't notice it and then come whining in #svn.

---------------

Externals section:

The penultimate paragraph talks about /trunk and 'svn copy' and
branches and such, and we've not yet covered those topics.  :-(   Not
sure what we can do about this...