[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