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