[svnbook commit] r2988 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Tue Mar 4 21:14:53 CST 2008
Author: cmpilato
Date: Tue Mar 4 21:14:52 2008
New Revision: 2988
Log:
Begin making copyedit changes suggested by O'Reilly. Love the
results, but the process is putting a crick in my neck!
Modified:
trunk/src/en/book/ch03-advanced-topics.xml
Modified: trunk/src/en/book/ch03-advanced-topics.xml
==============================================================================
--- trunk/src/en/book/ch03-advanced-topics.xml (original)
+++ trunk/src/en/book/ch03-advanced-topics.xml Tue Mar 4 21:14:52 2008
@@ -8,13 +8,13 @@
check out a working copy from a Subversion repository. You are
comfortable with submitting and receiving changes using the
<command>svn commit</command> and <command>svn update</command>
- functions. You've probably even developed a reflex which causes
+ functions. You've probably even developed a reflex that causes
you to run the <command>svn status</command> command almost
unconsciously. For all intents and purposes, you are ready to
use Subversion in a typical environment.</para>
<para>But the Subversion feature set doesn't stop at <quote>common
- version control operations</quote>. It has other bits of
+ version control operations.</quote> It has other bits of
functionality besides just communicating file and
directory changes to and from a central repository.</para>
@@ -24,7 +24,7 @@
directory versioning capabilities. If you aren't, you'll want to
first read <xref linkend="svn.basic" /> and <xref
linkend="svn.tour" />. Once you've mastered those basics and
- consumed this chapter, you'll be a Subversion power-user!</para>
+ consumed this chapter, you'll be a Subversion power user!</para>
<!-- ================================================================= -->
@@ -33,26 +33,26 @@
<sect1 id="svn.tour.revs.specifiers">
<title>Revision Specifiers</title>
- <para>As you saw in <xref linkend="svn.basic.in-action.revs" />, revision
- numbers in Subversion are pretty straightforward—integers
- that keep getting larger as you commit more changes to your
- versioned data. Still, it doesn't take long before you can no
- longer remember exactly what happened in each and every
- revision. Fortunately, the typical Subversion workflow doesn't
- often demand that you supply arbitrary revisions to the
- Subversion operations you perform. For operations that
- <emphasis>do</emphasis> require a revision specifier, you
- generally supply a revision number that you saw in a commit
- email, in the output of some other Subversion operation, or in
- some other context that would give meaning to that particular
- number.</para>
+ <para>As we described in <xref linkend="svn.basic.in-action.revs"
+ />, revision numbers in Subversion are pretty
+ straightforward—integers that keep getting larger as you
+ commit more changes to your versioned data. Still, it doesn't
+ take long before you can no longer remember exactly what
+ happened in each and every revision. Fortunately, the typical
+ Subversion workflow doesn't often demand that you supply
+ arbitrary revisions to the Subversion operations you perform.
+ For operations that <emphasis>do</emphasis> require a revision
+ specifier, you generally supply a revision number that you saw
+ in a commit email, in the output of some other Subversion
+ operation, or in some other context that would give meaning to
+ that particular number.</para>
<para>But occasionally, you need to pinpoint a moment in time for
which you don't already have a revision number memorized or
handy. So besides the integer revision numbers,
<command>svn</command> allows as input some additional forms of
- revision specifiers—<firstterm>revision keywords</firstterm>, and revision
- dates.</para>
+ revision specifiers: <firstterm>revision keywords</firstterm>
+ and revision dates.</para>
<note>
<para>The various forms of Subversion revision specifiers can be
@@ -89,16 +89,16 @@
<primary>PREV</primary>
</indexterm>
- <para>The Subversion client understands a number of
- revision keywords. These keywords can
- be used instead of integer arguments to the
- <option>--revision (-r)</option> switch, and are resolved into
- specific revision numbers by Subversion:</para>
+ <para>The Subversion client understands a number of revision
+ keywords. These keywords can be used instead of integer
+ arguments to the <option>--revision</option>
+ (<option>-r</option>) switch, and are resolved into specific
+ revision numbers by Subversion:</para>
<variablelist>
<varlistentry>
- <term>HEAD</term>
+ <term><literal>HEAD</literal></term>
<listitem>
<para>The latest (or <quote>youngest</quote>) revision in
the repository.</para>
@@ -106,17 +106,17 @@
</varlistentry>
<varlistentry>
- <term>BASE</term>
+ <term><literal>BASE</literal></term>
<listitem>
<para>The revision number of an item in a working copy.
- If the item has been locally modified, the <quote>BASE
- version</quote> refers to the way the item appears
- without those local modifications.</para>
+ If the item has been locally modified, this refers to
+ the way the item appears without those local
+ modifications.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>COMMITTED</term>
+ <term><literal>COMMITTED</literal></term>
<listitem>
<para>The most recent revision prior to, or equal to,
<literal>BASE</literal>, in which an item changed.</para>
@@ -124,7 +124,7 @@
</varlistentry>
<varlistentry>
- <term>PREV</term>
+ <term><literal>PREV</literal></term>
<listitem>
<para>The revision immediately <emphasis>before</emphasis>
the last revision in which an item changed.
@@ -187,13 +187,13 @@
<para>Revision numbers reveal nothing about the world outside
the version control system, but sometimes you need to
correlate a moment in real time with a moment in version
- history. To facilitate this, the <option>--revision (-r)</option>
- option can also accept as input date specifiers wrapped in
- curly braces (<literal>{</literal> and <literal>}</literal>).
- Subversion accepts the standard ISO-8601 date and time
- formats, plus a few others. Here are some examples.
- (Remember to use quotes around any date that contains
- spaces.)</para>
+ history. To facilitate this, the <option>--revision</option>
+ (<option>-r</option>) option can also accept as input date
+ specifiers wrapped in curly braces (<literal>{</literal> and
+ <literal>}</literal>). Subversion accepts the standard
+ ISO-8601 date and time formats, plus a few others. Here are
+ some examples. (Remember to use quotes around any date that
+ contains spaces.)</para>
<screen>
$ svn checkout -r {2006-02-17}
@@ -233,10 +233,10 @@
the 26th, or even earlier. Remember that Subversion will
find the <emphasis>most recent revision of the
repository</emphasis> as of the date you give. If you give
- a date without a timestamp, like
+ a date without a timestamp, such as
<literal>2006-11-27</literal>, Subversion assumes a time of
00:00:00, so looking for the most recent revision won't
- return anything on the day of the 27th.</para>
+ return anything on the 27th.</para>
<para>If you want to include the 27th in your search, you can
either specify the 27th with the time (<literal>{"2006-11-27
@@ -256,7 +256,7 @@
<warning>
<para>Since the timestamp of a revision is stored as an
unversioned, modifiable property of the revision (see <xref
- linkend="svn.advanced.props" />, revision timestamps can be
+ linkend="svn.advanced.props" />), revision timestamps can be
changed to represent complete falsifications of true
chronology, or even removed altogether. Subversion's
ability to correctly convert revision dates into real
@@ -325,29 +325,29 @@
apply—human-readable names and anything-you-want binary
values. The main difference is that revision properties are not
versioned. In other words, if you change the value of, or
- delete, a revision property, there's no way within the scope of
- Subversion's functionality to recover the previous value.</para>
+ delete, a revision property, there's no way, within the scope of
+ Subversion's functionality, to recover the previous value.</para>
<para>Subversion has no particular policy regarding the use of
properties. It asks only that you not use property names that
begin with the prefix <literal>svn:</literal>. That's the
namespace that it sets aside for its own use. And Subversion
- does, in fact, use properties, both the versioned and
+ does, in fact, use properties—both the versioned and
unversioned variety. Certain versioned properties have special
- meaning or effects when found on files and directories, or house
- a particular bit of information about the revisions on which
- they are found. Certain revision properties are automatically
- attached to revisions by Subversion's commit process, and carry
- information about the revision. Most of these properties are
- mentioned elsewhere in this or other chapters as part of the
- more general topics to which they are related. For an
- exhaustive list of Subversion's pre-defined properties, see
- <xref linkend="svn.ref.properties"/>.</para>
+ meaning or effects when found on files and directories, or they
+ house a particular bit of information about the revisions on
+ which they are found. Certain revision properties are
+ automatically attached to revisions by Subversion's commit
+ process, and they carry information about the revision. Most of
+ these properties are mentioned elsewhere in this or other
+ chapters as part of the more general topics to which they are
+ related. For an exhaustive list of Subversion's predefined
+ properties, see <xref linkend="svn.ref.properties" />.</para>
<para>In this section, we will examine the utility—both to
- users of Subversion, and to Subversion itself—of property
+ users of Subversion and to Subversion itself—of property
support. You'll learn about the property-related
- <command>svn</command> subcommands, and how property
+ <command>svn</command> subcommands and how property
modifications affect your normal Subversion workflow.</para>
<!-- =============================================================== -->
@@ -361,8 +361,8 @@
close to your versioned data to hang custom metadata about
that data.</para>
- <para>Say you wish to design a website that houses many digital
- photos, and displays them with captions and a datestamp. Now,
+ <para>Say you wish to design a web site that houses many digital
+ photos and displays them with captions and a datestamp. Now,
your set of photos is constantly changing, so you'd like to
have as much of this site automated as possible. These photos
can be quite large, so as is common with sites of this nature,
@@ -372,30 +372,29 @@
<para>Now, you can get this functionality using traditional
files. That is, you can have your
<filename>image123.jpg</filename> and an
- <filename>image123-thumbnail.jpg</filename> side-by-side in a
+ <filename>image123-thumbnail.jpg</filename> side by side in a
directory. Or if you want to keep the filenames the same, you
- might have your thumbnails in a different directory, like
+ might have your thumbnails in a different directory, such as
<filename>thumbnails/image123.jpg</filename>. You can also
store your captions and datestamps in a similar fashion, again
separated from the original image file. But the problem here
- is that your collection of files grows in multiples with each
- new photo added to the site.</para>
+ is that your collection of files multiplies with each new
+ photo added to the site.</para>
- <para>Now consider the same website deployed in a way that makes
- use of Subversion's file properties. Imagine having a single
- image file, <filename>image123.jpg</filename>, and then
- properties set on that file named <literal>caption</literal>,
- <literal>datestamp</literal>, and even
- <literal>thumbnail</literal>. Now your working copy directory
- looks much more manageable—in fact, it looks to the
- casual browser like there are nothing but image files in it.
- But your automation scripts know better. They know that they
- can use <command>svn</command> (or better yet, they can use
- the Subversion language bindings—see <xref
- linkend="svn.developer.usingapi" />) to dig out the
- extra information that your site needs to display without
- having to read an index file or play path manipulation
- games.</para>
+ <para>Now consider the same web site deployed in a way that
+ makes use of Subversion's file properties. Imagine having a
+ single image file, <filename>image123.jpg</filename>, with
+ properties set on that file that are named
+ <literal>caption</literal>, <literal>datestamp</literal>, and
+ even <literal>thumbnail</literal>. Now your working copy
+ directory looks much more manageable—in fact, it looks
+ to the casual browser like there are nothing but image files
+ in it. But your automation scripts know better. They know
+ that they can use <command>svn</command> (or better yet, they
+ can use the Subversion language bindings—see <xref
+ linkend="svn.developer.usingapi" />) to dig out the extra
+ information that your site needs to display without having to
+ read an index file or play path manipulation games.</para>
<para>Custom revision properties are also frequently used. One
common such use is a property whose value contains an issue
@@ -405,7 +404,7 @@
more friendly names on the revision—it might be hard to
remember that revision 1935 was a fully tested revision. But
if there's, say, a <literal>test-results</literal> property on
- that revision with a value <literal>all passing</literal>,
+ that revision with the value <literal>all passing</literal>,
that's meaningful information to have.</para>
<sidebar>
@@ -414,8 +413,8 @@
<para>For all their utility, Subversion properties—or,
more accurately, the available interfaces to them—have
- a major shortcoming:
- while it is a simple matter to <emphasis>set</emphasis> a custom property,
+ a major shortcoming: while it is a simple matter to
+ <emphasis>set</emphasis> a custom property,
<emphasis>finding</emphasis> that property later is whole
different ball of wax.</para>
@@ -433,12 +432,12 @@
repository.</para>
<para>For this reason, you might choose—especially in
- the revision property use-case—to simply add your
- metadata to the revision's log message, using some
- policy-driven (and perhaps programmatically-enforced)
+ the revision property use case—to simply add your
+ metadata to the revision's log message using some
+ policy-driven (and perhaps programmatically enforced)
formatting that is designed to be quickly parsed from the
output of <command>svn log</command>. It is quite common to
- see in Subversion log messages the likes of:</para>
+ see the following in Subversion log messages:</para>
<programlisting>
Issue(s): IZ2376, IZ1919
@@ -466,7 +465,7 @@
with short, human-readable values, perhaps the simplest way to
add a new property is to specify the property name and value
on the command line of the <command>propset</command>
- subcommand.</para>
+ subcommand:</para>
<screen>
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c
@@ -479,8 +478,9 @@
have a multi-line textual, or even binary, property value, you
probably do not want to supply that value on the command line.
So the <command>propset</command> subcommand takes a
- <option>--file (-F)</option> option for specifying the name of
- a file which contains the new property value.</para>
+ <option>--file</option> (<option>-F</option>) option for
+ specifying the name of a file that contains the new property
+ value.</para>
<screen>
$ svn propset license -F /path/to/LICENSE calc/button.c
@@ -508,7 +508,7 @@
modify properties. When you run the command,
<command>svn</command> invokes your editor program on a
temporary file that contains the current value of the property
- (or which is empty, if you are adding a new property). Then,
+ (or that is empty, if you are adding a new property). Then,
you just modify that value in your editor program until it
represents the new value you wish to store for the property,
save the temporary file, and then exit the editor program. If
@@ -527,7 +527,7 @@
subcommands, those related to properties can act on multiple
paths at once. This enables you to modify properties on whole
sets of files with a single command. For example, we could
- have done:</para>
+ have done the following:</para>
<screen>
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
@@ -614,7 +614,7 @@
<para>Remember those unversioned revision properties? You can
modify those, too, using the same <command>svn</command>
subcommands that we just described. Simply add the
- <option>--revprop</option> command-line parameter, and specify
+ <option>--revprop</option> command line parameter and specify
the revision whose property you wish to modify. Since
revisions are global, you don't need to specify a target path
to these property-related commands so long as you are
@@ -665,7 +665,7 @@
propedit</command> instead of <command>svn
propset</command>. While the end result of the commands is
identical, the former will allow them to see the current
- value of the property they are about to change, which helps
+ value of the property that they are about to change, which helps
them to verify that they are, in fact, making the change
they think they are making. This is especially true when
modifying unversioned revision properties. Also, it is
@@ -688,12 +688,12 @@
merging—cleanly or with conflicts—someone
else's modifications into your own.</para>
- <para>And as with file contents, your property changes are local
- modifications, only made permanent when you commit them to the
+ <para>As with file contents, your property changes are local
+ modifications, made permanent only when you commit them to the
repository with <command>svn commit</command>. Your property
changes can be easily unmade, too—the <command>svn
revert</command> command will restore your files and
- directories to their un-edited states—contents, properties,
+ directories to their unedited states—contents, properties,
and all. Also, you can receive interesting information about
the state of your file and directory properties by using the
<command>svn status</command> and <command>svn diff</command>
@@ -739,7 +739,7 @@
<para>Subversion will also create, in the same directory as
the conflicted object, a file with a
- <filename>.prej</filename> extension which contains the
+ <filename>.prej</filename> extension that contains the
details of the conflict. You should examine the contents of
this file so you can decide how to resolve the conflict.
Until the conflict is resolved, you will see a
@@ -764,7 +764,7 @@
</sidebar>
- <para>You might also have noticed the non-standard way that
+ <para>You might also have noticed the nonstandard way that
Subversion currently displays property differences. You can
still run <command>svn diff</command> and redirect the output
to create a usable patch file. The <command>patch</command>
@@ -801,8 +801,8 @@
Subversion will automatically set the
<literal>svn:executable</literal> property on newly added or
imported files whose execute bit is enabled. (See <xref
- linkend="svn.advanced.props.special.executable" /> for more
- about this property.)</para>
+ linkend="svn.advanced.props.special.executable" /> later in
+ this chapter for more about this property.)</para>
<para>Secondly, Subversion tries to determine the file's MIME
type. If you've configured a
@@ -813,8 +813,8 @@
<literal>svn:mime-type</literal> property to the MIME type it
found. If no mapping file is configured, or no mapping for
your file's extension could be found, Subversion runs a very
- basic heuristic to determine if the file contains non-textual
- content and, if so, automatically sets the
+ basic heuristic to determine if the file contains nontextual
+ content. If so, it automatically sets the
<literal>svn:mime-type</literal> property on that file to
<literal>application/octet-stream</literal> (the generic
<quote>this is a collection of bytes</quote> MIME type). Of
@@ -824,11 +824,12 @@
<literal>application/x-shockwave-flash</literal>—you can
always remove or edit that property. (For more on
Subversion's use of MIME types, see <xref
- linkend="svn.advanced.props.special.mime-type" />.)</para>
+ linkend="svn.advanced.props.special.mime-type" /> later in
+ this chapter.)</para>
<para>Subversion also provides, via its runtime configuration
system (see <xref linkend="svn.advanced.confarea" />), a more
- flexible automatic property setting feature which allows you
+ flexible automatic property setting feature that allows you
to create mappings of filename patterns to property names and
values. Once again, these mappings affect adds and imports,
and can not only override the default MIME type decision made
@@ -843,7 +844,7 @@
<literal>svn:eol-style</literal> set to
<literal>native</literal>, and <literal>svn:keywords</literal>
set to <literal>Id</literal>. Automatic property support is
- perhaps the handiest property-related tool in the Subversion
+ perhaps the handiest property related tool in the Subversion
toolbox. See <xref
linkend="svn.advanced.confarea.opts.config"/> for more about
configuring that support.</para>
@@ -865,7 +866,7 @@
everywhere.</para>
<para>However, the same is not always true of other general classes
- of software, or of the actual files you keep in Subversion. For
+ of software or of the actual files you keep in Subversion. For
example, on a Windows machine, the definition of a <quote>text
file</quote> would be similar to that used on a Linux box, but
with a key difference—the character sequences used to mark
@@ -886,7 +887,7 @@
<sect2 id="svn.advanced.props.special.mime-type">
<title>File Content Type</title>
- <para>Subversion joins the ranks of the many applications which
+ <para>Subversion joins the ranks of the many applications that
recognize and make use of Multipurpose Internet Mail
Extensions (MIME) content types. Besides being a
general-purpose storage location for a file's content type,
@@ -902,12 +903,12 @@
file by the file's name, specifically its file extension.
For example, files whose names end in
<filename>.txt</filename> are generally assumed to be
- human-readable, able to be understood by simple perusal
+ human-readable; that is, able to be understood by simple perusal
rather than requiring complex processing to decipher. Files
whose names end in <filename>.png</filename>, on the other
hand, are assumed to be of the Portable Network Graphics
type—not human-readable at all, and sensible only when
- interpreted by software which understands the PNG format and
+ interpreted by software that understands the PNG format and
can render the information in that format as a raster
image.</para>
@@ -934,22 +935,22 @@
doubt on the mapping between a file's name and its content.
With information being served across networks and generated
dynamically by server-side scripts, there was often no real
- file per se, and therefore no file name. Web
+ file per se, and therefore no filename. Web
servers, for example, needed some other way to tell browsers
what they were downloading so the browser could do something
intelligent with that information, whether that was to
display the data using a program registered to handle that
- data type, or to prompt the user for where on the client
+ data type or to prompt the user for where on the client
machine to store the downloaded data.</para>
<para>Eventually, a standard emerged for, among other things,
describing the contents of a data stream. In 1996, RFC2045
- was published, the first of five RFCs describing MIME. It
- describes the concept of media types and subtypes, and
- recommends a syntax for the representation of those types.
- Today, MIME media types—or <quote>MIME
+ was published. It was the first of five RFCs describing
+ MIME. It describes the concept of media types and subtypes
+ and recommends a syntax for the representation of those
+ types. Today, MIME media types—or <quote>MIME
types</quote>—are used almost universally across
- e-mail applications, Web servers, and other software as the
+ email applications, web servers, and other software as the
de facto mechanism for clearing up the file content
confusion.</para>
@@ -958,10 +959,10 @@
<para>For example, one of the benefits that Subversion typically
provides is contextual, line-based merging of changes received
from the server during an update into your working file. But
- for files containing non-textual data, there is often no
- concept of a <quote>line</quote>. So, for versioned files
+ for files containing nontextual data, there is often no
+ concept of a <quote>line.</quote> So, for versioned files
whose <literal>svn:mime-type</literal> property is set to a
- non-textual MIME type (generally, something that doesn't begin
+ nontextual MIME type (generally, something that doesn't begin
with <literal>text/</literal>, though there are exceptions),
Subversion does not attempt to perform contextual merges
during updates. Instead, any time you have locally modified a
@@ -980,14 +981,14 @@
to a value that does not indicate textual file contents, can
cause some unexpected behaviors with respect to other
properties. For example, since the idea of line endings
- (and therefore, line ending conversion) makes no sense when
- applied to non-textual files, Subversion will prevent you
+ (and therefore, line-ending conversion) makes no sense when
+ applied to nontextual files, Subversion will prevent you
from setting the <literal>svn:eol-style</literal> property
on such files. This is obvious when attempted on a single
file target—<command>svn propset</command> will error
out. But it might not be as clear if you perform a
recursive property set, where Subversion will silently skip
- over files which it deems unsuitable for a given
+ over files that it deems unsuitable for a given
property.</para>
</warning>
@@ -995,8 +996,8 @@
<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, for newly added and imported files, their MIME
- type.</para>
+ 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
@@ -1016,7 +1017,7 @@
permission bit. This bit usually defaults to being disabled,
and must be explicitly enabled by the user for each file that
needs it. But it would be a monumental hassle to have to
- remember exactly which files in freshly checked-out working
+ remember exactly which files in a freshly checked-out working
copy were supposed to have their executable bits toggled on,
and then to have to do that toggling. So, Subversion provides
the <literal>svn:executable</literal> property as a way to
@@ -1029,8 +1030,8 @@
NTFS.
<footnote>
<para>The Windows filesystems use file extensions (such as
- <literal>.EXE</literal>, <literal>.BAT</literal>, and
- <literal>.COM</literal>) to denote executable
+ <filename>.EXE</filename>, <filename>.BAT</filename>, and
+ <filename>.COM</filename>) to denote executable
files.</para>
</footnote>
Also, although it has no defined values, Subversion will force
@@ -1047,7 +1048,7 @@
<para>Unless otherwise noted using a versioned file's
<literal>svn:mime-type</literal> property, Subversion
assumes the file contains human-readable data. Generally
- speaking, Subversion only uses this knowledge to determine
+ speaking, Subversion uses this knowledge only to determine
if contextual difference reports for that file are
possible. Otherwise, to Subversion, bytes are bytes.</para>
@@ -1056,7 +1057,7 @@
markers</firstterm> used in your files. Unfortunately,
different operating systems have different conventions about
which character sequences represent the end of a line of text
- in a file. For example, the usual line ending token used by
+ in a file. For example, the usual line-ending token used by
software on the Windows platform is a pair of ASCII control
characters—a carriage return (<literal>CR</literal>)
followed by a line feed (<literal>LF</literal>). Unix
@@ -1064,24 +1065,23 @@
character to denote the end of a line.</para>
<para>Not all of the various tools on these operating systems
- understand files that contain line endings
- in a format that differs from the <firstterm>native line
- ending style</firstterm> of the operating system on which
- they are running. So, typically, Unix programs
- treat the <literal>CR</literal> character present in Windows
- files as a regular character (usually rendered as
- <literal>^M</literal>), and Windows programs combine
- all of the lines of a Unix file into one giant line because
- no carriage return-linefeed (or <literal>CRLF</literal>)
- character combination was found to denote the ends of
- the lines.</para>
+ understand files that contain line endings in a format that
+ differs from the <firstterm>native line-ending
+ style</firstterm> of the operating system on which they are
+ running. So, typically, Unix programs treat the
+ <literal>CR</literal> character present in Windows files as a
+ regular character (usually rendered as <literal>^M</literal>),
+ and Windows programs combine all of the lines of a Unix file
+ into one giant line because no carriage return-linefeed (or
+ <literal>CRLF</literal>) character combination was found to
+ denote the ends of the lines.</para>
<para>This sensitivity to foreign EOL markers can be
frustrating for folks who share a file across different
operating systems. For example, consider a source code
file, and developers that edit this file on both Windows and
- Unix systems. If all the developers always use tools which
- preserve the line ending style of the file, no problems
+ Unix systems. If all the developers always use tools that
+ preserve the line-ending style of the file, no problems
occur.</para>
<para>But in practice, many common tools either fail to
@@ -1096,7 +1096,7 @@
original quite literally on every line! Prior to committing
his changes, the user has two choices. Either he can use a
conversion utility to restore the modified file to the same
- line ending style that it was in before his edits were made.
+ line-ending style that it was in before his edits were made.
Or, he can simply commit the file—new EOL markers and
all.</para>
@@ -1104,7 +1104,7 @@
and unnecessary modifications to committed files. Wasted
time is painful enough. But when commits change every line
in a file, this complicates the job of determining which of
- those lines were changed in a non-trivial way. Where was
+ those lines were changed in a nontrivial way. Where was
that bug really fixed? On what line was a syntax error
introduced?</para>
@@ -1112,7 +1112,7 @@
<literal>svn:eol-style</literal> property. When this
property is set to a valid value, Subversion uses it to
determine what special processing to perform on the file so
- that the file's line ending style isn't flip-flopping with
+ that the file's line-ending style isn't flip-flopping with
every commit that comes from a different operating
system. The valid values are:</para>
@@ -1128,7 +1128,7 @@
<literal>svn:eol-style</literal> property set to
<literal>native</literal>, that file will contain
<literal>CRLF</literal> EOL markers. A Unix user
- checking out a working copy which contains the same
+ checking out a working copy that contains the same
file will see <literal>LF</literal> EOL markers in his
copy of the file.</para>
@@ -1160,10 +1160,10 @@
<listitem>
<para>This causes the file to contain
<literal>CR</literal> characters for EOL markers,
- regardless of the operating system in use. This line
- ending style is not very common. It was used on older
- Macintosh platforms (on which Subversion doesn't even
- run).</para>
+ regardless of the operating system in use. This
+ line-ending style is not very common. It was used on
+ older Macintosh platforms (on which Subversion doesn't
+ even run).</para>
</listitem>
</varlistentry>
</variablelist>
@@ -1177,12 +1177,12 @@
<sect1 id="svn.advanced.props.special.ignore">
<title>Ignoring Unversioned Items</title>
- <para>In any given working copy there is a good chance that
+ <para>In any given working copy, there is a good chance that
alongside all those versioned files and directories are other
- files and directories which are neither versioned nor intended
+ files and directories that are neither versioned nor intended
to be. Text editors litter directories with backup files.
Software compilers generate intermediate—or even
- final—files which you typically wouldn't bother to
+ final—files that you typically wouldn't bother to
version. And users themselves drop various other files and
directories wherever they see fit, often in version control
working copies.</para>
@@ -1194,7 +1194,7 @@
unversioned trees. But these not-to-be-versioned files and
directories can cause some annoyance for Subversion users. For
example, because the <command>svn add</command> and <command>svn
- import</command> commands act recursively by default, and don't
+ import</command> commands act recursively by default and don't
know which files in a given tree you do and don't wish to
version, it's easy to accidentally add stuff to version control
that you didn't mean to. And because <command>svn
@@ -1204,30 +1204,30 @@
these things exist.</para>
<para>So Subversion provides two ways for telling it which files
- you would prefer that it simply disregard. One of the ways
+ you would prefer for it to simply disregard. One of the ways
involves the use of Subversion's runtime configuration system
(see <xref linkend="svn.advanced.confarea" />), and therefore
- applies to all the Subversion operations which make use of that
- runtime configuration, generally those performed on a particular
- computer, or by a particular user of a computer. The other way
- makes use of Subversion's directory property support, is more
+ applies to all the Subversion operations that make use of that
+ runtime configuration—generally those performed on a particular
+ computer or by a particular user of a computer. The other way
+ makes use of Subversion's directory property support and is more
tightly bound to the versioned tree itself, and therefore
affects everyone who has a working copy of that tree. Both of
the mechanisms use <firstterm>file patterns</firstterm> (strings
of literal and special wildcard characters used to match against
- file names) to decide which files to ignore.</para>
+ filenames) to decide which files to ignore.</para>
<para>The Subversion runtime configuration system provides an
option, <literal>global-ignores</literal>, whose value is a
whitespace-delimited collection of file patterns. The
Subversion client checks these patterns against the names of the
- files which are candidates for addition to version control, as
- well as to unversioned files which the <command>svn
+ files that are candidates for addition to version control, as
+ well as to unversioned files that the <command>svn
status</command> command notices. If any file's name matches
one of the patterns, Subversion will basically act as if the
file didn't exist at all. This is really useful for the kinds
of files that you almost never want to version, such as editor
- backup files like Emacs' <literal>*~</literal> and
+ backup files such as Emacs' <literal>*~</literal> and
<literal>.*~</literal> files.</para>
<sidebar>
@@ -1235,12 +1235,12 @@
<para>File patterns (also called <firstterm>globs</firstterm> or
<firstterm>shell wildcard patterns</firstterm>) are strings of
- characters that are intended to be matched against file names,
+ characters that are intended to be matched against filenames,
typically for the purpose of quickly selecting some subset of
similar files from a larger grouping without having to
explicitly name each file. The patterns contain two types of
- characters: regular characters which are compared explicitly
- against potential matches, and special wildcard characters
+ characters: regular characters, which are compared explicitly
+ against potential matches, and special wildcard characters,
which are interpreted differently for matching
purposes.</para>
@@ -1254,29 +1254,29 @@
<varlistentry>
<term><literal>?</literal></term>
<listitem>
- <para>matches any single character</para>
+ <para>Matches any single character.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>*</literal></term>
<listitem>
- <para>matches any string of characters, including the
- empty string</para>
+ <para>Matches any string of characters, including the
+ empty string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>[</literal></term>
<listitem>
- <para>begins a character class definition terminated by
+ <para>Begins a character class definition terminated by
<literal>]</literal>, used for matching a subset of
- characters</para>
+ characters.</para>
</listitem>
</varlistentry>
</variablelist>
<para>You can see this same pattern matching behavior at a Unix
shell prompt. The following are some examples of patterns
- being used for various things.</para>
+ being used for various things:</para>
<screen>
$ ls ### the book sources
@@ -1314,7 +1314,7 @@
<para>When found on a versioned directory, the
<literal>svn:ignore</literal> property is expected to contain a
- list of newline-delimited file patterns which Subversion should
+ list of newline-delimited file patterns that Subversion should
use to determine ignorable objects in that same directory.
These patterns do not override those found in the
<literal>global-ignores</literal> runtime configuration option,
@@ -1371,7 +1371,7 @@
</sidebar>
<para>The global list of ignore patterns tends to be more a
- matter of personal taste, and tied more closely to a user's
+ matter of personal taste and ties more closely to a user's
particular tool chain than to the details of any particular
working copy's needs. So, the rest of this section will focus
on the <literal>svn:ignore</literal> property and its
@@ -1392,7 +1392,7 @@
</screen>
<para>In this example, you have made some property modifications
- to <filename>button.c</filename>, but in your working copy you
+ to <filename>button.c</filename>, but in your working copy, you
also have some unversioned files: the latest
<filename>calculator</filename> program that you've compiled
from your source code, a source file named
@@ -1406,12 +1406,12 @@
log files lying around. These facts are true for all working
copies of this project, not just your own. And you know that
you aren't interested in seeing those things every time you run
- <command>svn status</command>, and pretty sure that nobody else
- is interested in them either. So you use <command>svn propedit
- svn:ignore calc</command> to add some ignore patterns to the
- <filename>calc</filename> directory. For example, you might add
- this as the new value of the <literal>svn:ignore</literal>
- property:</para>
+ <command>svn status</command>, and you are pretty sure that
+ nobody else is interested in them either. So you use
+ <command>svn propedit svn:ignore calc</command> to add some
+ ignore patterns to the <filename>calc</filename> directory. For
+ example, you might add this as the new value of the
+ <literal>svn:ignore</literal> property:</para>
<programlisting>
calculator
@@ -1435,7 +1435,7 @@
logfiles are still in your working copy; Subversion just isn't
constantly reminding you that they are present and unversioned.
And now with all the uninteresting noise removed from the
- display, you are left with more interesting items—such as
+ display, you are left with more intriguing items—such as
that source code file <filename>data.c</filename> that you
probably forgot to add to version control.</para>
@@ -1576,7 +1576,7 @@
<para>Several of the previous descriptions use the phrase
<quote>last known</quote> or similar wording. Keep in mind that
keyword expansion is a client-side operation, and your client
- only <quote>knows</quote> about changes which have occurred in
+ <quote>knows</quote> only about changes that have occurred in
the repository when you update your working copy to include
those changes. If you never update your working copy, your
keywords will never expand to different values even if those
@@ -1592,10 +1592,10 @@
<para>… or maybe even a section of a book …</para>
</footnote>
about how to use keywords, and you don't want Subversion to
- substitute your beautiful examples of un-substituted keyword
+ substitute your beautiful examples of unsubstituted keyword
anchors!</para>
- <para>To tell Subversion whether or not to substitute keywords
+ <para>To tell Subversion whether to substitute keywords
on a particular file, we again turn to the property-related
subcommands. The <literal>svn:keywords</literal> property,
when set on a versioned file, controls which keywords will
@@ -1632,7 +1632,7 @@
contained a keyword anchor for the <literal>Rev</literal>
keyword, yet we did not include that keyword in the property
value we set. Subversion will happily ignore requests to
- substitute keywords that are not present in the file, and
+ substitute keywords that are not present in the file and
will not substitute keywords that are not present in the
<literal>svn:keywords</literal> property value.</para>
@@ -1641,15 +1641,15 @@
substitute text. Instead of seeing your keyword anchor
<literal>$LastChangedDate$</literal>, you'll see its
substituted result. That result also contains the name of
- the keyword, and continues to be bounded by the dollar sign
+ the keyword and continues to be bounded by the dollar sign
(<literal>$</literal>) characters. And as we predicted, the
<literal>Rev</literal> keyword was not substituted because
we didn't ask for it to be.</para>
<para>Note also that we set the <literal>svn:keywords</literal>
- property to <quote>Date Author</quote> yet the keyword
+ property to <literal>Date Author</literal>, yet the keyword
anchor used the alias <literal>$LastChangedDate$</literal>
- and still expanded correctly.</para>
+ and still expanded correctly:</para>
<screen>
Here is the latest report from the front lines.
@@ -1662,8 +1662,8 @@
<filename>weather.txt</filename>, your copy of that file
will continue to display the same substituted keyword value
as before—until you update your working copy. At that
- time the keywords in your <filename>weather.txt</filename>
- file will be re-substituted with information that
+ time, the keywords in your <filename>weather.txt</filename>
+ file will be resubstituted with information that
reflects the most recent known commit to that file.</para>
<sidebar>
@@ -1672,7 +1672,7 @@
<para>New users are often confused by how the
<literal>$Rev$</literal> keyword works. Since the repository
has a single, globally increasing revision number, many people
- assume that it is this number which is reflected by the
+ assume that it is this number that is reflected by the
<literal>$Rev$</literal> keyword's value. But
<literal>$Rev$</literal> expands to show the last revision in
which the file <emphasis>changed</emphasis>, not the last
@@ -1683,23 +1683,22 @@
files?</para>
<para>To do this, you need external processing. Subversion
- ships with a tool called <command>svnversion</command> which
- was designed for just this purpose.
- <command>svnversion</command> crawls your working copy and
- generates as output the revision(s) it finds. You can use
- this program, plus some additional tooling, to embed that
- revision information into your files. For more information on
- <command>svnversion</command>, see <xref
+ ships with a tool called <command>svnversion</command>, which
+ was designed for just this purpose. It crawls your working
+ copy and generates as output the revision(s) it finds. You
+ can use this program, plus some additional tooling, to embed
+ that revision information into your files. For more
+ information on <command>svnversion</command>, see <xref
linkend="svn.ref.svnversion"/>.</para>
</sidebar>
<para>Subversion 1.2 introduced a new variant of the keyword
- syntax which brought additional, useful—though perhaps
+ 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,
+ 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
@@ -1735,14 +1734,14 @@
<para>The result is not so beautiful. And you might be
tempted to then adjust the file after the substitution so
- that it again looks tabular. But that only holds as long as
+ that it again looks tabular. But that holds only as long as
the keyword values are the same width. If the last
committed revision rolls into a new place value (say, from
99 to 100), or if another person with a longer username
commits the file, stuff gets all crooked again. However, if
you are using Subversion 1.2 or better, you can use the new
- fixed-length keyword syntax, define some field widths that
- seem sane, and now your file might look like this:</para>
+ fixed-length keyword syntax and define some field widths that
+ seem sane so your file might look like this:</para>
<screen>
$Rev:: $: Revision of last commit
@@ -1751,9 +1750,9 @@
</screen>
<para>You commit this change to your file. This time,
- Subversion notices the new fixed-length keyword syntax, and
+ Subversion notices the new fixed-length keyword syntax and
maintains the width of the fields as defined by the padding
- you placed between the double-colon and the trailing dollar
+ you placed between the double colon and the trailing dollar
sign. After substitution, the width of the fields is
completely unchanged—the short values for
<literal>Rev</literal> and <literal>Author</literal> are
@@ -1776,9 +1775,9 @@
<warning>
<para>Be aware that because the width of a keyword field is
measured in bytes, the potential for corruption of
- multi-byte values exists. For example, a username which
- contains some multi-byte UTF-8 characters might suffer
- truncation in the middle of the string of bytes which make
+ multibyte values exists. For example, a username that
+ contains some multibyte UTF-8 characters might suffer
+ truncation in the middle of the string of bytes that make
up one of those characters. The result will be a mere
truncation when viewed at the byte level, but will likely
appear as a string with an incorrect or garbled final
@@ -1807,14 +1806,14 @@
structure is copied to your local disk. Subversion 1.5
introduces a feature called <firstterm>sparse
directories</firstterm> (or <firstterm>shallow
- checkouts</firstterm>) which allows you to easily checkout a
+ checkouts</firstterm>) that allows you to easily check out a
working copy—or a portion of a working copy—more
shallowly than full recursion, with the freedom to bring in
previously ignored files and subdirectories at a later
time.</para>
<para>For example, say we have a repository with a tree of files
- and directories named like the members of a human family with
+ and directories with names of the members of a human family with
pets. (It's an odd example, to be sure, but bear with us.) A
regular <command>svn checkout</command> operation will give us a
working copy of the whole tree:</para>
@@ -1835,9 +1834,9 @@
$
</screen>
- <para>Now, let's checkout the same tree again, but this time,
- we'll ask Subversion to give us only the topmost direcectory
- with none of its children at all.</para>
+ <para>Now, let's check out the same tree again, but this time,
+ we'll ask Subversion to give us only the top-most direcectory
+ with none of its children at all:</para>
<screen>
$ svn checkout file:///var/svn/repos mom-empty --depth empty
@@ -1848,8 +1847,9 @@
<para>Notice that we added to our original <command>svn
checkout</command> command line a new <option>--depth</option>
option. This option is present on many of Subversion's
- subcommands, and is similar to the <option>--non-recursive
- (-N)</option> and <option>--recursive (-R)</option> options. In
+ subcommands, and is similar to the
+ <option>--non-recursive</option> (<option>-N</option>) and
+ <option>--recursive</option> (<option>-R</option>) options. In
fact, it combines, improves upon, supercedes, and ultimately
obsoletes these two older options. For starters, it expands the
supported degrees of depth specification available to users,
@@ -1949,17 +1949,17 @@
present on many other Subversion commands, too. In those other
commands, depth specification is a way to limit the scope of an
operation to some depth, much like the way the older
- <option>--non-recursive (-N)</option> and <option>--recursive
- (-R)</option> options behave. This means that when operating on
- a working copy of some depth, and requesting an operation of a
- shallower depth, the operation is limited to that shallower
- depth. In fact, we can make an even more general statement:
- given a working copy of any arbitrary—even
- mixed—ambient depth, and a Subversion command with some
- requested operational depth, the command will maintain the
- ambient depth of the working copy members while still limiting
- the scope of the operation to the requested (or default)
- operational depth.</para>
+ <option>--non-recursive</option> (<option>-N</option>) and
+ <option>--recursive</option> (<option>-R</option>) options
+ behave. This means that when operating on a working copy of
+ some depth, and requesting an operation of a shallower depth,
+ the operation is limited to that shallower depth. In fact, we
+ can make an even more general statement: given a working copy of
+ any arbitrary—even mixed—ambient depth, and a
+ Subversion command with some requested operational depth, the
+ command will maintain the ambient depth of the working copy
+ members while still limiting the scope of the operation to the
+ requested (or default) operational depth.</para>
<para>In addition to the <option>--depth</option> option, the
<command>svn update</command> and <command>svn switch</command>
@@ -2090,7 +2090,7 @@
of a word or a single character of text. But common among those
algorithms is that they generally work only on text files. The
landscape starts to look pretty grim when you start talking
- about content merges of non-textual file formats. And when you
+ about content merges of nontextual file formats. And when you
can't find a tool that can handle that type of merging, you
begin to run into problems with the copy-modify-merge
model.</para>
@@ -2267,15 +2267,16 @@
<para>There are a number of new things demonstrated in the
previous example. First, notice that Harry passed the
- <option>--message (-m)</option> option to <command>svn
- lock</command>. Similar to <command>svn commit</command>, the
- <command>svn lock</command> command can take comments (either
- via <option>--message (-m)</option> or <option>--file
- (-F)</option>) to describe the reason for locking the file.
- Unlike <command>svn commit</command>, however, <command>svn
- lock</command> will not demand a message by launching your
- preferred text editor. Lock comments are optional, but still
- recommended to aid communication.</para>
+ <option>--message</option> (<option>-m</option>) option to
+ <command>svn lock</command>. Similar to <command>svn
+ commit</command>, the <command>svn lock</command> command can
+ take comments (either via <option>--message</option>
+ (<option>-m</option>) or <option>--file</option>
+ (<option>-F</option>) to describe the reason for locking the
+ file. Unlike <command>svn commit</command>, however,
+ <command>svn lock</command> will not demand a message by
+ launching your preferred text editor. Lock comments are
+ optional, but still recommended to aid communication.</para>
<para>Secondly, the lock attempt succeeded. This means that the
file wasn't already locked, and that Harry had the latest
@@ -3057,15 +3058,16 @@
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 (-r)</option> of which
- we've spoken so much in this book? That revision (or set of
- revisions) is called the <firstterm>operative
- revision</firstterm> (or <firstterm>operative revision
- range</firstterm>). Once a particular line of history has been
- identified using a path and peg revision, Subversion performs
- the requested operation using the operative revision(s). To map
- this to our Chicagoland streets analogy, if we are told to go to
- 606 N. Main Street in Wheaton,
+ <para>But what of the <option>--revision</option>
+ (<option>-r</option>) of which we've spoken so much in this
+ book? That revision (or set of revisions) is called the
+ <firstterm>operative revision</firstterm> (or
+ <firstterm>operative revision range</firstterm>). Once a
+ particular line of history has been identified using a path and
+ peg revision, Subversion performs the requested operation using
+ the operative revision(s). To map this to our Chicagoland
+ streets analogy, if we are told to go to 606 N. Main Street in
+ Wheaton,
<footnote>
<para>606 N. Main Street, Wheaton, Illinois, is the home of
the Wheaton History Center. Get it—<quote>History
More information about the svnbook-dev
mailing list