[svnbook] r3933 committed - * src/en/book/ch03-advanced-topics.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Fri Jul 29 10:49:00 CDT 2011
Revision: 3933
Author: cmpilato at gmail.com
Date: Fri Jul 29 08:48:39 2011
Log: * src/en/book/ch03-advanced-topics.xml
Miscellaneous Read-thru edits.
http://code.google.com/p/svnbook/source/detail?r=3933
Modified:
/trunk/src/en/book/ch03-advanced-topics.xml
=======================================
--- /trunk/src/en/book/ch03-advanced-topics.xml Fri Jul 29 07:55:23 2011
+++ /trunk/src/en/book/ch03-advanced-topics.xml Fri Jul 29 08:48:39 2011
@@ -391,19 +391,19 @@
street. Our motorist—and our Subversion—need a
little more detail to do the right thing.</para>
- <para>In version 1.1, Subversion introduced a way for you to tell
- it exactly which Main Street you meant. It's called the
- <firstterm>peg revision</firstterm>, and it is provided to
- Subversion for the sole purpose of identifying a unique line of
- history. Because at most, one versioned object may occupy a path
+ <para>Fortunately, Subversion allow you to tell it exactly which
+ Main Street you meant. The mechanism used is called a
+ <firstterm>peg revision</firstterm>, and you provide these to
+ Subversion for the sole purpose of identifying unique lines of
+ history. Because at most one versioned object may occupy a path
at any given time—or, more precisely, in any one
revision—the combination of a path and a peg revision is
- all that is needed to refer to a specific line of history. Peg
- revisions are specified to the Subversion command-line client
- using <firstterm>at syntax</firstterm>, so called because the
- syntax involves appending an <quote>at sign</quote>
- (<literal>@</literal>) and the peg revision to the end of the
- path with which the revision is associated.</para>
+ all that is needed to unambiguously identify to a specific line
+ of history. Peg revisions are specified to the Subversion
+ command-line client using <firstterm>at syntax</firstterm>, so
+ called because the syntax involves appending an <quote>at
+ sign</quote> (<literal>@</literal>) and the peg revision to the
+ end of the path with which the revision is associated.</para>
<para>But what of the <option>--revision</option>
(<option>-r</option>) of which we've spoken so much in this
@@ -1000,9 +1000,9 @@
command will list the names of properties that exist on a
path. Once you know the names of the properties on the node,
you can request their values individually using <command>svn
- propget</command>. This command will, given a property name and a
path (or set of
- paths), print the value of the property to
- the standard output stream.</para>
+ propget</command>. This command will, given a property name
+ and a path (or set of paths), print the value of the property
+ to the standard output stream.</para>
<informalexample>
<screen>
@@ -1209,6 +1209,8 @@
(s) show all options: p
C calc/button.c
Updated to revision 143.
+Summary of conflicts:
+ Property conflicts: 1
$
</screen>
</informalexample>
@@ -1328,6 +1330,22 @@
linkend="svn.advanced.confarea.opts.config"/> for more about
configuring that support.</para>
+ <note>
+ <para>Subversion administrators commonly ask if it is possible
+ to configure, on the server side, a set of property
+ definitions which all connecting clients will automatically
+ consider when operating on working copies checked out from
+ that server. Unfortunately, Subversion doesn't offer this
+ feature. Administrators can use hook scripts to validate
+ that the properties added to and modified on files and
+ directories match the administrator's preferred policies,
+ rejecting commits which are non-compliant in this fashion.
+ (See <xref linkend="svn.reposadmin.create.hooks" /> for more
+ about hook scripts.) But there's no way to automatically
+ dictate those preferences to Subversion clients
+ beforehand.</para>
+ </note>
+
</sect2>
</sect1>
@@ -1468,12 +1486,11 @@
property.</para>
</warning>
- <para>Beginning in Subversion 1.5, users can configure a new
- <literal>mime-types-file</literal> runtime configuration
- parameter, which identifies the location of a MIME types
- mapping file. Subversion will consult this mapping file to
- determine the MIME type of newly added and imported
- files.</para>
+ <para>Users can configure the <literal>mime-types-file</literal>
+ runtime configuration parameter, which identifies the location
+ of a MIME types mapping file. Subversion will consult this
+ mapping file to determine the MIME type of newly added and
+ imported files.</para>
<para>Also, if the <literal>svn:mime-type</literal> property is
set, then the Subversion Apache module will use its value to
@@ -2221,22 +2238,19 @@
</sidebar>
- <para>Subversion 1.2 introduced a new variant of the keyword
- syntax, which brought additional, useful—though perhaps
- atypical—functionality. You can now tell Subversion
- to maintain a fixed length (in terms of the number of bytes
- consumed) for the substituted keyword. By using a
- double colon (<literal>::</literal>) after the keyword name,
- followed by a number of space characters, you define that
- fixed width. When Subversion goes to substitute your
- keyword for the keyword and its value, it will essentially
- replace only those space characters, leaving the overall
- width of the keyword field unchanged. If the substituted
- value is shorter than the defined field width, there will be
- extra padding characters (spaces) at the end of the
- substituted field; if it is too long, it is truncated with a
- special hash (<literal>#</literal>) character just before
- the final dollar sign terminator.</para>
+ <para>You can also instruct Subversion to maintain a fixed length
+ (in terms of the number of bytes consumed) for the substituted
+ keyword. By using a double colon (<literal>::</literal>) after
+ the keyword name, followed by a number of space characters, you
+ define that fixed width. When Subversion goes to substitute
+ your keyword for the keyword and its value, it will essentially
+ replace only those space characters, leaving the overall width
+ of the keyword field unchanged. If the substituted value is
+ shorter than the defined field width, there will be extra
+ padding characters (spaces) at the end of the substituted field;
+ if it is too long, it is truncated with a special hash
+ (<literal>#</literal>) character just before the final dollar
+ sign terminator.</para>
<para>For example, say you have a document in which you have
some section of tabular data reflecting the document's
@@ -2633,7 +2647,7 @@
directory except the one you don't care about it.</para>
<informalexample>
- <screen>
+ <screen>
$ svn checkout http://svn.example.com/repos/many-dirs --depth empty
…
$ svn update --set-depth infinity many-dirs/wanted-dir-1
@@ -2660,7 +2674,7 @@
one subdirectory you don't care about.</para>
<informalexample>
- <screen>
+ <screen>
$ svn checkout http://svn.example.com/repos/many-dirs
…
$ svn update --set-depth exclude many-dirs/unwanted-dir
@@ -2720,11 +2734,12 @@
how well those algorithms perform when trying to resolve
conflicts caused by multiple users modifying the same file
concurrently. Subversion itself provides only one such
- algorithm: a three-way differencing algorithm that is smart
+ algorithm: a three-way differencing algorithm that is smart
enough to handle data at a granularity of a single line of text.
Subversion also allows you to supplement its content merge
processing with external differencing utilities (as described in
- <xref linkend="svn.advanced.externaldifftools.diff3" />), some
+ <xref linkend="svn.advanced.externaldifftools.diff3" /> and
+ <xref linkend="svn.advanced.externaldifftools.merge" />), some
of which may do an even better job, perhaps providing
granularity of a word or a single character of text. But common
among those algorithms is that they generally work only on text
@@ -2734,7 +2749,7 @@
you begin to run into problems with the copy-modify-merge
model.</para>
- <para>Let's look at a real-life example of where this model runs
+ <para>Let's look at a real-life example of where this model runs
aground. Harry and Sally are both graphic designers working on
the same project, a bit of marketing collateral for an
automobile mechanic. Central to the design of a particular
@@ -2965,11 +2980,12 @@
an <emphasis>authorization</emphasis> token. The token
isn't a protected secret. In fact, a lock's unique token is
discoverable by anyone who runs <userinput>svn info
- <replaceable>URL</replaceable></userinput>. A lock token is
special only when it lives
- inside a working copy. It's proof that the lock was created
- in that particular working copy, and not somewhere else by
- some other client. Merely authenticating as the lock owner
- isn't enough to prevent accidents.</para>
+ <replaceable>URL</replaceable></userinput>. A lock token is
+ special only when it lives inside a working copy. It's
+ proof that the lock was created in that particular working
+ copy, and not somewhere else by some other client. Merely
+ authenticating as the lock owner isn't enough to prevent
+ accidents.</para>
<para>For example, suppose you lock a file using a computer at
your office, but leave work for the day before you finish
@@ -2980,8 +2996,8 @@
token prevents one piece of Subversion-related software from
undermining the work of another. (In our example, if you
really need to change the file from an alternative working
- copy, you would need to <firstterm>break</firstterm> the lock
and relock the
- file.)</para>
+ copy, you would need to <firstterm>break</firstterm> the
+ lock and relock the file.)</para>
</sidebar>
@@ -3476,19 +3492,19 @@
<informalexample>
<screen>
$ svn checkout http://svn.example.com/repos/calc
-A calc
-A calc/Makefile
-A calc/integer.c
-A calc/button.c
+A calc
+A calc/Makefile
+A calc/integer.c
+A calc/button.c
Checked out revision 148.
Fetching external item into calc/third-party/sounds
-A calc/third-party/sounds/ding.ogg
-A calc/third-party/sounds/dong.ogg
-A calc/third-party/sounds/clang.ogg
+A calc/third-party/sounds/ding.ogg
+A calc/third-party/sounds/dong.ogg
+A calc/third-party/sounds/clang.ogg
…
-A calc/third-party/sounds/bang.ogg
-A calc/third-party/sounds/twang.ogg
+A calc/third-party/sounds/bang.ogg
+A calc/third-party/sounds/twang.ogg
Checked out revision 14.
Fetching external item into calc/third-party/skins
@@ -3728,6 +3744,10 @@
fetched into the working copy, and with the letter
<literal>X</literal> when showing the working copy status.</para>
+ <!-- ### TODO: Is Subversion using 'E' in the update output to
+ ### mean "external"? Or is this 'E' an "exists" notification,
+ ### the side-effect of the file externals implementation? -->
+
<warning>
<para>While directory externals can place the external
directory at any depth, and any missing intermediate
@@ -3811,22 +3831,22 @@
<para>We've already mentioned some of the additional shortcomings
of the old <literal>svn:externals</literal> format and how the
- new Subversion 1.5 format improves upon it. But be careful when
- making use of the new format that you don't inadvertently
- introduce new problems. For example, while Subversion 1.5
- clients will continue to recognize and support the original
- externals definition format, older clients
- will <emphasis>not</emphasis> be able to correctly parse the new
- format. If you change all your externals definitions to the
- newer format, you effectively force everyone who uses those
- externals to upgrade their Subversion clients to a version that
- can parse them. Also, be careful to avoid naively relocating
+ newer Subversion 1.5 format improves upon it. But be careful
+ when making use of the new format that you don't inadvertently
+ introduce new problems. For example, while the latest clients
+ will continue to recognize and support the original externals
+ definition format, pre-1.5 clients will <emphasis>not</emphasis>
+ be able to correctly parse the new format. If you change all
+ your externals definitions to the newer format, you effectively
+ force everyone who uses those externals to upgrade their
+ Subversion clients to a version that can parse them. Also, be
+ careful to avoid naively relocating
the <literal>-r<replaceable>NNN</replaceable></literal> portion
- of the definition—the older format uses that revision as
- a peg revision, but the newer format uses it as an operative
+ of the definition—the older format uses that revision as a
+ peg revision, but the newer format uses it as an operative
revision (with a peg revision of <literal>HEAD</literal> unless
- otherwise specified; see <xref linkend="svn.advanced.pegrevs"
- /> for a full explanation of the distinction here).</para>
+ otherwise specified; see <xref linkend="svn.advanced.pegrevs" />
+ for a full explanation of the distinction here).</para>
<warning>
<para>External working copies are still completely
@@ -3896,10 +3916,10 @@
degree, the details of the changes being made heavily influence
the methodology used to distinguish them.</para>
- <para>Subversion 1.5 brings a new
- <firstterm>changelists</firstterm> feature that adds yet
- another method to the mix. Changelists are basically arbitrary
- labels (currently at most one per file) applied to working copy
files for the express purpose of
+ <para>Subversion provides a <firstterm>changelists</firstterm>
+ feature that adds yet another method to the mix. Changelists
+ are basically arbitrary labels (currently at most one per file)
+ applied to working copy files for the express purpose of
associating multiple files together. Users of many of Google's
software offerings are familiar with this concept already. For
example, <ulink url="http://mail.google.com/">Gmail</ulink>
More information about the svnbook-dev
mailing list