[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

a pile of comments on the Book

From: Gareth McCaughan <Gareth.McCaughan_at_pobox.com>
Date: 2003-03-02 22:34:06 CET

I just sat down and read the book. It's very good indeed. I have a
number of corrections, suggestions and other comments. Here they
are. They are relative to revision 5113, of 2003-02-26.

I haven't included a patch, because lots of these are stylistic
issues where the authors may well disagree with me, and because
for lots of others I don't currently know enough to be confident
of not writing something wrong. If a patch would be helpful, though,
I can produce one just as soon as I know which of these are
deemed worth acting on. If any :-).

[lots of places]

    There are lots of instances of "..." that should probably
    be replaced with "&hellip;".

    There are some curious choices of line break. For
    instance, in at least one place a command-line option
    of the form "--foobar" has been broken between its
    two dashes! I appreciate that this may not be fixable
    in the book's source...

    Footnotes are often preceded by spaces, which looks very
    odd. Presumably this could be fixed by losing the whitespace
    before <footnote>...</footnote> ?

    Capitalization of section headings is quite inconsistent.
    Most have all significant words capitalized ("Examine Your
    Changes"), but some don't ("Adding projects"). It doesn't
    much matter which convention is chosen, but it's probably
    best to stick with one.

Chapter 3 : Revision Dates

    Is there a particular reason for not including ISO8601 format
    in the list of sample date formats Subversion accepts?

Chapter 3 : Examine Your Changes : svn status

    The reference to properties here may mystify newcomers;
    how about a cross-reference to where properties are
    discussed?

Chapter 3 : Examine Your Changes : svn diff

    Anyone reading that "Output is displayed in unified diff
    format" will immediately wonder whether it's possible to
    change that. It would be good to satisfy their curiosity
    briefly here.

Chapter 3 : Resolving conflicts

    "Once you've resolved the conflict, you need to let
    Subversion know by removing the three temporary files."
    ... is followed by an example command that doesn't
    (on the face of it) involve doing anything of the kind.
    It would be good to say explicitly that that's what
    "svn resolve" does and that running "svn resolve" is
    the preferred way to remove the temporary files; better
    still to explain why (is it anything more than convenience?).

Chapter 3 : Resolving conflicts : Copying a file onto your working
file

    The example code includes a bare "svn resolve", with no
    path. It should presumably say "svn resolve sandwich.txt".

Chapter 3 : Examining History : svn log

    It would be good to say something here about the
    interaction between "svn log" and the ability to move
    files and directories around. Maybe just a pointer
    to where it's discussed more fully.

Chapter 3 : Examining History : A Final Word on History

    Anyone who's used CVS will be wondering: if I use
    "svn update" with the --revision flag to move back
    in time, what then happens when I do later updates
    without that flag?

Chapter 4 : Using branches

    "It will take a long time to calc": presumably this is
    a typo, though I'm not sure quite what it was *meant*
    to say. Perhaps "It will take a long time to do"?

Chapter 4 : Using branches : Creating a branch

    "Whereever you wish": the correct spelling is "Wherever".

Chapter 5 : Repository Basics : Unversioned Properties

    It may be worth explicitly saying that these are *not*
    the same as the versioned properties attached to files
    and directories.

Chapter 5 : Repository Creation and Configuration

    "A file whose contents are a single integer value ...":
    that could mean either a string of characters representing
    an integer in base 10, or a bunch of bytes representing
    an integer in base 256. Presumably it means the former;
    maybe add "in base 10" to the text?

Chapter 5 : Repository Creation and Configuration : Hook scripts

    "Currently there are five true hooks ...": In what sense
    "true" hooks? They don't seem to be being contrasted with
    false hooks or pseudo-hooks or hook-alikes here. I think
    the word "true" should be either removed or explained.

Chapter 5 : Repository Creation and Configuration : Hook scripts

    At the end of this section, there's a note about permissions
    and file ownership and so on. It slightly gives the impression
    that the main failure mode in this area is having a hook
    script that can't do what you want because it doesn't have
    permission. Well, maybe that's the commonest failure mode,
    but there's a more serious failure mode where the script
    can do altogether too much because it has too much permission.
    Is it worth adding some mumblings about security?

Chapter 5 : Repository Maintenance : An Administrator's Toolkit :
svnlook

    (This is really a question about svnlook itself more than
    about the book.) The output from svnlook is supposed to be
    machine-readable. What happens to, e.g., "svnlook tree"
    if there are filenames containing newlines?

Chapter 5 : Repository Maintenance : An Administrator's Toolkit :
Berkeley DB Utilities

    "... with any of Berkeley's database tools ...": since this
    stuff is now owned by Sleepycat, I think "Berkeley's" is
    misleading. I suggest "... with any of the Berkeley database
    tools ..." instead.

    "... these tools are unnecessary, however, they do provide ...":
    either the comma before "however" should be a semicolon, or
    "however," should be replaced with "but". I prefer the latter.

    The text says that db_dump and db_load are useful for transferring
    Berkeley databases from one machine to another. It would be good
    to clarify the relationship between these and "svnadmin dump"
    and "svnadmin load". (That is, that there isn't any, and that
    Subversion users want to use the latter rather than the former.)

Chapter 5 : Repository Maintenance : Repository Cleanup

    "If you use these two subcommands like this, you should
    consider making your repository temporarily inaccessible
    to clients." -- this advice would be much more helpful
    if it said how to do it. Later in the book, there's a
    similar piece of advice that recommends killing the svnserve
    or Apache process, but (1) Apache might be being used for
    other things that you don't want to kill, (2) if you're
    using svnserve over ssh, doesn't each user have their own
    process?, and (3) this doesn't help if you have users
    accessing the repository directly. Hmm.

Chapter 5 : Repository Maintenance : Migrating a Repository

    "The only exception to this rule is the first revision
    that is dumped with the current svnadmin dump command."
    I'm not sure what "current" is meant to mean here. How
    about "... that is dumped with each svnadmin dump command."?

    "And, secondly, Subversion cannot know the state of the
    repository into which the dump data will be loaded (if
    it ever, in fact, occurs)." Er, if *what* ever occurs?
    Loading of the dump into a repository? If that's the
    meaning, then I suggest: "... into which the dump data
    will be loaded, if indeed it's ever loaded into a
    repository at all."

    The section about incremental repository dumps would,
    I think, be improved if it said *explicitly* that the
    concatenation of two dumps is a legal dump.

Chapter 5 : Repository Maintenance : Repository Backup

    "(such as crond on Unix systems)": the program is
    in fact called "cron", not "crond".

Chapter 5 : Networking a Repository

    [footnote] "You know, the collective term ...": I think
    this would read better without the "You know," at the
    start.

Chapter 5 : Networking a Repository : httpd, the Apache HTTP Server

    "speaking the WebDAV/deltaV protocol": "DeltaV" should be
    capitalized thus.

Chapter 5 : Networking a Repository : svnserve, a Custom Subversion
Server

    "Clients access the server with libsvn_ra_svn": this is
    the first mention of libsvn_ra_svn in the book; novice
    readers will have no idea what it is. It might be worth
    offering a brief explanation or a cross-reference. Or,
    perhaps better, not mentioning it at all. libsvn_ra_svn
    is an implementation detail with which Subversion *users*
    shouldn't need to be concerned at this point.

Chapter 5 : Networking a Repository : svnserve, a Custom Subversion
Server : Tunneling over SSH

    The business about "your servers run-time configuration
    file" will make sense only to someone who already knows
    about that configuration file. How about a cross-reference?

Chapter 5 : Networking a Repository : Which server to use?

    This should surely mention that at present using svnserve
    is dramatically faster than using Apache.

Chapter 5 : Adding projects : Choosing a Repository Layout

    According to the textual description, in both suggested
    layouts "branches" is a directory in which branches live.
    But what's then said about the second layout implies that
    actually it would have structure like

        /branches/projectA/bugfix-1234

    rather than

        /branches/bugfix-1234/projectA

Chapter 6

    The first paragraph begins "If you've been reading this book
    chapter by chapter, from start to finish", but of course
    at this point a reader who's been doing that hasn't reached
    the finish yet and doesn't know whether s/he will :-).
    How about "from the start" instead of "from start to finish"?

Chapter 6 : Run-time Configuration Area : Configuration Area Layout

    "you can simply delete the file, and run some innocuous
    svn command ...": in context, that comma is wrong. Delete it.
    (And run some innocuous svn command. :-) )

