[svnbook commit] r1281 - in trunk/src/en: . book

Ben Collins-Sussman sussman at red-bean.com
Sat May 14 11:17:16 CDT 2005

On May 14, 2005, at 1:06 AM, cmpilato wrote:

> Author: cmpilato
> Date: Sat May 14 01:06:35 2005
> New Revision: 1281
> Modified:
>    trunk/src/en/TODO
>    trunk/src/en/book/ch07.xml
> Log:
> Add section about peg revisions and tracing complex history.

Nice job, Mike!

I just committed some typo fixes and a comment.  But I have a couple  
of extra meta-comments:

> +  <sect1 id="svn-ch-7-sect-2b">
> +    <title>Addressing Historical Ambiguity</title>

This is a fine section title, but I wonder if it's a bit inconsistent  
with the rest of chapter 7.

The other section titles in this chapter are exact names of the  
feature, e.g. "Properties", rather than "Versioning Metadata",  
"Externals definitions" rather than "Building composite working  
copies", "Runtime configuration area" rather than "Changing runtime  

In other words, the titles are all "Feature name", rather than  
"Verbing noun".  So I'm wondering if it wouldn't make sense just to  
name this section "Peg Revisions"?

> +    <screen>
> +$ svn cat -r 1 concept/IDEA
> +subversion/libsvn_client/ra.c:775: (apr_err=20014)
> +svn: Unable to find repository location for 'concept/IDEA' in  
> revision 1
> +</screen>
> +
> +    <para>Of course, in this example, the current
> +      <filename>IDEA</filename> file didn't exist yet in revision 1,
> +      so Subversion gives an error.  The command above is shorthand
> +      for a longer notation which explicitly lists a peg revision.
> +      The expanded notation is:</para>
> +
> +    <screen>

The example(s) you give are excellent, but there's one other thing  
I'd love to see in this section:  some sort of overview that explains  
the *algorithm* that Subversion follows.

You talk about a peg-revision "defining a unique line of history",  
and how svn then performs the work on the operative-revision(s).  But  
I'd love to see this described less in prose, and more as  
straightforward algorithm.  Something like:

       When Subversion sees the syntax "svn subcommand -rX file at PEG", it

         * locates the 'file' object in revision PEG  (thus pegging a  
line of history),

         * traces the history line backwards to revision X, and  
operates on the older object, whatever its path may be.

I think this sort of top-down algorithmic explanation, if given  
before your examples, will make the examples easier to understand.

'Tis my 2 cents.

More information about the svnbook-dev mailing list