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

[C. Michael Pilato]

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.

> 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/