Gareth,
Months ago you posted a long list of comments on the Subversion book. Your message was filed away in issue 1216 and I have just found and reviewed it. (I checked it against the single-page HTML version of the book, in case it makes a difference.) I have assessed most suggestions as:
"Fixed." or "Looks OK.": The text in the book does not appear to have the problem.
"### TO DO": I agree that the suggested change would be good.
Most of your comments are still relevant. If you are willing, it would be really helpful if you could make and post an actual patch (result of "svn diff doc/book/"). The log message (see the "HACKING" file in the root of the source tree) would look something like:
[[[
Improvements to the book: grammar, clarifications, etc.
* doc/book/book/ch03.xml
* doc/book/book/ch04.xml
[...list all the files that are changed by the patch...]
* doc/book/book/appc.xml
[I don't think any specific comments are required here.]
]]]
If you can do this, I will check it and commit it.
- Julian
On 2003-03-02, Gareth McCaughan wrote:
> 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.
Don't worry about that; I will check it.
> If a patch would be helpful, though,
It would. :)
> 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 "…".
Fixed.
> 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...
Looks OK.
> Footnotes are often preceded by spaces, which looks very
> odd. Presumably this could be fixed by losing the whitespace
> before <footnote>...</footnote> ?
Looks OK.
> 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.
Mostly fixed.
> Chapter 3 : Revision Dates
>
> Is there a particular reason for not including ISO8601 format
> in the list of sample date formats Subversion accepts?
Fixed.
> 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?
Fixed.
> 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.
Fixed.
> 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?).
Fixed.
> 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".
Fixed.
> 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.
Fixed.
> 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?
### TO DO
> 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"?
### TO DO
> Chapter 4 : Using branches : Creating a branch
>
> "Whereever you wish": the correct spelling is "Wherever".
Fixed.
> 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.
Looks OK.
> 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?
Not important.
> 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.
Fixed.
> 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?
Looks OK.
> 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?
Not relevant here. A good question for the user interface design in general though.
> 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.
### TO DO
> "... 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.
### TO DO
> 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.)
### TO DO
> 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.
### TO DO
> 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."?
### TO DO
> "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."
### TO DO
> 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.
### TO DO
> Chapter 5 : Repository Maintenance : Repository Backup
>
> "(such as crond on Unix systems)": the program is
> in fact called "cron", not "crond".
### TO DO
> Chapter 5 : Networking a Repository
>
> [footnote] "You know, the collective term ...": I think
> this would read better without the "You know," at the
> start.
### TO DO
> Chapter 5 : Networking a Repository : httpd, the Apache HTTP Server
>
> "speaking the WebDAV/deltaV protocol": "DeltaV" should be
> capitalized thus.
### TO DO
> 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.
### TO DO
> 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?
### TO DO
> Chapter 5 : Networking a Repository : Which server to use?
>
> This should surely mention that at present using svnserve
> is dramatically faster than using Apache.
Fixed.
> 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
Looks OK.
> 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"?
### TO DO
> 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. :-) )
### TO DO
> 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.)
### TO DO
> The bit about "diff-cmd" seems to imply that Subversion
> always calls an external diff command. That's not true
> any longer, is it?
### TO DO
> "Subversion uses this program merge changes made by the
> user ...": insert "to" after "this program".
Fixed.
> Chapter 6 : Properties : Manipulating Properties
>
> The example of using "svn propdel" shows "svn propdel license ..."
> deleting a property called "foo". That isn't right.
Fixed.
> 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.
Fixed.
> 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".
### TO DO
> Chapter 6 : Properties : Special properties : svn:keywords
>
> There's a full stop missing at the end of the second paragraph
> (after "... formatted as $KeywordName$").
### TO DO
> And another at the end of the description of LastChangedBy.
### TO DO
> The description of "Id" begins "This keyword is compressed
> combination ..."; the word "a" should be inserted after "is".
### TO DO
> "...beautiful examples of un-substited keyword anchors!":
> either "ut" or "tu" has been omitted from the word
> "un-substituted" :-).
Fixed.
> 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: ...$".
### TO DO
> 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.
### TO DO
> "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.
### TO DO
> 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 :-).
Looks OK.
> The non-word "syncronize" appears here. It should be
> spelt "synchronize".
Fixed.
> Chapter 6 : Vendor branches
>
> Two more instances of "syncronize". (These, and the one
> in the previous section, are the only ones in the book.)
Fixed.
> 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".
### TO DO
> 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.
### TO DO
> Chapter 7 : Layered Library Design : Client Layer
>
> The first paragraph here contains the non-word "propogating";
> it should be "propagating".
Fixed.
> "This subdirectory, named .svn is present ...": there should
> be a comma after ".svn".
### TO DO
> Chapter 7 : Using the APIs
>
> "Functions private a given source file ...": insert "to" after
> "private".
Fixed.
> "but they definitely help to clarify the scope ...": I think
> removing the word "definitely" would definitely help to
> improve the style here :-).
### TO DO
> Chapter 7 : Using the APIs : The Apache Portable Runtime Library
>
> "While Apache HTTP Server was obviously the first user ...":
> perhaps insert "the" before "Apache"?
### TO DO
> "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> ?
### TO DO
> 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"?
### TO DO
> "... combined with a powerful, flexible binding language
> is so appealing": there should be a comma after "language".
### TO DO
> "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.
### TO DO
> "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".
### TO DO
> The list of languages with bindings to the Subversion API
> includes "Mzscheme". I believe that should have a capital S.
### TO DO
> 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.
Fixed.
> 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?
Looks OK.
> The description of "--revision" is another place where
> perhaps the ISO8601 date format should be one of those
> listed.
### TO DO
> 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".
### TO DO
> 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.
Fixed.
> The description of "svn propset" includes another instance of
> "UNIX" (the only other one in the book). It also talks about
### TO DO
> 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.
Fixed.
> 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.
### TO DO
> Appendix B : Running cvs2svn.py
>
> "It does this by examing RCS files ...": "examining", please.
> A nice instance of haplography. :-)
Fixed.
> "If you interrupt the script, you can pass the -p option to script
> ...":
> insert "the" between "to" and "script".
### TO DO
> 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?)
### TO DO
> 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. :-)
### TO DO
> Appendix C : Common Problems : Problems Building Subversion
>
> "VCa++ 6.0": the "a" is presumably a typo.
### TO DO
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Aug 28 03:06:41 2003