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