Style patches

Joshua Varner jlvarner at gmail.com
Thu Sep 8 16:14:13 CDT 2005


On 9/7/05, Ben Collins-Sussman <sussman at red-bean.com> wrote:
> 
> On Sep 6, 2005, at 12:05 PM, Joshua Varner wrote:
> 
> > Are you interested in style patches?
> >
> 
> Rather than sending patches, how about starting some discussion about
> specific changes you'd like to see?
> 

Here it goes, for me the easiest way to see the various things is
in a patch so I'm inlining one and putting some comments about why
I think they should change. None are really large enough that they make
sense out of context.

Index: ch00.xml
===================================================================
--- ch00.xml	(revision 1660)
+++ ch00.xml	(working copy)
@@ -53,8 +53,9 @@
     
     <para>This book is written for computer-literate folk who want to
       use Subversion to manage their data.  While Subversion runs on a
-      number of different operating systems, its primary user
-      interface is command-line based.  It is that command-line tool
+      number of different operating systems with a number of available
+      clients, the client that is part of Subversion itself
+      is command-line based.  It is this command-line tool
       (<command>svn</command>) which is discussed and used in this
       book.  For consistency, the examples in this book assume the
       reader is using a Unix-like operating system, and is relatively

> Primary seems a bit arbitrary, in a windows environment the "primary"
> interface is GUI, what is unargueable is that the svn command line
> client comes with subversion.
@@ -80,7 +81,7 @@
     
     <para>While this book is written with the assumption that the
       reader has never used version control, we've also tried to make
-      it easy for users of CVS to make a painless leap into
+      it easy for users of CVS to make a painless leap to
       Subversion.  Special sidebars may discuss CVS from time to time,
       and a special appendix summarizes most of the differences
       between CVS and Subversion.</para>

> This is probably to bikeshed, but "into" just feels wrong to me,
> if you want to emphasize the community aspect, then into is
> probably the way to go.
@@ -153,7 +154,7 @@
     <para>The book ends with reference material—chapter 9 is a
       reference guide for all Subversion commands, and the appendices
       cover a number of useful topics.  These are the chapters you're
-      mostly likely to come back to after you've finished the
+      mostly likely to come back to after you've finished reading the
       book.</para>
 
   </sect1>

> More explicit
@@ -218,6 +219,8 @@
       </warning>
     </sect2>
 
+    <!-- where are the conventions for source code examples 
+         this note should be with that -->
     <para>Note that the source code examples are just
       that—examples. While they will compile with the proper
       compiler incantations, they are intended to illustrate the

> There is no convention describing the appearance of code
> samples, and once one is added, this note should be moved
> to be with it.
@@ -267,7 +270,7 @@
         <varlistentry>
           <term>Chapter 4, <emphasis>Branching and Merging</emphasis></term>
           <listitem>
-            <para>Discusses branches, merges, and tagging, including
+            <para>Discusses branches, merges, and tags, including
               best practices for branching and merging, common
               use cases, how to undo changes, and how to easily swing
               from one branch to the next.</para>

> Makes the list have consistent part of speech
@@ -279,8 +282,8 @@
             Administration</emphasis></term>
           <listitem>
             <para>Describes the basics of the Subversion repository,
-              how to create, configure, and maintain a repository, and
-              the tools you can use to do all of this.</para>
+              and the tools to create, configure, and maintain a
+              repository.</para>
           </listitem>
         </varlistentry>
 
> More concise
@@ -394,6 +397,9 @@
       <listitem>
         <para>You will always find the latest version of this book in
           the book's own Subversion repository.</para>
+
+	<!-- Should the URL or web site for the book be included
+	     here? -->
       </listitem>
 
       <listitem>

> Since the book is no longer in the subversion repository, should
> the web site or book repository be mentioned here?

I'm attaching a patch, so that you can see what these changes
look like in context.
Josh
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ch00.patch
Type: application/octet-stream
Size: 3243 bytes
Desc: not available
URL: <http://www.red-bean.com/pipermail/svnbook-dev/attachments/20050908/5a9313bd/attachment.obj>


More information about the svnbook-dev mailing list