Chapter 6 : Run-time Configuration Area : Configuration Options :
Config

    "and the edits take places right in the editor program":
    oops :-). Should just be "take place". This section should
    perhaps say what happens if Subversion can't find an editor
    to use. (Namely, that whatever command you were running
    aborts with an error message.)

    The bit about "diff-cmd" seems to imply that Subversion
    always calls an external diff command. That's not true
    any longer, is it?

    "Subversion uses this program merge changes made by the
    user ...": insert "to" after "this program".

Chapter 6 : Properties : Manipulating Properties

    The example of using "svn propdel" shows "svn propdel license ..."
    deleting a property called "foo". That isn't right.

    The box about modifying revision properties has an example
    that shows "svn propset svn:log ..." changing a property
    called "status". That isn't right either.

Chapter 6 : Properties : Special properties : svn:ignore

    It might be worth making a bigger deal of the one really
    key difference between svn:ignore and .cvsignore: the former
    will always get checked in whenever the directory it applies to
    does, whereas you can leave .cvsignore un-checked-in. This is
    alluded to in passing ("These facts are true for all working
    copies, not just your own."), but it should probably be mentioned
    in the box "Ignore Patterns for CVS Users".

Chapter 6 : Properties : Special properties : svn:keywords

    There's a full stop missing at the end of the second paragraph
    (after "... formatted as $KeywordName$").

    And another at the end of the description of LastChangedBy.

    The description of "Id" begins "This keyword is compressed
    combination ..."; the word "a" should be inserted after "is".

    "...beautiful examples of un-substited keyword anchors!":
    either "ut" or "tu" has been omitted from the word
    "un-substituted" :-).

    The exact treatment of the briefer aliases for keywords
    isn't very clear. Specifically, I can't tell from the
    description here (1) whether, if I include "LastChangedDate"
    in svn:keywords, "$Date$" will get expanded or not, nor
    (2) whether, if I have "$Date$" and it gets expanded, it
    turns into "$Date: ...$" or "$LastChangedDate: ...$".

