[svnbook commit] r3012 - trunk/src/en/book
Ben Collins-Sussman
sussman at red-bean.com
Sun Mar 30 22:52:12 CDT 2008
Woot! I've only got chapter 6 left; I should get it done on Tuesday night.
On Sun, Mar 30, 2008 at 10:45 PM, cmpilato <noreply at red-bean.com> wrote:
> 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
>
> _______________________________________________
> svnbook-dev mailing list
> svnbook-dev at red-bean.com
> http://www.red-bean.com/mailman/listinfo/svnbook-dev
More information about the svnbook-dev
mailing list