[svnbook commit] r3012 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Sun Mar 30 22:45:43 CDT 2008
Author: cmpilato
Date: Sun Mar 30 22:45:42 2008
New Revision: 3012
Log:
* src/en/book/ch07-customizing-svn.xml
Dear Chapter 7,
Enclosed are some copyedit tweaks. I received them from
O'Reilly's wonderful staff some time ago, and have finally found some
time to implement them.
Love, C-Mike
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 Sun Mar 30 22:45:42 2008
@@ -2,9 +2,9 @@
<title>Customizing Your Subversion Experience</title>
<para>Version control can be a complex subject, as much art as
- science, and offering myriad ways of getting stuff done.
- Throughout this book you've read of the various Subversion
- command-line client subcommands and the options which modify their
+ science, that offers myriad ways of getting stuff done.
+ Throughout this book, you've read of the various Subversion
+ command-line client subcommands and the options that modify their
behavior. In this chapter, we'll look into still more ways to
customize the way Subversion works for you—setting up the
Subversion runtime configuration, using external helper
@@ -27,7 +27,7 @@
controlled by the user. 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
+ for specifying these options and to use them for every
operation they perform, Subversion uses configuration files,
segregated into a Subversion configuration area.</para>
@@ -38,7 +38,7 @@
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 contain directives read by the client to
+ Emacs or vi), and that contain directives read by the client to
determine which of several optional behaviors the user
prefers.</para>
@@ -54,8 +54,8 @@
folder named <filename>Subversion</filename>, typically inside
the <filename>Application Data</filename> area of the user's
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
+ directory). However, on this platform, the exact location
+ differs from system to system and is dictated by the Windows
registry.
<footnote>
<para>The <literal>APPDATA</literal> environment variable
@@ -87,13 +87,13 @@
<para>The per-user configuration area currently contains three
files—two configuration files (<filename>config</filename> and
<filename>servers</filename>), and a <filename>README.txt</filename>
- file which describes the INI format. At the time of their
+ file, which describes the INI format. At the time of their
creation, the files contain default values for each of the
supported Subversion options, mostly commented out and grouped
with textual descriptions about how the values for the key
affect Subversion's behavior. To change a certain behavior,
you need only to load the appropriate configuration file into
- a text editor, and modify the desired option's value. If at
+ a text editor, and to modify the desired option's value. If at
any time you wish to have the default configuration settings
restored, you can simply remove (or rename) your configuration
directory and then run some innocuous <command>svn</command>
@@ -161,7 +161,7 @@
</orderedlist>
<para>Also, the Windows Registry doesn't really support the
- notion of something being <quote>commented out</quote>.
+ notion of something being <quote>commented out.</quote>
However, Subversion will ignore any option key whose name
begins with a hash (<literal>#</literal>) character. This
allows you to effectively comment out a Subversion option
@@ -169,16 +169,18 @@
simplifying the process of restoring that option.</para>
<para>The <command>svn</command> command-line client never
- attempts to write to the Windows Registry, and will not
- attempt to create a default configuration area there. You can
- create the keys you need using the <command>REGEDIT</command>
+ attempts to write to the Windows Registry and will not attempt
+ to create a default configuration area there. You can create
+ the keys you need using the <command>REGEDIT</command>
program. Alternatively, you can create a
- <filename>.reg</filename> file, and then double-click on that
- file from the Explorer shell, which will cause the data to be
- merged into your registry.</para>
+ <filename>.reg</filename> file (such as the one in <xref
+ 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>
<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
@@ -219,19 +221,18 @@
"#enable-auto-props"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
-
</programlisting>
</example>
<para>The previous example shows the contents of a
- <filename>.reg</filename> file which contains some of the most
+ <filename>.reg</filename> file, which contains some of the most
commonly used configuration options and their default values.
Note the presence of both system-wide (for network
proxy-related options) and per-user settings (editor programs
and password storage, among others). Also note that all the
options are effectively commented out. You need only to
remove the hash (<literal>#</literal>) character from the
- beginning of the option names, and set the values as you
+ beginning of the option names and set the values as you
desire.</para>
</sect2>
@@ -243,7 +244,7 @@
<!-- TODO(cmpilato): Rework and move this section to the Reference -->
<para>In this section, we will discuss the specific
- run-time configuration options that are currently supported
+ runtime configuration options that are currently supported
by Subversion.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -258,7 +259,7 @@
section is essentially a cross-reference table. The keys in
this section are the names of other sections in the file;
their values are <firstterm>globs</firstterm>—textual
- tokens which possibly contain wildcard
+ tokens that possibly contain wildcard
characters—that are compared against the hostnames of
the machine to which Subversion requests are sent.</para>
@@ -279,14 +280,14 @@
group name under the <literal>groups</literal> section. If
a match is made, Subversion then looks for a section in the
<filename>servers</filename> file whose name is the matched
- group's name. From that section it reads the actual network
+ group's name. From that section, it reads the actual network
configuration settings.</para>
<para>The <literal>global</literal> section contains the
settings that are meant for all of the servers not matched
by one of the globs under the <literal>groups</literal>
section. The options available in this section are
- exactly the same as those valid for the other server
+ exactly the same as those that are valid for the other server
sections in the file (except, of course, the special
<literal>groups</literal> section), and are as
follows:</para>
@@ -364,8 +365,8 @@
<term><literal>http-library</literal></term>
<listitem>
<para>Subversion provides a pair of repository access
- modules which understand its WebDAV network protocol.
- The original one which shipped with Subversion 1.0 is
+ modules that understand its WebDAV network protocol.
+ The original one, which shipped with Subversion 1.0, is
<literal>libsvn_ra_neon</literal> (though back then it
was called <literal>libsvn_ra_dav</literal>). Newer
Subversion versions also provide
@@ -458,14 +459,15 @@
<title>Config</title>
<para>The <filename>config</filename> file contains the rest
- of the currently available Subversion run-time options,
- those not related to networking. There are only a few
- options in use as of this writing, but they are again grouped into
- sections in expectation of future additions.</para>
+ of the currently available Subversion runtime
+ options—those not related to networking. There are
+ only a few options in use as of this writing, but they are
+ again grouped into sections in expectation of future
+ additions.</para>
<para>The <literal>auth</literal> section contains settings
related to Subversion's authentication and authorization
- against the repository. It contains:</para>
+ against the repository. It contains the following:</para>
<variablelist>
<varlistentry>
@@ -519,7 +521,7 @@
<para>This specifies the absolute path of a differencing
program, used when Subversion generates
<quote>diff</quote> output (such as when using the
- <command>svn diff</command> command). By default
+ <command>svn diff</command> command). By default,
Subversion uses an internal differencing
library—setting this option will cause it to
perform this task using an external program. See
@@ -533,7 +535,7 @@
<para>This specifies the absolute path of a three-way
differencing program. Subversion uses this program to
merge changes made by the user with those received
- from the repository. By default Subversion uses an
+ from the repository. By default, Subversion uses an
internal differencing library—setting this
option will cause it to perform this task using an
external program. See <xref
@@ -589,7 +591,7 @@
items—for example, object files that result from
a program's compilation—in this display. The
<literal>global-ignores</literal> option is a list of
- whitespace-delimited globs which describe the names of
+ whitespace-delimited globs that describe the names of
files and directories that Subversion should not
display unless they are versioned. The default value
is <literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~
@@ -599,8 +601,8 @@
<command>svn add</command> and <command>svn import</command>
commands also ignore files that match the list
when they are scanning a directory. You can override this
- behaviour for a single instance of any of these commands
- by explicitly specifying the file name, or by using
+ behavior for a single instance of any of these commands
+ 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
@@ -615,7 +617,7 @@
<para>This instructs Subversion to automatically set
properties on newly added or imported files. The
default value is <literal>no</literal>, so set this to
- <literal>yes</literal> to enable Auto-props.
+ <literal>yes</literal> to enable this feature.
The <literal>auto-props</literal> section of this file
specifies which properties are to be set on which files.</para>
</listitem>
@@ -628,7 +630,7 @@
encoding for commit log messages. It's a permanent
form of the <option>--encoding</option> option (see
<xref linkend="svn.ref.svn.sw"/>). The Subversion
- repository stores log messages in UTF-8, and assumes
+ repository stores log messages in UTF-8 and assumes
that your log message is written using your operating
system's native locale. You should specify a
different encoding if your commit messages are written
@@ -681,8 +683,8 @@
<term><literal>preserved-conflict-file-exts</literal></term>
<listitem>
<para>The value of this option is a space-delimited list
- of file extensions which Subversion should preserve
- when generating conflict file names. By default, the
+ of file extensions that Subversion should preserve
+ when generating conflict filenames. By default, the
list is empty. This option is new to Subversion
1.5.</para>
@@ -692,9 +694,9 @@
pristine copies of the various competing versions of
the file in the working copy. By default, those
conflict files have names constructed by appending to
- the original file name a custom extension such as
- <literal>.mine</literal> or
- <literal>.<replaceable>REV</replaceable></literal>
+ the original filename a custom extension such as
+ <filename>.mine</filename> or
+ <filename>.<replaceable>REV</replaceable></filename>
(where <replaceable>REV</replaceable> is a revision
number). A mild annoyance with this naming scheme is
that on operating systems where a file's extension
@@ -708,10 +710,10 @@
<filename>ReleaseNotes.pdf.r4231</filename>. While
your system might be configured to use Adobe's Acrobat
Reader to open files whose extensions are
- <literal>.pdf</literal>, there probably isn't an
+ <filename>.pdf</filename>, there probably isn't an
application configured on your system to open all
files whose extensions are
- <literal>.r4321</literal>.</para>
+ <filename>.r4321</filename>.</para>
<para>You can fix this annoyance by using this
configuration option, though. For files with one of
@@ -719,14 +721,14 @@
the conflict file names the custom extension just as
before, but then also re-append the file's original
extension. Using the previous example, and assuming
- that <literal>pdf</literal> is one of the extensions
+ that <filename>pdf</filename> 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
- <literal>.pdf</literal>, the correct default
+ <filename>.pdf</filename>, the correct default
application will be used to view them.</para>
</listitem>
</varlistentry>
@@ -734,8 +736,8 @@
<varlistentry>
<term><literal>interactive-conflicts</literal></term>
<listitem>
- <para>This is a boolean option which specifies whether
- or not Subversion should try to resolve conflicts
+ <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
the user for how to handle conflicts in the manner
@@ -749,14 +751,15 @@
<varlistentry>
<term><literal>no-unlock</literal></term>
<listitem>
- <para>This boolean option corresponds to the
- <option>--no-unlock</option> option to <command>svn
- commit</command>, which tells Subversion not to release
- locks on files you've just committed. If this runtime
- option is set to <literal>yes</literal>, Subversion will
+ <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
+ is set to <literal>yes</literal>, Subversion will
never release locks automatically, leaving you to run
- <command>svn unlock</command> explicitly. It defaults to
- <literal>no</literal>.</para>
+ <command>svn unlock</command> explicitly. It defaults
+ to <literal>no</literal>.</para>
+
</listitem>
</varlistentry>
@@ -766,7 +769,7 @@
the Subversion client's ability to automatically set
properties on files when they are added or imported.
It contains any number of key-value pairs in the
- format <literal>PATTERN = PROPNAME=PROPVALUE</literal>
+ format <literal>PATTERN = PROPNAME=PROPVALUE</literal>,
where <literal>PATTERN</literal> is a file pattern
that matches a set of filenames and the rest of the
line is the property and its value. Multiple matches
@@ -795,14 +798,14 @@
<para><firstterm>Localization</firstterm> is the act of making
programs behave in a region-specific way. When a program
formats numbers or dates in a way specific to your part of the
- world, or prints messages (or accepts input) in your native
+ 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>
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.understanding">
- <title>Understanding locales</title>
+ <title>Understanding Locales</title>
<para>Most modern operating systems have a notion of the
<quote>current locale</quote>—that is, the region or
@@ -826,6 +829,7 @@
LC_NUMERIC="C"
LC_TIME="C"
LC_ALL="C"
+$
</screen>
<para>The output is a list of locale-related environment
@@ -858,7 +862,7 @@
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.svnuse">
- <title>Subversion's use of locales</title>
+ <title>Subversion's Use of Locales</title>
<para>The Subversion client, <command>svn</command>, honors the
current locale configuration in two ways. First, it notices
@@ -911,11 +915,11 @@
<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 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
- to convert the data to UTF-8 before sending them off to the
+ to convert the data to UTF-8 before sending it off to the
repository.</para>
<para>Note that while the repository demands UTF-8 filenames and
@@ -926,7 +930,7 @@
contents.</para>
<sidebar>
- <title>Character set conversion errors</title>
+ <title>Character Set Conversion Errors</title>
<para>While using Subversion, you might get hit with an error
related to character set conversions:</para>
@@ -948,7 +952,7 @@
update</command>.</para>
<para>The solution is either to set your locale to something
- which <emphasis>can</emphasis> represent the incoming UTF-8
+ that <emphasis>can</emphasis> represent the incoming UTF-8
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
@@ -991,7 +995,7 @@
on demand.</para>
<para>Subversion supports this by allowing you to specify an
- external text editor which it will launch as necessary in order
+ external text editor that it will launch as necessary in order
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,
@@ -1053,7 +1057,7 @@
<sect1 id="svn.advanced.externaldifftools">
<title>Using External Differencing and Merge Tools</title>
- <para>The interface between Subversion and external 2- and 3-way
+ <para>The interface between Subversion and external two- and three-way
differencing tools harkens back to a time when Subversion's only
contextual differencing capabilities were built around
invocations of the GNU diffutils toolchain, specifically the
@@ -1086,19 +1090,19 @@
that program can understand those options. And that's where
things get unintuitive for most users.</para>
- <para>The key to using external 2- and 3-way differencing tools
+ <para>The key to using external two- and three-way differencing tools
(other than GNU diff and diff3, of course) with Subversion is to
- use wrapper scripts which convert the input from Subversion into
+ use wrapper scripts, which convert the input from Subversion into
something that your differencing tool can understand, and then
- to convert the output of your tool back into a format which
+ to convert the output of your tool back into a format that
Subversion expects—the format that the GNU tools would
have used. The following sections cover the specifics of those
expectations.</para>
<note>
- <para>The decision on when to fire off a contextual 2- or 3-way
+ <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
+ by Subversion and is affected by, among other things, whether
or not 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
@@ -1119,16 +1123,16 @@
runtime configuration option to find the name of an external
merge tool and, upon finding one, launch that tool with the
appropriate input files. This differs from the configurable
- 3-way differencing tool in a couple of ways. First, the
- differencing tool is always used to handle 3-way differences,
- whereas the merge tool is only employed when 3-way difference
- application has detected a conflict. Secondly, the interface is
- much cleaner—your configured merge tool need only accept
- on its command line four path specifications: the base file, the
- <quote>theirs</quote> file (which contains upstream changes),
- the <quote>mine</quote> file (which contains local
- modifications), and the path of the file where the final
- resolved contents should be stored.</para>
+ 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
+ three-way difference application has detected a conflict.
+ Secondly, 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
+ (which contains local modifications), and the path of the file
+ where the final resolved contents should be stored.</para>
<!-- =============================================================== -->
<sect2 id="svn.advanced.externaldifftools.diff">
@@ -1138,7 +1142,7 @@
suitable for the GNU diff utility, and expects only that the
external program return with a successful error code. For
most alternative diff programs, only the sixth and seventh
- arguments—the paths of the files which represent the left and
+ 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
@@ -1213,15 +1217,15 @@
<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
- the full file contents which result from the completed merge
+ 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
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,
+ files which represent the <quote>mine,</quote>
+ <quote>older,</quote> and <quote>yours</quote> inputs,
respectively, are of interest. Note that because Subversion
- depends on the output of your merge program, you wrapper
+ depends on the output of your merge program, your wrapper
script must not exit before that output has been delivered to
Subversion. When it finally does exit, it should return an
error code of 0 if the merge was successful, or 1 if unresolved
More information about the svnbook-dev
mailing list