Review and comments on the Subversion book listed by chapter. Overall Book Comments #1) Blair It may be a good idea where possible to set up a little example repository for the book. It could live as http://www.svnbook.org/examples/ #2) Gareth McCaughan (from issue #1216) There are lots of instances of "..." that should probably be replaced with "…". Capitalization of section headings is quite inconsistent. Most have all significant words capitalized ("Examine Your Changes"), but some don't ("How to Read this Book"). It doesn't much matter which convention is chosen, but it's probably best to stick with one. Chapter 3 #1) ghudson (also affects ch 9 a little bit) The new date parser requires a change to the doc formats. A minimal patch can be found in issue #408. The new date parser accepts three varieties kinds of formats. The first is very nicely documented by the W3C in ; we allow the time zone designator to be missing, in which case we use system local time. The second variety is just like the first variety, except the punctuation characters '-' and ':' are omitted. The third variety is what we use in the output of "svn log", and can look like: YYYY-MM-DD hh:mm[:ss[.uuuuuu]][ +hh[:mm]] There can be fewer than six digits in the microseconds designation, and of course the time zone designation may be "-hh[:mm]" instead of "+hh[:mm]". Examining History : svn log #2) Gareth McCaughan (from issue #1216) 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. Examining History : A Final Word on History #3) Gareth McCaughan (from issue #1216) 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 5 Section svn-ch-5-sect-6 #1) Blair I don't know if the "Adding Projects" sections works best here. It follows pretty specific information on setting up a repository, debugging, recovering, which are highly specific and not generally used. This section could be missed. This information is also used by people who aren't Subversion "administrator's". For example, at my work, there are people creating new projects pretty consistently and we have 61 projects. While I'm the administrator, the users and programmers also need to know project layout information. There's a repository layout section in chapter 4 that this could well be merged into. If that doesn't work, I would consider moving it up to the front of this chapter. Repository Basics : Unversioned Properties #2) Gareth McCaughan (from issue #1216) It may be worth explicitly saying that these are *not* the same as the versioned properties attached to files and directories. Repository Creation and Configuration #3) Gareth McCaughan (from issue #1216) "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? Repository Creation and Configuration : Hook scripts #4) Gareth McCaughan (from issue #1216) 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? Repository Maintenance : An Administrator's Toolkit : Berkeley DB Utilities #5) Gareth McCaughan (from issue #1216) 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.) Repository Maintenance : Repository Cleanup #6) Gareth McCaughan (from issue #1216) "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. Repository Maintenance : Migrating a Repository #7) Gareth McCaughan (from issue #1216) "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 7 Properties : Special properties : svn:ignore #1) Gareth McCaughan (from issue #1216) 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". Properties : Special properties : svn:keywords #2) Gareth McCaughan (from issue #1216) 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: ...$". Properties : Special properties : svn:eol-style #3) Gareth McCaughan (from issue #1216) "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. Externals Definitions #4) Gareth McCaughan (from issue #1216) "no one else has to Subver-bother---sion": wow! This appears to be a bug in whatever generated the PDF form of the document, because the source looks fine :-). Chapter 8 Using the APIs : Using Languages Other than C and C++ #1) Gareth McCaughan (from issue #1216) "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. Chapter 9 Section svn-ch-9-sect-1.2 #1) naked "svn diff" synopsis differs from actual usage and there is no explanation or examples of the --old and --new arguments which are bound to be confusing. #2) naked "svn merge" has the same problem as above. Appendix A Directory Versions #1) Gareth McCaughan (from issue #1216) "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 C Common Problems : Problems Using Subversion #1) Gareth McCaughan (from issue #1216) 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?)