Review of fitz's chapter 2
Brian W. Fitzpatrick
fitz at red-bean.com
Sun Feb 25 14:55:23 CST 2007
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.
> * 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...)"?
> * 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.
> * 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...
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.
> * "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'.
Ooh. Good idea. Done.
> * "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" :-)
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
> * "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!
More information about the svnbook-dev