[svnbook commit] r3219 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Mon Jul 28 22:24:02 CDT 2008
Author: cmpilato
Date: Mon Jul 28 22:24:02 2008
New Revision: 3219
Log:
Enter more O'Reilly second-round copyedits.
Modified:
trunk/src/en/book/ch07-customizing-svn.xml
Modified: trunk/src/en/book/ch07-customizing-svn.xml
==============================================================================
--- trunk/src/en/book/ch07-customizing-svn.xml (original)
+++ trunk/src/en/book/ch07-customizing-svn.xml Mon Jul 28 22:24:02 2008
@@ -23,8 +23,8 @@
<sect1 id="svn.advanced.confarea">
<title>Runtime Configuration Area</title>
- <para>Subversion provides many optional behaviors that can be
- controlled by the user. Many of these options are of the kind
+ <para>Subversion provides many optional behaviors that the user can
+ control. Many of these options are of the kind
that a user would wish to apply to all Subversion operations.
So, rather than forcing users to remember command-line arguments
for specifying these options and to use them for every
@@ -36,9 +36,9 @@
Usually, this boils down to a special directory that contains
<firstterm>configuration files</firstterm> (the first tier),
which are just text files in standard INI format (with
- <quote>sections</quote> providing the second tier). These files
- can be easily edited using your favorite text editor (such as
- Emacs or vi), and that contain directives read by the client to
+ <quote>sections</quote> providing the second tier). You can
+ easily edit these files using your favorite text editor (such as
+ Emacs or vi), and they contain directives read by the client to
determine which of several optional behaviors the user
prefers.</para>
@@ -46,7 +46,7 @@
<sect2 id="svn.advanced.confarea.layout">
<title>Configuration Area Layout</title>
- <para>The first time that the <command>svn</command>
+ <para>The first time the <command>svn</command>
command-line client is executed, it creates a per-user
configuration area. On Unix-like systems, this area appears
as a directory named <filename>.subversion</filename> in the
@@ -56,7 +56,7 @@
profile directory (which, by the way, is usually a hidden
directory). However, on this platform, the exact location
differs from system to system and is dictated by the Windows
- registry.
+ Registry.
<footnote>
<para>The <literal>APPDATA</literal> environment variable
points to the <filename>Application Data</filename> area,
@@ -70,7 +70,7 @@
also recognizes the existence of a system-wide configuration
area. This gives system administrators the ability to
establish defaults for all users on a given machine. Note
- that the system-wide configuration area does not alone dictate
+ that the system-wide configuration area alone does not dictate
mandatory policy—the settings in the per-user
configuration area override those in the system-wide one, and
command-line arguments supplied to the <command>svn</command>
@@ -117,12 +117,12 @@
<para>In addition to the usual INI-based configuration area,
Subversion clients running on Windows platforms may also use
- the Windows registry to hold the configuration data. The
+ the Windows Registry to hold the configuration data. The
option names and their values are the same as in the INI
files. The <quote>file/section</quote> hierarchy is
preserved as well, though addressed in a slightly different
fashion—in this schema, files and sections are just
- levels in the registry key tree.</para>
+ levels in the Registry key tree.</para>
<para>Subversion looks for system-wide configuration values
under the
@@ -137,7 +137,7 @@
<para>Registry-based configuration options are parsed
<emphasis>before</emphasis> their file-based counterparts, so
- are overridden by values found in the configuration files. In
+ they are overridden by values found in the configuration files. In
other words, Subversion looks for configuration information in
the following locations on a Windows system; lower-numbered
locations take precedence over higher-numbered locations:</para>
@@ -177,10 +177,10 @@
linkend="svn.advanced.confarea.windows-registry.ex-1" />), and
then double-click on that file's icon in the Explorer shell,
which will cause the data to be merged into your
- registry.</para>
+ Registry.</para>
<example id="svn.advanced.confarea.windows-registry.ex-1">
- <title>Sample registration entries (.reg) file.</title>
+ <title>Sample registration entries (.reg) file</title>
<programlisting>
REGEDIT4
@@ -244,8 +244,8 @@
<!-- TODO(cmpilato): Rework and move this section to the Reference -->
<para>In this section, we will discuss the specific
- runtime configuration options that are currently supported
- by Subversion.</para>
+ runtime configuration options that Subversion currently
+ supports.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.advanced.confarea.opts.servers">
@@ -352,10 +352,10 @@
<varlistentry>
<term><literal>http-compression</literal></term>
<listitem>
- <para>This specifies whether or not Subversion should
+ <para>This specifies whether Subversion should
attempt to compress network requests made to DAV-ready
servers. The default value is <literal>yes</literal>
- (though compression will only occur if that capability
+ (though compression will occur only if that capability
is compiled into the network layer). Set this to
<literal>no</literal> to disable compression, such as
when debugging network transmissions.</para>
@@ -446,7 +446,7 @@
passphrase whenever the certificate is used. If you
find this annoying (and don't mind storing the
password in the <filename>servers</filename> file),
- then you can set this variable to the certificate's
+ you can set this variable to the certificate's
passphrase. You won't be prompted anymore.</para>
</listitem>
</varlistentry>
@@ -491,7 +491,7 @@
<listitem>
<para>This setting is the same as
<literal>store-passwords</literal>, except that it
- enables or disables disk-caching of
+ enables or disables on-disk caching of
<emphasis>all</emphasis> authentication information:
usernames, passwords, server certificates, and any
other types of cacheable credentials.</para>
@@ -586,7 +586,7 @@
command, Subversion lists unversioned files and
directories along with the versioned ones, annotating
them with a <literal>?</literal> character (see <xref
- linkend="svn.tour.cycle.examine.status" />). Sometimes, it can
+ linkend="svn.tour.cycle.examine.status" />). Sometimes it can
be annoying to see uninteresting, unversioned
items—for example, object files that result from
a program's compilation—in this display. The
@@ -605,7 +605,7 @@
by explicitly specifying the filename, or by using
the <option>--no-ignore</option> command-line flag.</para>
- <para>For information on more fine-grained control of
+ <para>For information on finer-grained control of
ignored items, see
<xref linkend="svn.advanced.props.special.ignore" />.</para>
</listitem>
@@ -643,7 +643,7 @@
<listitem>
<para>Normally your working copy files have timestamps
that reflect the last time they were touched by any
- process, whether that be your own editor or by some
+ process, whether your own editor or some
<command>svn</command> subcommand. This is generally
convenient for people developing software, because
build systems often look at timestamps as a way of
@@ -689,7 +689,7 @@
1.5.</para>
<para>When Subversion detects conflicting file content
- changes, it defers resolution of that conflict to the
+ changes, it defers resolution of those conflicts to the
user. To assist in the resolution, Subversion keeps
pristine copies of the various competing versions of
the file in the working copy. By default, those
@@ -719,15 +719,15 @@
configuration option, though. For files with one of
the specified extensions, Subversion will append to
the conflict file names the custom extension just as
- before, but then also re-append the file's original
+ before, but then also reappend the file's original
extension. Using the previous example, and assuming
- that <filename>pdf</filename> is one of the extensions
+ that <literal>pdf</literal> is one of the extensions
configured in this list thereof, the conflict files
generated for <filename>ReleaseNotes.pdf</filename>
would instead be named
<filename>ReleaseNotes.pdf.mine.pdf</filename> and
<filename>ReleaseNotes.pdf.r4231.pdf</filename>.
- Because each of these files end in
+ Because each file ends in
<filename>.pdf</filename>, the correct default
application will be used to view them.</para>
</listitem>
@@ -736,7 +736,7 @@
<varlistentry>
<term><literal>interactive-conflicts</literal></term>
<listitem>
- <para>This is a boolean option that specifies whether
+ <para>This is a Boolean option that specifies whether
Subversion should try to resolve conflicts
interactively. If its value is <literal>yes</literal>
(which is the default value), Subversion will prompt
@@ -751,7 +751,7 @@
<varlistentry>
<term><literal>no-unlock</literal></term>
<listitem>
- <para>This boolean option corresponds to <command>svn
+ <para>This Boolean option corresponds to <command>svn
commit</command>'s <option>--no-unlock</option>
option, which tells Subversion not to release locks on
files you've just committed. If this runtime option
@@ -801,7 +801,7 @@
world or prints messages (or accepts input) in your native
language, the program is said to
be <firstterm>localized</firstterm>. This section describes
- steps Subversion has made towards localization.</para>
+ steps Subversion has made toward localization.</para>
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.understanding">
@@ -838,11 +838,11 @@
locale, but users can set these variables to specific
country/language code combinations. For example, if one were
to set the <literal>LC_TIME</literal> variable to
- <literal>fr_CA</literal>, then programs would know to present
- time and date information formatted according a
+ <literal>fr_CA</literal>, programs would know to present
+ time and date information formatted according to a
French-speaking Canadian's expectations. And if one were to
set the <literal>LC_MESSAGES</literal> variable to
- <literal>zh_TW</literal>, then programs would know to present
+ <literal>zh_TW</literal>, programs would know to present
human-readable messages in Traditional Chinese. Setting the
<literal>LC_ALL</literal> variable has the effect of changing
every locale variable to the same value. The value of
@@ -893,7 +893,7 @@
on Windows they're often found in the
<filename>\share\locale\</filename> folder in Subversion's
installation area. Once installed, a module is named after
- the program it provides translations for. For example, the
+ the program for which it provides translations. For example, the
<filename>de.mo</filename> file may ultimately end up
installed as
<filename>/usr/share/locale/de/LC_MESSAGES/subversion.mo</filename>.
@@ -909,13 +909,13 @@
repository is ready to accept input in any human language.
This means, however, that the Subversion client is responsible
for sending only UTF-8 filenames and log messages into the
- repository. In order to do this, it must convert the data
+ repository. To do this, it must convert the data
from the native locale into UTF-8.</para>
<para>For example, suppose you create a file named
<filename>caffè.txt</filename>, and then when committing the
file, you write the log message as <quote>Adesso il caffè è
- più forte.</quote> Both the filename and log message contain
+ più forte.</quote> Both the filename and the log message contain
non-ASCII characters, but because your locale is set to
<literal>it_IT</literal>, the Subversion client knows to
interpret them as Italian. It uses an Italian character set
@@ -942,7 +942,7 @@
…
</screen>
- <para>Errors like this typically occur when the Subversion
+ <para>Errors such as this typically occur when the Subversion
client has received a UTF-8 string from the repository, but
not all of the characters in that string can be represented
using the encoding of the current locale. For example, if
@@ -956,7 +956,7 @@
data, or to change the filename or log message in the
repository. (And don't forget to slap your collaborator's
hand—projects should decide on common languages ahead of
- time, so that all participants are using the same
+ time so that all participants are using the same
locale.)</para>
</sidebar>
@@ -972,8 +972,8 @@
<para>The most obvious way to get data into Subversion is through
the addition of files to version control, committing changes to
- those files, and so on. But there are other pieces of
- information besides merely versioned file data that live in your
+ those files, and so on. But other pieces of
+ information besides merely versioned file data live in your
Subversion repository. Some of these bits of
information—commit log messages, lock comments, and some
property values—tend to be textual in nature and are
@@ -995,7 +995,7 @@
on demand.</para>
<para>Subversion supports this by allowing you to specify an
- external text editor that it will launch as necessary in order
+ external text editor that it will launch as necessary
to give you a more powerful input mechanism for this textual
metadata. There are several ways to tell Subversion which
editor you'd like use. Subversion checks the following things,
@@ -1027,7 +1027,7 @@
<para>The value of any of these options or variables is the
beginning of a command line to be executed by the shell.
Subversion appends to that command line a space and the pathname
- of a temporary file to be edited. So, in order to be used with
+ of a temporary file to be edited. So, to be used with
Subversion, the configured or specified editor needs to support
an invocation in which its last command-line parameter is a file
to be edited, and it should be able to save the file in place
@@ -1037,7 +1037,7 @@
messages to any of the committing subcommands (such as
<command>svn commit</command> or <command>import</command>,
<command>svn mkdir</command> or <command>delete</command> when
- provided a URL target, and so on), and Subversion will try to
+ provided a URL target, etc.), and Subversion will try to
launch the editor automatically if you don't specify either of
the <option>--message</option> (<option>-m</option>) or
<option>--file</option> (<option>-F</option>) options. The
@@ -1068,7 +1068,7 @@
later, Subversion grew its own internal differencing library,
and as a failover mechanism, the <option>--diff-cmd</option> and
<option>--diff3-cmd</option> options were added to the
- Subversion command-line client so users could more easily
+ Subversion command-line client so that users could more easily
indicate that they preferred to use the GNU diff and diff3
utilities instead of the newfangled internal diff library. If
those options were used, Subversion would simply ignore the
@@ -1085,8 +1085,8 @@
members of the GNU diffutils toolchain. But the only
configurable aspect of using those external tools is their
location on the system—not the option set, parameter
- order, etc. Subversion continues throwing all those GNU utility
- options at your external diff tool regardless of whether or not
+ order, and so on. Subversion continues to throw all those GNU utility
+ options at your external diff tool regardless of whether
that program can understand those options. And that's where
things get unintuitive for most users.</para>
@@ -1103,11 +1103,11 @@
<para>The decision on when to fire off a contextual two- or three-way
diff as part of a larger Subversion operation is made entirely
by Subversion and is affected by, among other things, whether
- or not the files being operated on are human-readable as
+ the files being operated on are human-readable as
determined by their <literal>svn:mime-type</literal> property.
This means, for example, that even if you had the niftiest
Microsoft Word-aware differencing or merging tool in the
- Universe, it would never be invoked by Subversion so long as
+ universe, it would never be invoked by Subversion as long as
your versioned Word documents had a configured MIME type that
denoted that they were not human-readable (such as
<literal>application/msword</literal>). For more about MIME
@@ -1117,17 +1117,17 @@
<para>Subversion 1.5 introduces interactive resolution of
conflicts (described in <xref linkend="svn.tour.cycle.resolve"
- />), and one of the options provided to users is the ability
+ />), and one of the options provided to users is the ability to
launch a third-party merge tool. If this action is taken,
Subversion will consult the <literal>merge-tool-cmd</literal>
runtime configuration option to find the name of an external
- merge tool and, upon finding one, launch that tool with the
+ merge tool and, upon finding one, will launch that tool with the
appropriate input files. This differs from the configurable
three-way differencing tool in a couple of ways. First, the
differencing tool is always used to handle three-way
- differences, whereas the merge tool is only employed when
+ differences, whereas the merge tool is employed only when
three-way difference application has detected a conflict.
- Secondly, the interface is much cleaner—your configured
+ Second, the interface is much cleaner—your configured
merge tool need only accept as command-line parameters four path
specifications: the base file, the <quote>theirs</quote> file
(which contains upstream changes), the <quote>mine</quote> file
@@ -1140,13 +1140,13 @@
<para>Subversion calls external diff programs with parameters
suitable for the GNU diff utility, and expects only that the
- external program return with a successful error code. For
+ external program will return with a successful error code. For
most alternative diff programs, only the sixth and seventh
arguments—the paths of the files that represent the left and
right sides of the diff, respectively—are of interest. Note
that Subversion runs the diff program once per modified file
covered by the Subversion operation, so if your program runs
- in an asynchronous fashion (or <quote>backgrounded</quote>),
+ in an asynchronous fashion (or is <quote>backgrounded</quote>),
you might have several instances of it all running
simultaneously. Finally, Subversion expects that your program
return an error code of 1 if your program detected differences,
@@ -1174,7 +1174,7 @@
# Configure your favorite diff program here.
DIFF = "/usr/local/bin/my-diff-tool"
-# Subversion provides the paths we need as last two parameters.
+# Subversion provides the paths we need as the last two parameters.
LEFT = sys.argv[-2]
RIGHT = sys.argv[-1]
@@ -1196,7 +1196,7 @@
REM Configure your favorite diff program here.
SET DIFF="C:\Program Files\Funky Stuff\My Diff Tool.exe"
-REM Subversion provides the paths we need as last two parameters.
+REM Subversion provides the paths we need as that last two parameters.
REM These are parameters 6 and 7 (unless you use svn diff -x, in
REM which case, all bets are off).
SET LEFT=%6
@@ -1218,11 +1218,11 @@
<para>Subversion calls external merge programs with parameters
suitable for the GNU diff3 utility, expecting that the
- external program return with a successful error code and that
+ external program will return with a successful error code and that
the full file contents that result from the completed merge
operation are printed on the standard output stream (so that
- Subversion can redirect them into the appropriate version
- controlled file). For most alternative merge programs, only
+ Subversion can redirect them into the appropriate version-controlled
+ file). For most alternative merge programs, only
the ninth, tenth, and eleventh arguments, the paths of the
files which represent the <quote>mine,</quote>
<quote>older,</quote> and <quote>yours</quote> inputs,
@@ -1275,7 +1275,7 @@
SET DIFF3="C:\Program Files\Funky Stuff\My Merge Tool.exe"
REM Subversion provides the paths we need as last three parameters.
-REM These are parameters 9, 10, and 11. But we only have access to
+REM These are parameters 9, 10, and 11. But we have access to only
REM nine parameters at a time, so we shift our nine-parameter window
REM twice to let us get to what we need.
SHIFT
@@ -1298,6 +1298,30 @@
</sect2>
</sect1>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.customization.summary">
+ <title>Summary</title>
+
+ <para>Sometimes there's a single right way to do things; sometimes
+ there are many. Subversion's developers understand that while
+ the majority of its exact behaviors are acceptable to most of
+ its users, there are some corners of its functionality where
+ such a universally pleasing approach doesn't exist. In those
+ places, Subversion offers users the opportunity to tell it how
+ <emphasis>they</emphasis> want it to behave.</para>
+
+ <para>In this chapter, we explored Subversion's runtime
+ configuration system and other mechanisms by which users can
+ control those configurable behaviors. If you are a developer,
+ though, the next chapter will take you one step further. It
+ will discuss how you can further customize your Subversion
+ experience by writing your own software against Subversion's
+ libraries.</para>
+
+ </sect1>
+
</chapter>
<!--
More information about the svnbook-dev
mailing list