[svnbook commit] r1229 - trunk/src/en
maxb
svnbook-dev at red-bean.com
Fri Apr 22 06:20:25 CDT 2005
Author: maxb
Date: Fri Apr 22 06:20:24 2005
New Revision: 1229
Modified:
trunk/src/en/REVIEW
Log:
* en/REVIEW: Issue #1216 was essentially an extension of the REVIEW file, but
having a bunch of unrelated comments in an IssueZilla issue is not very
flexible. Transfer the entire contents of the issue here (and close the
issue.)
Modified: trunk/src/en/REVIEW
==============================================================================
--- trunk/src/en/REVIEW (original)
+++ trunk/src/en/REVIEW Fri Apr 22 06:20:24 2005
@@ -9,6 +9,17 @@
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)
@@ -31,6 +42,23 @@
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
@@ -52,6 +80,143 @@
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
@@ -66,3 +231,30 @@
#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?)
+
+
More information about the svnbook-dev
mailing list