Review of Chapter 2: Basic Usage

Brian W. Fitzpatrick fitz at red-bean.com
Sat Feb 24 23:17:08 CST 2007


> Running with the previously made agreement that, to the degree possible,
> we won't try to mention concepts earlier in the book than their proper
> introduction, there are some issues that arise fairly early in the chapter.
>
>   * The section on getting data into the repository is introducing 'svn
>     import' and 'svn add'.  No problem with 'svn import', but the part
>     about 'svn add' requires a working copy (though we've not
>     mentioned how to get one yet) and casually mentions 'svn commit'
>     (without further explanation -- though, at least in this case
>     'commit' was mentioned in Chapter 1).
>
>     Perhaps we should simply explain 'svn import' here, and note that
>     later in the chapter we'll talk about other ways to add files to
>     version control (since we do cover 'add' again later as part of
>     the "making changes" section).

Done.  I dropped the svn add here and pointed to later in the chapter.

>   * Shortly after introducing checkouts, we smack users with "Disabling
>     Password Caching", which is a pretty hefty topic.  Seems that
>     Chapter 1 (where fundamentals are discussed) should mention the
>     fundamental fact that Subversion can operate over a network and
>     supports authentication.  In fact, Chapter 1 does talk about
>     a client/server model, but is using the terms "Repository" and
>     "Client".  It's really kinda wierd that way.

I'll leave that to Ben then. :)

> I don't like that we explain each and every status code in this chapter.
>  That's reference material.  Choosing some common examples to
> demonstrate is fine, but the exhaustive list need live only in the
> reference.  The current state is a hugely imbalanced attention to the
> finer details of 'svn status' compared to the level of exposition
> provided for the other subcommands.  And it also means we have several
> links to later chapters because some of the status codes have more
> advanced meanings.

That makes a lot of sence--I pulled 80% of it and added a pointer to
the reference chapter.  I'll make sure that the reference chapter
covers everything that we covered here.

> I've similar complaints about the exhaustive list of 'svn update' output
> codes.

Did the same here.

> The variable list section containing "File changes" and "Tree changes"
> is unnecessary.  I'd just merge the info there into the two paragraphs
> which follow it.

Done.

> I think we should promote 'svn mkdir' as a commonly used operation.  It
> certainly is for me, but more importantly, there are multiple references
> to it in the "Basic Work Cycle" section that might make more sense if it
> was quickly explained alongside add, delete, copy and move.

Agreed--done.  Heck, there's plenty of room now that I pulled out all
that svn status and svn update cruft! :-)

> "Earlier in this chapter, we said that you have to commit any changes
> that you make in order for the repository to reflect these changes.
> That's not entirely true--there are some use cases that immediately
> commit tree changes to the repository."  This seems contradictory --
> "earlier we said you have to commit, but we lied, because sometimes you
> can commit another way".  I know what is meant here; I don't think our
> readers will.

Done.  It was actually a total lie--there wasn't anywhere in the
chapter where we said that.  Doh.

> "Look Ma!  No Network!" begins, "All three of these commands (svn
> status, svn diff, and svn revert) can be used without any network
> access..."  Sidebars should be self-sufficient, able to be read
> independent of the surrounding chapter context.  But "these commands"
> has a dependency on that context.  Remember that in print, sidebars may
> get moved around so that they fit nicely on the printed page -- the
> context in our HTML and PDF renderings isn't guaranteed to be the same
> context in the printed book.

Tweaked.

> The footnote that begins "Subversion uses its internal diff engine,
> which produces unified diff format, by default." is a little out of
> date.  In Subversion 1.4.0, you can get whitespace-ignoring diffs
> without using an external diff tool.  Maybe pick a different peculiarity
> of GNU diff to highlight?

Fixed to ignore case differences instead.

> "Undoing Working Changes" begins, "Now suppose you see the above diff
> output..."  First, we can't say "above" -- that implies page
> positioning.  But more importantly, it binds the section to the previous
> one, and this is something we try to avoid.  This section doesn't need
> to refer to a diff in a previous section, because "setting up" the
> example is a really trivial task.  "Suppose while viewing the output of
> 'svn diff' you determine that all the changes you made to a particular
> file are mistakes.  Maybe you shouldn't have changed the file at all, or
> perhaps it would be easier to make different changes starting from scratch."

Perfect.  Fixed.

> "You're probably wondering why we don't just use svn update --revision
> to update the file to the older revision.... it's sometimes just easier
> to look at an older version of a file in its entirety than to look only
> at the differences between it and another revision."  These two
> sentences don't really make sense.  'svn update' isn't about viewing
> diffs, and *would* provide a way to see the old version of the file in
> its entirety.

Ah.  I was unclear.  The point I was trying to make is that sometimes
you just need a fulltext copy of an older revision while keeping your
current revision around. Anyway, they were prolix, so I pulled those 2
mini-paragraphs.

> I'm not completely thrilled with the relationship of this chapter to the
> other ones.  That's not anybody's fault, really -- it's extremely
> difficult to present so many interrelated concepts in building-blocks
> order.  But I'll start a different thread around that subject.

Okey doke.  Changes incoming momentarily.  Thanks again for the
awesome review--the chapter is feeling really tight now.

-Fitz




More information about the svnbook-dev mailing list