Chapter 6 : Properties : Special properties : svn:eol-style

    "A unix user checking out a working copy" ... "Unix" is
    capitalized everywhere else in the book, and presumably
    should be here too.

    "This is basically transparent to the user, though.":
    every time I see "basically" in a technical book it
    makes me shudder, because I'm afraid that underneath it
    lurk some nasty details that the author is afraid to
    touch. This should either say "This is transparent to
    the user." or else explain briefly the ways in which
    it's not quite transparent.

Chapter 6 : Externals Definitions

    "no one else has to Subver-bother---sion": wow! This
    appears to be a bug in whatever generated the printed
    form of the document, because the source looks fine :-).

    The non-word "syncronize" appears here. It should be
    spelt "synchronize".

Chapter 6 : Vendor branches

    Two more instances of "syncronize". (These, and the one
    in the previous section, are the only ones in the book.)

Chapter 7 : Layered Library Design : Repository Access Layer : RA-DAV

    The two uses of "machines" in the first sentence here
    are referring to different things. I suggest changing
    the second to "servers".

Chapter 7 : Layered Library Design : Repository Access Layer : RA-SVN

    The brief description of why one might want to use ra_svn
    in preference to ra_dav doesn't mention one important reason:
    that, at least at present, ra_svn is considerably faster.

Chapter 7 : Layered Library Design : Client Layer

    The first paragraph here contains the non-word "propogating";
    it should be "propagating".

    "This subdirectory, named .svn is present ...": there should
    be a comma after ".svn".

