[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

[PATCH] documentation fixes

From: Ben Elliston <bje_at_air.net.au>
Date: 2002-12-22 02:30:41 CET

Attached is a changeset that makes some documentation changes that I noted
while reading "Subversion: The Definitive Guide". I tried to minimise any
stylistic changes in light of the statements made in the doc/book/HACKING
file, since they're less likely to be accepted. :-) My log message is
quite verbose; I hope that it provides sufficient justification for the
changes.

In most cases, I was looking to clarify things or make the text read more
smoothly. I'd like to specifically defend the change to ch08.xml -- while
I appreciate that hacker lingo makes for a more enjoyable document, I fear
it will confuse readers whose mother tongue is not English. In such
cases, writers should probably take the conservative line.

Keep up the great work. Subversion rocks!

Ben

   * doc/book/book/ch01.xml
     (Target audience): Remove duplicated use of "appendix".
     (History): Use commas instead of parentheses where applicable.
     Reword some sentences to flow better.
     (History of Subversion): Surround Collabnet URL in parentheses.
   * doc/book/book/ch02.xml
     (The Repository): Mention that .svn directories have the nice
     property of not showing up in normal directory listings.
     (How working copies track the repository): Reword. Remove commas
     from the terms in the list of possible file states.
   * doc/book/book/ch03.xml
     (Make Changes to Your Working Copy): Reword some paragraphs.
     (Changing the Repository Without a Working Copy): Remove excess
     parentheses.
     (Examine Your Changes): Add commentary about reviewing patches.
     (CVS Users: Hold That Update!): Add comment about "cvs update".
     (Look Ma! No Network!): Beach hacking is more realistic for most
     of us than being on the flight deck of the Space Shuttle.
     Replace occurrence of "1" with "one".
     (Resolving conflicts): Remove surplus comma.
   * doc/book/book/ch08.xml
     (svn export): Replace "rolling" with "producing".

Index: ./doc/book/book/ch01.xml
===================================================================
--- ./doc/book/book/ch01.xml
+++ ./doc/book/book/ch01.xml 2002-12-22 11:37:50.000000000 +1100
@@ -30,10 +30,10 @@
       or CVS. It assumes that the reader is computer-literate, and
       reasonably comfortable at a Unix command-line.</para>
 
- <para>People familiar with CVS may want to skip some of the introductory
- sections that describe Subversion's concurrent versioning model.
- Also, there is a quick guide for CVS users attached as an appendix
- <xref linkend="svn-ap-a"/></para>
+ <para>People familiar with CVS may want to skip some of the
+ introductory sections that describe Subversion's concurrent
+ versioning model. Also, there is a quick guide for CVS users
+ attached as <xref linkend="svn-ap-a"/>.</para>
     
   </sect1>
 
@@ -62,11 +62,11 @@
           configuration management</firstterm> (SCM) systems. These
         systems are specifically tailored to manage trees of source
         code, and have many features that are specific to software
- development (such as natively understanding programming
- languages). Subversion, however, is not one of these
+ development, such as natively understanding programming
+ languages. Subversion, however, is not one of these
         systems; it is a general system that can be used to manage
- <emphasis>any</emphasis> sort of collection of files,
- including source code.</para>
+ <emphasis>any</emphasis> collection of files, including
+ source code.</para>
       
     </sect2>
     
@@ -95,8 +95,8 @@
         should be written such that any CVS user should be able to
         start using it with little effort.</para>
       
- <para>Collabnet <systemitem
- class="url">http://www.collab.net/</systemitem> provided the
+ <para>Collabnet (<systemitem
+ class="url">http://www.collab.net/</systemitem>) provided the
         initial funding in 2000 to begin development work, and the
         effort has now blossomed into a large, open-source project
         backed by a community of free software developers.</para>
Index: ./doc/book/book/ch02.xml
===================================================================
--- ./doc/book/book/ch02.xml
+++ ./doc/book/book/ch02.xml 2002-12-22 11:38:28.000000000 +1100
@@ -259,7 +259,9 @@
         In particular, each directory in your working copy contains a
         subdirectory named <filename>.svn</filename>, also known as
         the working copy <firstterm>administrative
- directory</firstterm>. The files in each administrative
+ directory</firstterm>. Since the directory name beings with a
+ period, it is not normally visible in directory listings and
+ so stays out of your way. The files in each administrative
         directory help Subversion recognize which files contain
         unpublished changes, and which files are out-of-date with
         respect to others' work.</para>
@@ -490,13 +492,13 @@
             last updated by the repository.</para></listitem>
       </itemizedlist>
 
- <para>Given this information, by talking to the repository,
- Subversion can tell which of the following four states a
- working file is in:</para>
+ <para>Given this information, and by communicating with the
+ repository, Subversion can tell which of the following four
+ states a working file is in:</para>
 
       <variablelist>
         <varlistentry>
- <term>Unchanged, and current</term>
+ <term>Unchanged and current</term>
 
           <listitem><para>The file is unchanged in the working
           directory, and no changes to that file have been committed
@@ -507,7 +509,7 @@
         </varlistentry>
         
         <varlistentry>
- <term>Locally changed, and current</term>
+ <term>Locally changed and current</term>
 
           <listitem><para>The file has been changed in the working
           directory, and no changes to that file have been committed
@@ -519,7 +521,7 @@
         </varlistentry>
         
         <varlistentry>
- <term>Unchanged, and out-of-date</term>
+ <term>Unchanged and out-of-date</term>
 
           <listitem><para>The file has not been changed in the working
           directory, but it has been changed in the repository. The
@@ -531,7 +533,7 @@
         </varlistentry>
         
         <varlistentry>
- <term>Locally changed, and out-of-date</term>
+ <term>Locally changed and out-of-date</term>
 
           <listitem><para>The file has been changed both in the
           working directory, and in the repository. A <command>svn
@@ -585,8 +587,8 @@
     
     <para>At this point, you should have a good idea of how Subversion
     works in the most general sense. Armed with this knowledge, you
- should now be ready to jump into the next chapter, which is a
- detailed tour of Subversion's commands and features. </para>
+ should now be ready to jump into the next chapter: a detailed tour
+ of Subversion's commands and features. </para>
       
   </sect1>
 
Index: ./doc/book/book/ch03.xml
===================================================================
--- ./doc/book/book/ch03.xml
+++ ./doc/book/book/ch03.xml 2002-12-22 12:07:13.000000000 +1100
@@ -523,17 +523,18 @@
               and directories for scheduled removal, addition,
               copying, or moving. While these changes may take place
               immediately in your working copy, no additions or
- removals will happen in the repository until you decide
- to commit.</para>
+ removals will happen in the repository until you commit
+ them.</para>
           </listitem>
         </varlistentry>
 
       </variablelist>
       
- <para>To make file changes, just use your text editor, word
- processor, or graphics program&mdash;whatever tool you would
+ <para>To make file changes, use your text editor, word
+ processor, graphics program, or whatever tool you would
         normally use. Subversion handles binary files just as easily
- as it handles text files (and just as efficiently too).</para>
+ as it handles text files&mdash;and just as efficiently
+ too.</para>
       
       <para>Here is an overview of the four Subversion subcommands
         that you'll use most often to make tree changes (we'll cover
@@ -611,10 +612,10 @@
           <emphasis>are</emphasis> some use-cases that immediately
           commit tree changes to the repository. This only happens
           when a subcommand is operating directly on a URL, rather
- than on a working-copy path. (In particular, specific uses
+ than on a working-copy path. In particular, specific uses
           of <command>svn mkdir</command>, <command>svn
           copy</command>, <command>svn move</command>, and
- <command>svn delete</command> can work with URLs).</para>
+ <command>svn delete</command> can work with URLs.</para>
 
         <para>URL operations behave in this manner because commands
           that operate on a working copy can use the working copy as a
@@ -637,7 +638,9 @@
         examining your changes before you commit, you can not only
         make a more accurate log message, but you may discover that
         you've inadvertently changed a file, and this gives you a
- chance to revert those changes before committing. You can see
+ chance to revert those changes before committing.
+ Additionally, this is a good opportunity to review and
+ scrutinize changes before publishing them. You can see
         exactly what changes you've made by using <command>svn
         status</command>, <command>svn diff</command>, and
         <command>svn revert</command>. You will usually use the first
@@ -668,7 +671,8 @@
             working copy. <command>svn status</command> will give
             you all the information you need regarding what has
             changed in your working copy&mdash;without accessing the
- repository.</para>
+ repository or potentially incorporating new changes
+ published by other users.</para>
         
           <para>In Subversion, <command>update</command> does just
             that&mdash;it updates your working copy with any changes
@@ -1046,9 +1050,8 @@
           <command>svn revert</command>) can be used without any
           network access. This makes it easy to manage your
           changes-in-progress when you are somewhere without a network
- connection (e.g. traveling on an airplane, riding on a
- commuter train, on the flight deck of the Space Shuttle,
- etc.).</para>
+ connection such as traveling on an aeroplane, riding a
+ commuter train or hacking on the beach.</para>
 
         <para>Subversion does this by keeping private caches of
           pristine versions of each versioned file inside of the
@@ -1063,7 +1066,7 @@
           much faster to send only a file's changes rather than the
           whole file to the server. At first glance, this might not
           seem that important, but imagine the repercussions if you
- try to commit a 1 line change to a 400MB file and have to
+ try to commit a one line change to a 400MB file and have to
           send the whole file to the server!</para>
     </sidebar>
 
@@ -1113,7 +1116,7 @@
 
         <listitem>
           <para>Subversion places <firstterm>conflict
- markers</firstterm> into the file, to visibly demonstrate
+ markers</firstterm> into the file to visibly demonstrate
             the overlapping areas.</para>
         </listitem>
 
Index: ./doc/book/book/ch08.xml
===================================================================
--- ./doc/book/book/ch08.xml
+++ ./doc/book/book/ch08.xml 2002-12-22 11:31:43.000000000 +1100
@@ -58,7 +58,7 @@
       <para>The resulting directory will not contain any
         <filename>.svn</filename> administrative areas, and all
         property metadata will be lost. (Hint: don't use this
- technique for backing up; it's probably better for rolling
+ technique for backing up; it's probably better for producing
         source distributions.)</para>
 
     </sect2>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Dec 22 04:51:12 2002

This is an archived mail posted to the Subversion Dev mailing list.