Review of fitz's chapter 2

[Ben Collins-Sussman]

* Help!

Suggestion: can you show an example of someone actually running some
sort of 'svn help subcommand'?  It would make the chapter feel more
consistent.  Throughout the chapter (and the book, really), we always
explain what a subcommand does, then show a demonstration of it.


* svn import

It's good that you point out that the original import tree is not
automatically converted to a working copy, since a lot of newbies
assume that.  I've always wished, though, that we could describe the
'in place import' trick somewhere in the book.  It seems like TMI to
do that right at the beginning of the tour chapter here, but maybe we
can put it somewhere else in the book, some sort of 'tips & tricks'
section, and then make an xref to it here?  (Maybe the 'tips & tricks'
section could be at the end of the chapter, or in the 'advanced
topics' chapter?)

* Recommended repository layout.

I like how this section ends with links to sections about detailed
repository-layout planning.  But what worries me is that the section
says one should create /branches and /tags "to contain branch and tag
copies".  At this point in the book, the user has never even *seen*
the word "branch" or "tag".  Those terms might be utterly meaningless
at this point.  Can we at least point them to explanation of those
words, something like, "(you'll learn more about branches and tags in
chapter 4...)"?

* What's in a Name?

At the end of this sidebar, there's a brief mention of the
auto-URL-escaping feature.  Is that explained in more detail elsewhere
in the book?  If so, can we link to it?  If not, can we show an
example of how it works?  We should be showing users how put URLs in
quotes for auto-escaping to kick in:

       svn co "http://host/dir with space/file"


* "Since Subversion uses a 'copy-modify-merge' model instead of
   'lock-modify-unlock' (see Chapter 1, Fundamental Concepts),"

    Let's make this xref actually point to the 'versioning models'
    section in chapter 1, rather than the top of chapter 1.


* Note: While your working copy is "just like any other collection of
  files and directories on your system"...

  At the moment this note-section says "don't forget to tell svn about
  copies and moves".  But this is incomplete -- you need to tell svn
  about adds and deletes too.  My feeling is that there's a much, much
  simpler way to explain this critical idea: "you can edit files at
  will, but you must tell svn about *everything else* you do."  That's
  a much easier way to remember the rules, and I've used it many times
  in the #svn channel.

  I'm also confused, because further down in the chapter, in the "Make
  Changes to Your Working Copy" section, there's a warning-sidebar
  that seems to reiterate this same idea.  I'm detecting redundancy...


* "That will place your working copy in a directory named subv instead
  of a directory named trunk as we did previously."

  Also, point out that the directory will be created if it doesn't
  already exist.

* "or whatever tool you wulrd normally use" --- typo.

* "See an overview of your changes" section:

   A bunch of 'svn status' examples are using --verbose and
   --show-updates options.  Given our new HACKING rules, can we
   change those to -v and -u, like what real users actually type?  :-)

   (I know we need to go through the whole book and consistify, but
   these really stand out as awkward to me.)

* "Examine the details of your local modifications" section:

   There's a footnote explaining how to use external diff command.
   It's a really big footnote with meaty information, and it's
   answering a really common newbie question.  I'd suggest converting
   the footnote into a normal paragraph in this 'diff' section... it's
   too important to be an 'aside'.

* "Undoing Working Changes" section:

   First sentence should have 'svn diff' in <command>, not in quotes.

* Best line EVAR:  "you can't get sauerkraut from an Italian deli" :-)

* "Examining History" section:

   There's a table giving brief descriptions of each history command
   -- for 'svn diff', it says that it shows "details of how a file
   changed over time".  I think that's too specific, and not quite
   accurate, since it's not always used on single files.  Maybe a
   better wording would be "shows line-level details of a particular
   change"?

* "Comparing repository to repository" section;

  Instead of the stilted "svn diff --revision 2:3" example, how about
  the hot new "svn diff -c 3"?  (There's also a --revision 4:5 example
  that can be replaced.)  This is a great opportunity to introduce the
  -c switch and explain how it relates to the -r switch.  I'm using -c
  a lot now in the branching/merging chapter, so this would set us up
  really nicely.

* "Fetching older repository snapshots" section:

  A lot of newbies learn about 'svn up -r X', and assume that's the
  proper way to 'undo' changes.  We need an explanation in here that
  one *cannot* commit changes that come from backdated working
  copies.  Put a xref pointer to the 'undoing changes' section in
  chapter 4.


* Footnote #5 has a stray '>' at the end of it?