Chapter 7 : Using the APIs

    "Functions private a given source file ...": insert "to" after
    "private".

    "but they definitely help to clarify the scope ...": I think
    removing the word "definitely" would definitely help to
    improve the style here :-).

Chapter 7 : Using the APIs : The Apache Portable Runtime Library

    "While Apache HTTP Server was obviously the first user ...":
    perhaps insert "the" before "Apache"?

    "But perhaps the most pervasive APR datatype, found in nearly
    every Subversion API prototype, is the apr_pool_t ...":
    should "apr_pool_t" here be enclosed in <literal></literal> ?

Chapter 7 : Using the APIs : Using Languages Other than C and C++

    "As you know, only a human can botch up the input to a program
    as well as they do": this reads very clumsily to me. How about
    "As you know, there is no limit to how badly a human can botch
    the input to a program"?

    "... combined with a powerful, flexible binding language
    is so appealing": there should be a comma after "language".

    "Our example will do the same thing as our last example":
    no it won't. The previous example was a function to create
    a directory in the repository; this one enumerates paths
    below a given point in the repository. What it's the same
    as is the example in the section on memory pools, but that's
    later in the book.

    "Python has hashes and lists (called "dictionaries" and
    "sequences", respectively): no, Python's lists are called
    lists. Python has a more general notion of "sequence" too,
    meaning something like "anything you can iterate over".

    The list of languages with bindings to the Subversion API
    includes "Mzscheme". I believe that should have a capital S.

Chapter 8 : The Subversion Command Line Client: svn : Switches

    Most of the switches that have single-letter forms have
    them documented here. For some reason, --extensions (-x)
    doesn't.

    While I'm on the subject of --extensions, perhaps its
    description should mention that "svn diff" no longer goes
    to an external diff program at all by default?

    The description of "--revision" is another place where
    perhaps the ISO8601 date format should be one of those
    listed.

Chapter 8 : The Subversion Command Line Client: svn : svn subcommands

    The description of "svn list" says: "Like UNIX ls, you can also
    pass the --verbose switch for additional information.". But
    (1) "Unix" is normally capitalized thus, and (2) the Unix "ls"
    command doesn't have a "--verbose" switch. It has plenty of
    others that generate more information; the nearest equivalent
    is perhaps "-l".

    The description of "svn log" says: "With --quiet, svn log don't
    print the log message body itself". That don't look like no good
    grammer to me :-). "doesn't", surely.

    The description of "svn propset" includes another instance of
    "UNIX" (the only other one in the book). It also talks about
    setting the svn:log revprop to fix a broken log message; it
    should mention that by default that isn't allowed, and maybe
    cross-ref to where the issue is discussed in more detail.

Appendix A : Directory Versions

    "For more discussion about the limitations of directory
versioning,
    see ...": it looks to me as if the referenced section contains
    strictly *less* about the limitations of directory versioning
    than the preceding paragraphs in appendix A. Someone turning there
    will learn nothing new.

Appendix B : Running cvs2svn.py

    "It does this by examing RCS files ...": "examining", please.
    A nice instance of haplography. :-)

    "If you interrupt the script, you can pass the -p option to script
...":
    insert "the" between "to" and "script".

Appendix C : Common Problems : Problems Using Subversion

    The first problem meets with the suggestion of running
    "svn recover", and says "Make sure you run this command
    as the user that owns and manages the database ...".
    Perhaps it should say something about what to do if
    you run it as root by mistake. (Is "chown -R user:group
/path/to/repos"
    sufficient, for instance?)

    The problem about running under Windows and having import/checkout
    operations fail says "Then the problem is that Subversion
    doesn't handle file URLs that have a drive specification".
    (1) The initial "t" should not be capitalized, since it's
    in the middle of a sentence. (2) According to chapter 2,
    Subversion *does* recognize file URLs that have a drive
    specification. One of these must be wrong. :-)

Appendix C : Common Problems : Problems Building Subversion

    "VCa++ 6.0": the "a" is presumably a typo.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Mar 2 22:35:01 2003

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.