[svnbook commit] r3420 - trunk/src/en/book

[Stefan Sperling]

On Mon, Feb 09, 2009 at 08:29:07AM -0500, C. Michael Pilato wrote:
> codesite-noreply at google.com wrote:
> > Author: stsp at elego.de
> > Date: Fri Feb  6 08:07:04 2009
> > New Revision: 3420
> > 
> > Modified:
> >    trunk/src/en/book/ch02-basic-usage.xml
> > 
> > Log:
> > * src/en/book/ch02-basic-usage.xml
> >   (svn.tour.treeconflicts.example): New section illustrating how to
> >    deal with tree conflicts.
> 
> Overall, good stuff.  Some inline comments below.

Thanks Mike!

I haven't had time yet to work on integrating your feedback.
Just letting you know that I have not forgotten about this.
Will try to do it ASAP.

Stefan
> 
> > Modified: trunk/src/en/book/ch02-basic-usage.xml
> > ==============================================================================
> > 
> > --- trunk/src/en/book/ch02-basic-usage.xml    (original)
> > +++ trunk/src/en/book/ch02-basic-usage.xml    Fri Feb  6 08:07:04 2009
> > @@ -2348,7 +2348,271 @@
> >          problems before committing.</para>
> > 
> >        <!-- TODO: example -->
> > +    <sect2 id="svn.tour.treeconflicts.example">
> > +      <title>An example Tree Conflict</title>
> > 
> > +      <para>Suppose a software project you are working currently
> > +       looks like this:</para>
> > +
> > +      <screen>
> > +$ svn ls -Rv svn://svn.example.com/trunk/
> > +      4 harry                 Feb 06 14:34 ./
> > +      4 harry              23 Feb 06 14:34 COPYING
> > +      4 harry              41 Feb 06 14:34 Makefile
> > +      4 harry              33 Feb 06 14:34 README
> > +      4 harry                 Feb 06 14:34 code/
> > +      4 harry              51 Feb 06 14:34 code/bar.c
> > +      4 harry             124 Feb 06 14:34 code/foo.c
> > +</screen>
> > +
> > +      <para>Suppose your collaborator Harry has renamed the file
> > +        <filename>bar.c</filename> to <filename>baz.c</filename>.
> > +        You are still working on <filename>bar.c</filename> in your
> > +        working copy, but you don't know yet that the file has
> > +        been renamed in the repository.</para>
> > +
> > +      <para>Suppose the log message to Harry's commit looks like
> > +        this:</para>
> 
> At this point, I've seen the word "Suppose" far too often.  You've
> established that this is an example, and setup the hypothetical initial
> state.  From there on, I think we can state "Harry's done this" and "You've
> done this", where the past tense is the clue that let's the reader know
> you're still establishing the supposedly background of the situation, and
> the eventual switch to present-tense verbs signals the suggested response to
> the situation.
> 
> > +Index: code/bar.c
> > +===================================================================
> > +--- code/bar.c  (revision 4)
> > ++++ code/bar.c  (working copy)
> > +@@ -1,4 +1,4 @@
> > + const char* bar(void)
> 
>    "const char *bar(void)", for consistency?
> 
> > + {
> > +-       return "Me neither!\n";
> > ++       return "Well, I do like being moved around!\n";
> > + }
> > +</screen>
> > +
> > +      <para>Your changes are all based on revision 4. They cannot be
> > +        committed because Harry has already checked in revision 5:</para>
> > +
> > +      <screen>
> > +$ svn commit -m "Small fixes"
> > +Sending        code/bar.c
> > +Sending        code/foo.c
> > +Transmitting file data ..
> > +svn: Commit failed (details follow):
> > +svn: File not found: transaction '5-5', path '/trunk/code/bar.c'
> > +</screen>
> > +<!-- XXX: That error message should be cleaned up! -->
> > +
> > +      <para>It is now mandatory to run <command>svn update</command>.
> > +        This causes a tree conflict to be flagged:</para>
> 
> Suggest: "At this point, you need to run 'svn update'.  Besides bringing our
> working copy up to date so that you can see Harry's changes, this also flags
> the tree conflict so you have the opportunity to evaluate and properly
> resolve it."  (Just so folks don't think by reading this section alone that
> 'svn up' does nothing more than 'tree conflict'
> 
> > +      <para>During <command>svn update</command>, tree conflicts are
> > +        signified by a capital C in the fourth output column. Details
> > +        about the conflict can be seen in the output of
> > +        <command>svn status</command>:</para>
> 
> Try to use a more active voice instead of a passive one:
> 
>    In its output, 'svn update' signifies tree conflicts using a
>    capital C in the fourth output column.  'svn status' reveals additional
>    details of the conflict:
> 
> (You might need to make similar adjustments elsewhere, but this paragraph
> just caught my eye.)
> 
> > + const char* bar(void)
> 
>     const char *bar(void)
> 
> > +      <warning>
> > +        <para>This only works if <filename>bar.c</filename> in your
> > working
> > +          copy is based on the revision in which
> > <filename>bar.c</filename>
> > +          was last modified before being moved in the repository.
> > +          Otherwise, Subversion will resort to retreiving
> > +          <filename>baz.c</filename> from the repository, and will not
> > +          try to transfer your local modifications to it. You will have
> > +          to do so manually.
> > +        </para>
> > +      </warning>
> 
> Try to avoid being unnecessarily vague in admonishments.  A "warning" block
> is set off from the rest of the text visually, which means the eye will be
> drawn to it.  Bummer when what the eye finds is "This only works..."  This?
>  This what?  Probably better to replace "this" with something which
> concisely gives a little more information about what "this" is.
> 
> > +Index: code/baz.c
> > +===================================================================
> > +--- code/baz.c  (revision 5)
> > ++++ code/baz.c  (working copy)
> > +@@ -1,4 +1,4 @@
> > + const char* bar(void)
> 
> Ho hum.
> 
> > + const char* bar(void)
> 
> La dee da.
> 
> > +-const char* bar(void)
> 
> Whoop dee doo.
> 
> 
> -- 
> C. Michael Pilato <cmpilato at red-bean.com> | http://cmpilato.blogspot.com/