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