Review of fitz's chapter 2

[Brian W. Fitzpatrick]

On 2/25/07, Ben Collins-Sussman <sussman at red-bean.com> wrote:
> * 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.

Done.

> * 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?)

I agree that I'd like to see it in the book somewhere, but this is
definitely not the place.

> * 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...)"?

Done.

> * 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"

It's in chapter 8 under "URL and Path Requirements, but I dunno that
we should be pointing J. Random User to the developer info chapter..."

> * "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.

Done.

> * 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.

Refined.

>   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...

I killed the warning sidebar.

> * "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.

Done.

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

Fixed.

> * "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.)

Fixed.

> * "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'.

Ooh.  Good idea.  Done.

> * "Undoing Working Changes" section:
>
>    First sentence should have 'svn diff' in <command>, not in quotes.

Done.

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

Oh man, if only you could have been there :-)

> * "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"?

Fixed.

> * "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.

I added it in after the -r 2:3 example

> * "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.

Good catch.  I've added a warning with a link.

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

Must be a FOP error--It's not in the source.

Thanks for the review!

-Fitz