Below is a large patch that puts <quote>'s in place of " (and one case of ``
''). Also fixed one place -- was used instead of —. I also made sure they
paragraph was wrapped properly after the addition of <quote>'s.
Question: There were a few spots that would have <quote><literal> and then when
converting a few <literal>", I decided to go with what I saw before, with the
quote outside the literal. If this is not the case, I can reverse them to be
<literal><quote>.
Also, there were a few spots I saw <literal>', I decided not to touch those.
Also, a spot where ' was used instead of ", there is no <singlequote> is there?
-- Larry
Log Message:
doc/book/ch00.xml Use <quote> consistently (instead of ").
doc/book/ch02.xml ditto
doc/book/ch03.xml ditto
doc/book/ch05.xml ditto
doc/book/ch06.xml ditto
doc/book/ch07.xml ditto
doc/book/ch04.xml ditto and fix -- to —
Index: doc/book/book/ch00.xml
===================================================================
--- doc/book/book/ch00.xml (revision 5360)
+++ doc/book/book/ch00.xml (working copy)
@@ -26,13 +26,12 @@
Subversion is a relatively new version control system designed
to be the successor to CVS. The designers set out to win the
hearts of CVS users in two ways: by creating a open-source
- version control system with a similar design (and "look and
- feel") as CVS, and by attempting to fix most of CVS's noticeable
- flaws. While the result isn't necessarily the next great
- evolution in version control design, Subversion
+ version control system with a similar design (and <quote>look
+ and feel</quote>) as CVS, and by attempting to fix most of CVS's
+ noticeable flaws. While the result isn't necessarily the next
+ great evolution in version control design, Subversion
<emphasis>is</emphasis> very powerful, very useable, and very
- flexible.
- </para>
+ flexible. </para>
</simplesect>
Index: doc/book/book/ch02.xml
===================================================================
--- doc/book/book/ch02.xml (revision 5360)
+++ doc/book/book/ch02.xml (working copy)
@@ -53,13 +53,13 @@
sees only the latest version of the filesystem tree. But the
client also has the ability to view
<emphasis>previous</emphasis> states of the filesystem. For
- example, a client can ask historical questions like, "what did
- this directory contain last Wednesday?", or "who was the last
- person to change this file, and what changes did they make?"
- These are the sorts of questions that are at the heart of any
- <firstterm>version control system</firstterm>: systems that are
- designed to record and track changes to data over time.
- </para>
+ example, a client can ask historical questions like, <quote>what
+ did this directory contain last Wednesday?</quote>, or
+ <quote>who was the last person to change this file, and what
+ changes did they make?</quote> These are the sorts of questions
+ that are at the heart of any <firstterm>version control
+ system</firstterm>: systems that are designed to record and
+ track changes to data over time.</para>
</sect1>
@@ -106,14 +106,15 @@
<firstterm>lock-modify-unlock</firstterm> model to address
this problem, which is a very simple solution. In such a
system, the repository allows only one person to change a file
- at a time. First Harry must "lock" the file before he can begin
- making changes to it. Locking a file is a lot like borrowing
- a book from the library; if Harry has locked a file, then Sally
- cannot make any changes to it. If she tries to lock the file,
- the repository will deny the request. All she can do is read
- the file, and wait for Harry to finish his changes and release
- his lock. After Harry unlocks the file, his turn is over, and
- now Sally can take her turn by locking and editing.</para>
+ at a time. First Harry must <quote>lock</quote> the file
+ before he can begin making changes to it. Locking a file is a
+ lot like borrowing a book from the library; if Harry has
+ locked a file, then Sally cannot make any changes to it. If
+ she tries to lock the file, the repository will deny the
+ request. All she can do is read the file, and wait for Harry
+ to finish his changes and release his lock. After Harry
+ unlocks the file, his turn is over, and now Sally can take her
+ turn by locking and editing.</para>
<figure id="svn-ch2-dia3">
<title>The lock-modify-unlock solution</title>
@@ -181,16 +182,17 @@
<para>Here's an example. Say that Harry and Sally each create
working copies of the same project, copied from the
repository. They work concurrently, and make changes to the
- same file "A" within their copies. Sally saves her changes to
- the repository first. When Harry attempts to save his changes
- later, the repository informs him that his file A is
- <firstterm>out-of-date</firstterm>. In other words, that file
- A in the repository has somehow changed since he last copied
- it. So Harry asks his client to <firstterm>merge</firstterm>
- any new changes from the repository into his working copy of
- file A. Chances are that Sally's changes don't overlap with
- his own; so once he has both sets of changes integrated, he
- saves his working copy back to the repository.</para>
+ same file <quote>A</quote> within their copies. Sally saves
+ her changes to the repository first. When Harry attempts to
+ save his changes later, the repository informs him that his
+ file A is <firstterm>out-of-date</firstterm>. In other words,
+ that file A in the repository has somehow changed since he
+ last copied it. So Harry asks his client to
+ <firstterm>merge</firstterm> any new changes from the
+ repository into his working copy of file A. Chances are that
+ Sally's changes don't overlap with his own; so once he has
+ both sets of changes integrated, he saves his working copy
+ back to the repository.</para>
<figure id="svn-ch2-dia4">
<title>The copy-modify-merge solution</title>
@@ -259,11 +261,11 @@
<para>After you've made some changes to the files in your
working copy and verified that they work properly, Subversion
- provides you with commands to "publish" your changes to the
- other people working with you on your project (by writing to
- the repository). If other people publish their own changes,
- Subversion provides you with commands to merge those changes
- into your working directory (by reading from the
+ provides you with commands to <quote>publish</quote> your
+ changes to the other people working with you on your project
+ (by writing to the repository). If other people publish their
+ own changes, Subversion provides you with commands to merge
+ those changes into your working directory (by reading from the
repository).</para>
<para>A working copy also contains some extra files, created and
@@ -296,11 +298,11 @@
<para>To get a working copy, you must <firstterm>check
out</firstterm> some subtree of the repository. (The term
- "check out" may sound like it has something to do with locking
- or reserving resources, but it doesn't; it simply creates a
- private copy of the project for you.) For example, If you
- check out <filename>/calc</filename>, you will get a working
- copy like this: </para>
+ <quote>check out</quote> may sound like it has something to do
+ with locking or reserving resources, but it doesn't; it simply
+ creates a private copy of the project for you.) For example,
+ If you check out <filename>/calc</filename>, you will get a
+ working copy like this: </para>
<screen>
$ svn checkout http://svn.example.com/repos/calc
@@ -504,14 +506,14 @@
repository after some committed change. Another way to
think about it is that revision N represents the state of
the repository filesystem after the Nth commit. When a
- Subversion user talks about ``revision 5 of
- <filename>foo.c</filename>'', they really mean
- ``<filename>foo.c</filename> as it appears in revision 5.''
- Notice that in general, revisions N and M of a file do
- <emphasis>not</emphasis> necessarily differ! Because CVS
- uses per-file revisions numbers, CVS users might want to
- look at Appendix A, "SVN for CVS Users", for more details.
- <!-- ### add xref here! --></para>
+ Subversion user talks about <quote>revision 5 of
+ <filename>foo.c</filename></quote>, they really mean
+ <quote><filename>foo.c</filename> as it appears in revision
+ 5.</quote> Notice that in general, revisions N and M of a
+ file do <emphasis>not</emphasis> necessarily differ!
+ Because CVS uses per-file revisions numbers, CVS users might
+ want to look at Appendix A, "SVN for CVS Users", for more
+ details. <!-- ### add xref here! --></para>
</sidebar>
<para>It's important to note that working copies do not always
@@ -625,12 +627,12 @@
<listitem><para>The file has been changed both in the
working directory, and in the repository. A <command>svn
- commit</command> of the file will fail with an "out-of-date"
- error. The file should be updated first; a <command>svn
- update</command> command will attempt to merge the public
- changes with the local changes. If Subversion can't
- complete the merge in a plausible way automatically, it
- leaves it to the user to resolve the
+ commit</command> of the file will fail with an
+ <quote>out-of-date</quote> error. The file should be
+ updated first; a <command>svn update</command> command will
+ attempt to merge the public changes with the local changes.
+ If Subversion can't complete the merge in a plausible way
+ automatically, it leaves it to the user to resolve the
conflict.</para></listitem>
</varlistentry>
</variablelist>
Index: doc/book/book/ch03.xml
===================================================================
--- doc/book/book/ch03.xml (revision 5360)
+++ doc/book/book/ch03.xml (working copy)
@@ -1124,16 +1124,17 @@
<filename>.svn</filename> administrative areas. This allows
Subversion to report—and revert—local
modifications to those files <emphasis>without network
- access</emphasis>. This cache (called the "text-base") also
- allows Subversion to send the user's local modifications
- during a commit to the server as a compressed delta against
- the pristine version. Having this cache is a tremendous
- benefit—even if you have a fast net connection, it's
- much faster to send only a file's changes rather than the
- whole file to the server. At first glance, this might not
- seem that important, but imagine the repercussions if you
- try to commit a one line change to a 400MB file and have to
- send the whole file to the server!</para>
+ access</emphasis>. This cache (called the
+ <quote>text-base</quote>) also allows Subversion to send the
+ user's local modifications during a commit to the server as
+ a compressed delta against the pristine version. Having
+ this cache is a tremendous benefit—even if you have a
+ fast net connection, it's much faster to send only a file's
+ changes rather than the whole file to the server. At first
+ glance, this might not seem that important, but imagine the
+ repercussions if you try to commit a one line change to a
+ 400MB file and have to send the whole file to the
+ server!</para>
</sidebar>
</sect2>
@@ -1683,12 +1684,13 @@
to remember that while revisions are repository-wide,
<command>svn log</command> operates on a path in the
repository (If you suy no path, Subversion defaults to
- <literal>"."</literal>). As a result, if you're operating
- in a subdirectory of your working copy and attempt to log a
- revision where nothing beneath your current directory
- changed, Subversion will give you an empty log. If you want
- to see what changed in that revision, try running the same
- command from the top directory of your working copy.</para>
+ <quote><literal>.</literal></quote>). As a result, if
+ you're operating in a subdirectory of your working copy and
+ attempt to log a revision where nothing beneath your current
+ directory changed, Subversion will give you an empty log.
+ If you want to see what changed in that revision, try
+ running the same command from the top directory of your
+ working copy.</para>
</sidebar>
Index: doc/book/book/ch04.xml
===================================================================
--- doc/book/book/ch04.xml (revision 5360)
+++ doc/book/book/ch04.xml (working copy)
@@ -63,8 +63,8 @@
related to one another. It also helps you duplicate changes
from one branch to another. Finally, it can make portions of
your working copy reflect different branches, so that you can
- "mix and match" different lines of development in your daily
- work.</para>
+ <quote>mix and match</quote> different lines of development in
+ your daily work.</para>
</sect1>
@@ -75,9 +75,9 @@
<title>Using branches</title>
<para>At this point, you should understand how each commit creates
- an entire new filesystem tree (called a "revision") in the
- repository. If not, go back and read about ons in <xref
- linkend="svn-ch-2-sect-3.2"/>.</para>
+ an entire new filesystem tree (called a <quote>revision</quote>)
+ in the repository. If not, go back and read about revisions in
+ <xref linkend="svn-ch-2-sect-3.2"/>.</para>
<para>For this chapter, we'll go back to the same example from
Chapter 2. Remember that you and your collaborator, Sally, are
@@ -143,9 +143,10 @@
policy. Let's say that your team has a policy of creating
branches in the <filename>/branches/calc</filename> area of
the repository, and you want to name your branch
- "my-calc-branch". You'll want to create a new directory,
- <filename>/branches/calc/my-calc-branch</filename>, which
- starts as a copy of <filename>/trunk/calc</filename>. </para>
+ <quote>my-calc-branch</quote>. You'll want to create a new
+ directory, <filename>/branches/calc/my-calc-branch</filename>,
+ which starts as a copy of
+ <filename>/trunk/calc</filename>. </para>
<para>There are two different ways to make a copy. We'll
demonstrate the messy way first, just to make the concept
@@ -244,14 +245,15 @@
the original directory.</para>
<para>This is why you'll often hear Subversion users talk
- about "cheap copies". It doesn't matter how large the
- directory is -- it takes a very tiny, constant amount of
- time to make a copy of it. In fact, this feature is the
- basis of how commits work in Subversion: each revision is a
- "cheap copy" of the previous revision, with a few items
- lazily changed within. (To read more about this, visit
- Subversion's website and read about the "bubble up" method
- in Subversion's design documents.)</para>
+ about <quote>cheap copies</quote>. It doesn't matter how
+ large the directory is — it takes a very tiny,
+ constant amount of time to make a copy of it. In fac: each
+ revision is a <quote>cheap copy</quote> of the previous
+ revision, with a few items lazily changed within. (To read
+ more about this, visit Subversion's website and read about
+ the <quote>bubble up</quote> method in Subversion's design
+ documents.)</para>
<para>The point here is that copies are cheap, both in time
and space. Make branches as often as you want. </para>
@@ -391,13 +393,14 @@
extra dimension.</para>
</listitem>
<listitem>
- <para>Subversion has no internal concept of a "branch"
- — only copies. When you copy a directory, the
- resulting directory is only a "branch" because
- <emphasis>you</emphasis> attach that meaning to it. You may
- think of the directory differently, or treat it differently,
- but to Subversion it's just an ordinary directory that
- happens to have been created by copying.</para>
+ <para>Subversion has no internal concept of a
+ <quote>branch</quote> — only copies. When you copy a
+ directory, the resulting directory is only a
+ <quote>branch</quote> because <emphasis>you</emphasis>
+ attach that meaning to it. You may think of the directory
+ differently, or treat it differently, but to Subversion it's
+ just an ordinary directory that happens to have been created
+ by copying.</para>
</listitem>
</orderedlist>
@@ -415,15 +418,15 @@
project. The good news is that you're not interfering with each
other. The bad news is that it's very easy to drift
<emphasis>too</emphasis> far apart. Remember that one of the
- problems with the "crawl in a hole" strategy is that by the time
- you're finished with your branch, it may be near-impossible to
- merge your changes back into the main branch without a huge
- number of conflicts.</para>
+ problems with the <and> is to roll
back a change that has already been committed. Suppose you
decide that the change made way back in revision 303, which
- changed <filename>integer.c</filename>, is completely wrong.
- It never should have been committed. You can use <command>svn
- merge</command> to "undo" the change in your working copy, and
- then commit the local modification to the repository. All you
- need to do is do specify a <emphasis>reverse</emphasis>
- difference:</para>
+ changed <filename>integer.c</filename>, is completely wrong. It
+ never should have been committed. You can use <command>svn
+ merge</command> to <quote>undo</quote> the change in your
+ working copy, and then commit the local modification to the
+ repository. All you need to do is do specify a
+ <emphasis>reverse</emphasis> difference:</para>
<screen>
$ svn merge -r 303:302 http://svn.example.com/trunk/calc
@@ -699,19 +703,20 @@
<filename>calc</filename> project between revisions 303 and
349, they'll still see the bad change, right?</para>
- <para>Yes, that's true. When we talk about "removing" a change,
- we're really talking about "removing it from HEAD". The
- original change still exists in the repository's history. For
- most situations, this is good enough. Most people are only
- interested in tracking the HEAD of a project anyway. There are
- special cases, however, where you really might want to destroy
- all evidence of the commit. (Perhaps somebody accidentally
- committed a confidential document.) This isn't so easy, it
- turns out, because Subversion was deliberately designed to never
- lose information. Revisions are immutable trees which build
- upon one another. Removing a revision from history would cause
- a domino effect, creating chaos in all subsequent revisions and
- possibly invalidating all working copies.
+ <para>Yes, that's true. When we talk aboworking copies contain a mixture of working
- revisions, but a mixture of repository locations as well.</para>
+ copy, but the <quote>switched</quote> portions will remain
+ immune (unless someone commits a change to their branch). This
+ feature adds a whole new dimension to the concept of a
+ <quote>mixed working copy</quote> — not only can working
+ copies contain a mixture of working revisions, but a mixture of
+ repository locations as well.</para>
<para>If your working copy contains a number of switched subtrees
from different repository locations, it continues to function as
@@ -846,16 +852,17 @@
<title>Tags</title>
<para>Another common version control concept is a
- <firstterm>tag</firstterm>. A tag is just a "snapshot" of a
- project in time. In Subversion, this idea already seems to be
- everywhere. Each repository revision is exactly that — a
- snapshot of the filesystem after each commit.</para>
+ <firstterm>tag</firstterm>. A tag is just a
+ <quote>snapshot</quote> of a project in time. In Subversion,
+ this idea already seems to be everywhere. Each repository
+ revision is exactly that — a snapshot of the filesystem
+ after each commit.</para>
<para>However, people often want to give more human-friendly names
- to tags, like "release-1.0". And they want to make snapshots of
- smaller subdirectories of the filesystem. After all, it's not
- so easy to remember that release-1.0 of a piece of software is a
- particular subdirectory of revision 4822.</para>
+ to tags, like <quote>release-1.0</quote>. And they want to make
+ snapshots of smaller subdirectories of the filesystem. After
+ all, it's not so easy to remember that release-1.0 of a piece of
+ software is a particular subdirectory of revision 4822.</para>
<sect2 id="svn-ch-4-sect-6.1">
<title>Creating a simple tag</title>
@@ -891,25 +898,27 @@
is. In Subversion, there's no difference between a tag and a
branch. Both are just ordinary directories that are created
by copying. Just as with branches, the only reason a copied
- directory is a "tag" is because <emphasis>humans</emphasis>
- have decided to treat it that way: as long as nobody ever
- commits to the directory, it forever remains a snapshot. If
- people start committing to it, it becomes a branch.</para>
+ directory is a <quote>tag</quote> is because
+ <emphasis>humans</emphasis> have decided to treat it that way:
+ as long as nobody ever commits to the directory, it forever
+ remains a snapshot. If people start committing to it, it
+ becomes a branch.</para>
<para>If you are administering a repository, there are two
approaches you can take to managing tags. The first approach
- is "hands off": as a matter of project policy, decide where
- your tags will live, and make sure all users know how to treat
- the directories they copy in there. (That is, make sure they
- know not to commit to them.) The second approach is more
- paranoid: you can use one of the access-control scripts
- provided with Subversion to prevent anyone from doing anything
- but creating new copies in the tags-area (###cross-ref a
- section that demonstrates how to use these scripts?). The
- paranoid approach, however, isn't usually necessary. If a
- user accidentally commits a change to a tag-directory, you can
- simply undo the change as discussed in the previous section.
- This is version control, after all.</para>
+ is <quote>hands off</quote>: as a matter of project policy,
+ decide where your tags will live, and make sure all users know
+ how to treat the directories they copy in there. (That is,
+ make sure they know not to commit to them.) The second
+ approach is more paranoid: you c one of the
+ access-control scripts provided with Subversion to prevent
+ anyone from doing anything but creating new copies in the
+ tags-area (###cross-ref a section that demonstrates how to use
+ these scripts?). The paranoid approach, however, isn't
+ usually necessary. If a user accidentally commits a change to
+ a tag-directory, you can simply undo the change as discussed
+ in the previous section. This is version control, after
+ all.</parceive your exact changes.</para>
</sect2>
@@ -990,8 +999,8 @@
<para>There are some standard, recommended ways to organize a
repository. Most people create a <filename>trunk</filename>
- directory to hold the "main line" of development, a
- <filename>branches</filename> directory to contain branch
+ directory to hold the <quote>main line</quote> of development,
+ a <filename>branches</filename> directory to contain branch
copies, and a <filename>tags</filename> directory to contain
tag copies. If a repository holds only one project, then
often people create these top-level directories:</para>
@@ -1082,14 +1091,15 @@
short lifetime: you may have created it to fix a bug or
implement a new feature. When your task is done, so is the
branch. In software development, though, it's also common to
- have two "main" branches running side-by-side for very long
- periods. For example, suppose it's time to release a stable
- <filename>calc</filename> project to the public, and you know
- it's going to take a couple of months to shake bugs out of the
- software. You don't want people to add new features to the
- project, but you don't want to tell all developers to stop
- programming either. So instead, you create a "stable" branch
- of the software that won't change much:</para>
+ have two <quote>main</quote> branches running side-by-side for
+ very long periods. For example, suppose it's time to release
+ a stable <filename>calc</filename> project to the public, and
+ you know it's going to take a couple of months to shake bugs
+ out of the software. You don't want people to add new
+ features to the project, but you don't want to tell all
+ developers to stop programming either. So instead, you create
+ a <quote>stable</quote> branch of the software that won't
+ change much:</para>
<screen>
$ svn copy http://svn.example.com/repos/trunk/calc \
Index: doc/book/book/ch05.xml
===================================================================
--- doc/book/book/ch05.xml (revision 5360)
+++ doc/book/book/ch05.xml (working copy)
@@ -180,7 +180,7 @@
machine where the repository resides to examine or modify
aspects of the repository, and are in fact unable to perform
tasks across a network. A common mistake made by Subversion
- newcomers is trying to pass URLs (even "local"
+ newcomers is trying to pass URLs (even <quote>local</quote>
<literal>file:</literal> ones) to these two programs.</para>
<para>So, after you've run the <command>svnadmin create</command>
@@ -941,8 +941,9 @@
commands may be specified at a single command prompt,
separated by a semicolon. Also, the shell understands the
notions of relative and absolute paths, and will properly
- handle the "<literal>.</literal>" and
- "<lital>..</literal>" special path components.</para>
+ handle the <quote><literal>.</literal></quote> and
+ <quote><literal>..</literal></quote> special path
+ components.</para>
<para>The <literal>youngest</literal> command displays the
youngest revision. This is useful for determining the range
Index: doc/book/book/ch06.xml
===================================================================
--- doc/book/book/ch06.xml (revision 5360)
+++ doc/book/book/ch06.xml (working copy)
@@ -19,8 +19,8 @@
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 "common
- version control operations".</para>
+ <para>But the Subversion feature set doesn't stop at <quote>common
+ version control operations</quote>.</para>
<para>This chapter highlights some of Subversion's features which
aren't quite so regularly used. In it, we will discuss
Index: doc/book/book/ch07.xml
===================================================================
--- doc/book/book/ch07.xml (revision 5360)
+++ doc/book/book/ch07.xml (working copy)
@@ -104,21 +104,22 @@
</tgroup>
</table>
- <para>The fact that the word "miscellaneous" only appears once in
- Table 7-1 is a good sign. The Subversion development team
- is serious about making sure that functionality lives in the
- right layer and libraries. Perhaps the greatest advantage of
- the modular design is its lack of complexity from a developer's
- point of view. As a developer, you can quickly formulate that
- kind of "big picture" that allows you to pinpoint the location
- of certain pieces of functionality with relative ease.</para>
+ <para>The fact that the word <quote>miscellaneous</quote> only
+ appears once in Table 7-1 is a good sign. The Subversion
+ development team is serious about making sure that functionality
+ in the right layer and libraries. Perhaps the greatest
+ advantage of the modular design is its lack of complexity from a
+ developer's point of view. As a developer, you can quickly
+ formulate that kind of <quote>big picture</quote> that allows
+ you to pinpoint the location of certain pieces of functionality
+ with relative ease.</para>
- <para>And what could better help a developer gain a "big picture"
- perspective than a big picture? To help you understand
- how the Subversion libraries fit together, see Figure 7-1, a
- diagram of Subversion's layers. Program flow begins at the top
- of the diagram (initiated by the user) and flows
- "downward".</para>
+ <para>And what could better help a developer gain a <quote>big
+ picture</quote> perspective than a big picture? To help you
+ understand how the Subversion libraries fit together, see Figure
+ 7-1, a diagram of Subversion's layers. Program flow begins at
+ the top of the diagram (initiated by the user) and flows
+ <quote>downward</quote>.</para>
<!-- Fitz's revised graphic here (Heaven help us if he ever makes
another piece of graphic art ... what *will* we call it?).
@@ -128,7 +129,7 @@
make sure that each library also gives its libsvn_foo name. -->
<figure id="svn-ch7-sect1-dia1">
- <title>Subversion's "Big Picture"</title>
+ <title>Subversion's <quote>Big Picture</quote></title>
<graphic fileref="images/ch07dia1.png"/>
</figure>
@@ -162,16 +163,17 @@
of your version-controlled data. This layer is connected to
the Client Layer via the Repository Access Layer, and is, from
the perspective of the Subversion user, the stuff at the
- "other end of the line."</para>
+ <quote>other end of the line.</quote></para>
<para>The Subversion Filesystem is accessed via the libsvn_fs
API, and is not a kernel-level filesystem that one would
install in rating system (like the Linux ext2 or NTFS),
- but a virtual filesystem. Rather than storing "files" and
- "directories" as real files and directories (as in, the kind
- you can navigate through using your favorite shell program),
- it uses a database system for its back-end storage mechanism.
- Currently, the database system in use is Berkeley DB.
+ but a virtual filesystem. Rather than storing
+ <quote>files</quote> and <quote>directories</quote> as real
+ files and directories (as in, the kind you can navigate
+ through using your favorite shell program), it uses a database
+ system for its back-end storage mechanism. Currently, the
+ database system in use is Berkeley DB.
<footnote>
<para>The choice of Berkeley DB brought several automatic
features that Subversion needed, such as data integrity,
@@ -189,14 +191,14 @@
directories, copy and move them around, modify file contents,
and so on. It also has features that are not quite as common,
such as the ability to add, modify, and remove metadata
- ("properties") on each file or directory. Furthermore, the
- Subversion Filesystem is a versioning filesystem, which means
- that as you make changes to your directory tree, Subversion
- remembers what your tree looked like before those changes.
- And before the previous changes. And the previous ones. And
- so on, all the way back through versioning time to (and just
- beyond) the moment you first started adding things to the
- filesystem.</para>
+ (<quote>properties</quote>) on each file or directory.
+ Furthermore, the Subversion Filesystem is a verng
+ filesystem, which means that as you make changes to your
+ directory tree, Subversion remembers what your tree looked
+ like before those changes. And before the previous changes.
+ And the previous ones. And so on, all the way back through
+ versioning time to (and just beyond) the moment you first
+ started adding things to the filesystem.</para>
<para>All the modifications you make to your tree are done
within the context of a Subversion transaction. The following
@@ -220,7 +222,7 @@
modifications are permanently stored as historical artifacts.
Each of these cycles generates a single new revision of your
tree, and each revision is forever accessible as an immutable
- snapshot of "the way things were."</para>
+ snapshot of <quote>the way things were.</quote></para>
<sidebar>
<title>The Transaction Distraction</title>
@@ -231,11 +233,12 @@
by the underlying database itself. Both types of
transaction exist to provide atomicity and isolation. In
other words, transactions give you the ability to perform a
- set of actions in an "all or nothing" fashion—either
- all the actions in the set complete with success, or they
- all get treated as if <emphasis>none</emphasis> of them ever
- happened—and in a way that does not interfere with
- other processes acting on the data.</para>
+ set of actions in an <quote>all or nothing</quote>
+ fashion—either all the actions in the set complete
+ with success, or they all get treated as if
+ <emphasis>none</emphasis> of them ever happened—and in
+ a way that does not interfere with other processes acting on
+ the data.</para>
<para>Database transactions generally encompass small
operations related specifically to the modification of data
@@ -455,9 +458,10 @@
to yoeloper mailing list), you need to use the
libsvn_repos-wrapped version of that
function—<function>svn_repos_fs_commit_txn</function>.
- This function will actually first run the "pre-commit" hook
- script if one exists, then commit the transaction, and finally
- will run a "post-commit" hook script. The hooks provide a
+ This function will actually first run the
+ <quote>pre-commit</quote> hook script if one exists, then
+ commit the transaction, and finally will run a
+ <quote>post-commit</quote> hook script. The hooks provide a
special kind of reporting mechanism that does not really
belong in the core filesystem library itself. (For more
information regarding Subversion's repository hooks, see <xref
@@ -485,9 +489,9 @@
set of files was modified in the filesystem.</para>
</listitem>
<listitem>
- <para>generate a human-readable "dump" of the filesystem, a
- complete representation of the revisions in the
- filesystem.</para>
+ <para>generate a human-readable <quote>dump</quote> of the
+ filesystem, a complete representation of the revisions in
+ the filesystem.</para>
</listitem>
<listitem>
<para>parse that dump format, loading the dumped revisions
@@ -505,16 +509,16 @@
<sect2 id="svn-ch-7-sect-1.2">
<title>Repository Access Layer</title>
- <para>If the Subversion Repository Layer is at "the other end of
- the line", the Repository Access Layer is the line itself.
- Charged with marshalling data between the client libraries and
- the repository, this layer includes the libsvn_ra module
- loader library, the RA modules themselves (which currently
- includes libsvn_ra_dav, libsvn_ra_local, and libsvn_ra_svn),
- and any additional libraries needed by one or more of those RA
- modules, such as the mod_dav_svn Apache modulewhich
- libsvn_ra_dav communicates or libsvn_ra_svn's server,
- <command>svnserve</command>.</para>
+ <para>If the Subversion Repository Layer is at <quote>the other
+ end of the line</quote>, the Repository Access Layer is the
+ line itself. Charged with marshalling data between the client
+ libraries and the repository, this layer includes the
+ libsvn_ra module loader library, the RA modules themselves
+ (which currently includes libsvn_ra_dav, libsvn_ra_local, and
+ libsvn_ra_svn), and any additional libraries needed by one or
+ more of those RA modules, such as the mod_dav_svn Apache
+ module with which libsvn_ra_dav communicates or
+ libsvn_ra_svn's server, <command>svnserve</command>.</para>
<para>Since Subversion uses URLs to identify its repository
resources, the protocol portion of the URL schema (usually
@@ -522,11 +526,11 @@
<literal>https:</literal>, or <literal>svn:</literal>) is used
to determine which RA module will handle the communications.
Each module registers a list of the protocols it knows how to
- "speak" so that the RA loader can, at runtime, determine which
- module to use for the task at hand. You can determine which
- RA modules are available to the Subversion command-line
- client, and what protocols they claim to support, by running
- <command>svn --version</command>:</para>
+ <quote>speak</quote> so that the RA loader can, at runtime,
+ determine which module to use for the task at hand. You can
+ determine which RA modules are available to the Subversion
+ command-line client, and what protocols they claim to support,
+ by runninmand>svn --version</command>:</para>
<screen>
$ svn --version
@@ -627,15 +631,16 @@
example, if Neon finds the OpenSSL libraries, it allows the
Subversion client to attempt to use SSL-encrypted
communications with the Apache server (whose own mod_ssl can
- "speak the language"). Also, both Neon itself and Apache's
- mod_deflate can understand the "deflate" algorithm (the same
- used by the PKZIP and gzip programs), so requests can be
- sent in smaller, compressed chunks across the wire. Other
- complex features that Subversion hopes to support in the
- future include the ability to automatically handle
- server-specified redirects (for example, when a repository
- has been moved to a new canonical URL) and taking advantage
- of HTTP pipelining.</para>
+ <quote>speak the language</quote>). Also, both Neon itself
+ and Apache's mod_deflate can understand the
+ <quote>deflate</quote> algorithm (the same used by the PKZIP
+ and gzip programs), so requests can be sent in smaller,
+ compressed chunks across the wire. Other complex features
+ that Subversion hopes to support in the future include the
+ ability to automatically handle server-specified redirects
+ (for example, when a repository has been moved to a new
+ canonical URL) and taking advantage of HTTP
+ pipelining.</para>
<!-- Talk about another difference between CVS and Subversion.
CVS users had to specify which auth mechanism to use
@@ -730,7 +735,7 @@
implemented by the client-side libraries exists for the sole
purpose of managing working copies—directories full of
files and other subdirectories which serve as a sort of local,
- editable "reflection" of one or more repository
+ editable <quote>reflection</quote> of one or more repository
locations&mnd propogating changes to and from the
Repository Access layer.</para>
@@ -820,18 +825,20 @@
<para>The first thing you might notice is that Subversion's
datatypes and functions are namespace protected. Every public
- Subversion symbol name begins with <literal>"svn_"</literal>,
- followed by a short code for the library in which the symbol is
- defined (such as <literal>"wc"</literal>,
- <literal>"client"</literal>, <literal>"fs"</literal>, etc.),
- followed by a single underscore (<literal>"_"</literal>) and
- then the rest of the symbol name. Semi-public functions (used
- among source files of a given library but not by code outside
- that library, and found inside the library directories
- themselves) differ from this naming scheme in that instead of a
- single underscore after the library code, they use a double
- underscore (<literal>"__"</literal>). Functions private a given
- source file have no special prefixing, and are declared
+ Subversion symbol name begins with
+ <quote><literal>svn_</literal></quote>, followed by a short code
+ for the library in which the symbol is defined (such as
+ <quote><literal>wc</literal></quote>,
+ <quote><literal>client</literal></quote>,
+ <quote><literal>fs</literal></quote>, etc.), followed by a
+ single underscore (<quote><literal>_</literal></quote>) and then
+ the rest of the symbol name. Semi-public functions (used among
+ source files of a given library but not by code outside that
+ library, and found inside the library directories themselves)
+ differ from this naming scheme in that instead of a single
+ underscore after the library code, they use a double underscore
+ (<quote><literal>__</literal></quote>). Functions private a
+ given source file have no special prefixing, and are declared
<literal>static</literal>. Of course, a compiler isn't
interested in these naming conventions, by definitely help
to clarify the scopy of a given function or datatype.</para>
@@ -842,10 +849,10 @@
<para>Along with Subversion's own datatype, you will see many
references to datatypes that begin with
- <literal>"apr_"</literal>—symbols from the Apache
- Portable Runtime (APR) library. APR is Apache's portability
- library, originally carved out of its server code as an
- attempt to separate the OS-specific bits from the
+ <quote><literal>apr_</literal></quote>—symbols from the
+ Apache Portable Runtime (APR) library. APR is Apache's
+ portability library, originally carved out of its server code
+ as an attempt to separate the OS-specific bits from the
OS-independent portions of the code. The result was a library
that provides a generic API for performing operations that
differ mildly—or wildly—from OS to OS. While
@@ -887,18 +894,18 @@
<para>With remote version control operation as the whole point
of Subversion's existence, it makes sense that some attention
has been paid to internationalization (i18n) support. After
- all, while "remote" might mean "across the office", it could
- just as well mean "across the globe." To facilitate this, all
- of Subversion's public interfaces that accept path arguments
- expect those paths to be canonicalized, and encoded in UTF-8.
- This means, for example, that any new client binary that
- drives the libsvn_client interface needs to first convert
- paths from the locale-specific encoding to UTF-8 before
- passing those paths to the Subversion libraries, and then
- re-convert any resultant output paths from Subversion back
- into the locale's encoding before using those paths for
- non-Subversion purposes. Fortunately, Subversion provides a
- suite of functions (see
+ all, while <quote>remote</quote> might mean <quotes the
+ office</quote>, it could just as well mean <quote>across the
+ globe.</quote> To facilitate this, all of Subversion's public
+ interfaces that accept path arguments expect those paths to be
+ canonicalized, and encoded in UTF-8. This means, for example,
+ that any new client binary that drives the libsvn_client
+ interface needs to first convert paths from the
+ locale-specific encoding to UTF-8 before passing those paths
+ to the Subversion libraries, and then re-convert any resultant
+ output paths from Subversion back into the locale's encoding
+ before using those paths for non-Subversion purposes.
+ Fortunately, Subversion provides a suite of functions (see
<filename>subversion/include/svn_utf.h</filename>) that can be
used by any program to do these conversions.</para>
@@ -994,12 +1001,12 @@
need to pay close attention to memory usage, and need to use
custom datatypes for representing the hash of entries and the
list of paths. Python has hashes and lists (called
- "dictionaries" and "sequences", respectively) as built-in
- datatypes, and provides a wonderful selection of methods for
- operating on those types. And since Python uses reference
- counting and garbage collection, users of the language don't
- have to bother themselves with allocating and freeing
- memory.</para>
+ <quote>dictionaries</quote> and <quote>sequences</quote>,
+ respectively) as built-in datatypes, and provides a wonderful
+ selection of methods for operating on those types. And since
+ Python uses reference counting and garbage collection, users
+ of the language don't have to bother themselves with
+ allocating and freeing memory.</para>
<para>In the previous section of this chapter, we mentioned the
<filename>libsvn_client</filename> interface, and how it
@@ -1177,18 +1184,18 @@
ent Each <sgmltag>entry</sgmltag> tag represents one of
three things: the working copy directory itself (noted by
having its <structfield>name</structfield> attribute set to
- <literal>"svn:this-dir"</literal>), a file in that working
- copy directory (noted by having its
+ <quote><literal>svn:this-dir</literal><quote>), a file in that
+ working copy directory (noted by having its
<structfield>kind</structfield> attribute set to
- <literal>"file"</literal>), or a subdirectory in that working
- copy (<structfield>kind</structfield> here is set to
- <literal>"dir"</literal>). The files and subdirectories whose
- entries are stored in this file are either already under
- version control, or (as in the case of the file named
- <filename>zeta</filename> above) are scheduled to be added to
- version control when the user next commits this working copy
- directory's changes. Each entry has a unique name, and each
- entry has a node kind.</para>
+ <quote><literal>file</literal></quote>), or a subdirectory in
+ that working copy (<structfield>kind</structfield> here is set
+ to <quote><literal>dir</literal></quote>). The files and
+ subdirectories whose entries are stored in this file are
+ either already under version control, or (as in the case of
+ the file named <filename>zeta</filename> above) are scheduled
+ to be added to version control when th for determining the full
set of information about a subdirectory is to traverse down
into that subdirectory, and read the
- <literal>"svn:this-dir"</literal> entry from its own
- <filename>.svn/entries</filename> file. However, a reference
- to the subdirectory is kept in its parent's
+ <quotee><literal>svn:this-dir</literal></quote> entry from its
+ own <filename>.svn/entries</filename> file. However, a
+ reference to the subdirectory is kept in its parent's
<filename>entries</filename> file, with enough information to
permit basic versioning operations in the event that the
subdirectory itself is actually missing from disk.</para>
@@ -1228,34 +1235,35 @@
<title>Pristine Copies and Property Files</title>
<para>As mentioned before, the <filename>.svn</filename>
- directory also holds the pristine "text-base" versions of
- files. Those can be found in
+ directory also holds the pristine <quote>text-base</quote>
+ versions of files. Those can be found in
<filename>.svn/text-base</filename>. The benefits of these
pristine copies are multiple—network-free checks for
- local modifications and "diff" reporting, network-free
- reversion of modified or missing files, smaller transmission
- of changes to the server—but comes at the cost of having
- each versioned file stored at least twice on disk. These
- days, this seems to be a negligible penalty for most files.
- However, the situation gets uglier as the size of your
- versioned files grows. Some attention is being given to
- making the presence of the "text-base" an option. Ironically
- though, it is as your versioned files' sizes get larger that
- the existence of the "text-base" becomes more
- crucial—who wants to transmit a huge file across a
- network just because they want to commit a tiny change to
- it?</para>
+ local modifications and <quote>diff</quote> reporting,
+ network-free reversion of modified or missing files, smaller
+ transmission of changes to the server—but comes at the
+ cost of having each versioned file stored at least twice on
+ disk. These days, this seems to be a negligible penalty for
+ most files. However, the situation gets uglier as the size of
+ your versioned files grows. Some attention is being given to
+ making the presence of the <quote>text-base</quote> an option.
+ Ironically though, it is as your versioned files' sizes get
+ larger that the existence of the <quote>text-base</quote>
+ becomes more crucial—who wants to transmit a huge file
+ across a network just because they want to commit a tiny
+ change to it?</para>
- <para>Similar in purpose to the "text-base" files are the
- property files and their pristine "prop-base" copies, located
- in <filename>.svn/props</filename> and
+ <para>Similar in purpose to the <quote>text-base</quote> files
+ are the property files and their pristine
+ <quote>prop-base</quote> copies, located in
+ <filename>.svn/props</filename> and
<filename>.svn/prop-base</filename> respectively. Since
directories can have properties, too, there are also
<filename>.svn/dir-props</filename> and
<filename>.svn/dir-prop-base</filename> files. Each of these
- property files ("working" and "base" versions) uses a simple
- "hash-on-disk" file format for storing the property names and
- values.</para>
+ property files (<quote>working</quote> and <quote>base</quote>
+ versions) simple <quote>hash-on-disk</quote> file
+ format for storing the property names and values.</para>
</sect2>
@@ -1281,14 +1289,15 @@
<sect1 id="svn-ch-7-sect-4">
<title>WebDAV</title>
- <para>WebDAV ("Web-based Distributed Authoring and Versioning") is
- an extension of the standard HTTP protocol designed to make the
- web into a read/write medium, instead of the basically read-only
- medium that exists today. The theory is that directories and
- files can be shared—as both readable and writable
- objects—over the web. RFCs 2518 and 3256 describe the
- WebDAV/DeltaV extensions to HTTP, and are available (along with
- a lot of other useful information) at <systemitem
+ <para>WebDAV (<quote>Web-based Distributed Authoring and
+ Versioning</quote>) is an extension of the standard HTTP
+ protocol designed to make the web into a read/write medium,
+ instead of the basically read-only medium that exists today.
+ The theory is that directories and files can be shared—as
+ both readable and writable objects—over the web. RFCs
+ 2518 and 3256 describe the WebDAV/DeltaV extensions to HTTP, and
+ are available (along with a lot of other useful information) at
+ <systemitem
class="url">http://www.webdav.org/</systemitem>.</para>
<para>A number of operating system file browsers are already able
@@ -1333,7 +1342,7 @@
program that crashes itself, or worse, crashes the computer.
Fortunately, the APR library that Subversion depends on for
portability provides the <structname>apr_pool_t</structname>
- type, which represents a "pool" of memory.</para>
+ type, which represents a <quote>pool</quote> ofy.</para>
<para>A memory pool is an abstract representation of a chunk of
memory allocated for use by a program. Rather than requesting
@@ -1361,20 +1370,20 @@
gives developers the flexibility to allocate several—or
several thousand— things from the pool, and then clean up
all of that memory with a single function call! Further, pools
- have hierarchy. You can make "subpools" of any previously
- created pool. When you clear a pool, all of its subpools are
- destroyed; if you destroy a pool, it and its subpools are
- destroyed.</para>
+ have hierarchy. You can make <quote>subpools</quote> of any
+ previously created pool. When you clear a pool, all of its
+ subpools are destroyed; if you destroy a pool, it and its
+ subpools are destroyed.</para>
<para>Before we go further, developers should be aware that they
probably will not find many calls to the APR pool functions we
just mentioned in the Subversion source code. APR pools offer
some extensibility mechanisms, like the ability to have custom
- "user data" attached to the pool, and mechanisms for registering
- cleanup functions that get called when the pool is destroyed.
- Subversion makes use of these extensions in a somewhat
- non-trivial way. So, Subversion supplies (and most of its code
- uses) the wrapper functions
+ <quote>user data</quote> attached to the pool, and mechanisms
+ for registering cleanup functions that get called when the pool
+ is destroyed. Subversion makes use of these extensions in a
+ somewhat non-trivial way. So, Subversion supplies (and most of
+ its code uses) the wrapper functions
<function>svn_pool_create()</function>,
<function>svn_pool_clear()</function>, and
<function>svn_pool_destroy()</function>.</para>
@@ -1536,17 +1545,17 @@
<para>But how do you know what needs to be done? It is quite
common for a programmerave the greatest intentions of
- helping out with the development, yet be unable to find a
- good starting point. After all, not many folks come to the
+ helping out with the development, yet be unable to find a good
+ starting point. After all, not many folks come to the
community having already decided on a particular itch they
would like to scratch. But by watching the developer
discussion lists, you might see mentions of existing bugs or
- feature requests fly by that particularly interest
- you. Also, a great place to look for outstanding, unclaimed
- tasks is the Issue Tracking database on the Subversion
- website. There you will find the current list of known bugs
- and feature requests. If you want to start with something
- small, look for issues marked as "bite-sized".</para>
+ feature requests fly by that particularly interest you. Also,
+ a great place to look for outstanding, unclaimed tasks is the
+ Issue Tracking database on the Subversion website. There you
+ will find the current list of known bugs and feature requests.
+ If you want to start with something small, look for issues
+ marked as <quote>bite-sized</quote>.</para>
</sect2>
@@ -1559,13 +1568,14 @@
Subversion source repository. As straightforward as that
might sound, the task can be slightly tricky. Because
Subversion's source code is versioned using Subversion itself,
- you actually need to "bootstrap" by getting a working
- Subversion client via some other method. The most common
- methods include downloading the latest binary distribution (if
- such is available for your platform), or downloading the
- latest source tarball and building your own Subversion client.
- If you build from source, make sure read the INSTALL file in
- the top level of the source tree for instructions.</para>
+ ou actually need to <quote>bootstrap</quote> by getting a
+ working Subversion client via some other method. The most
+ common methods include downloading the latest binary
+ distribution (if such is available for your platform), or
+ downloading the latest source tarball and building your own
+ Subversion client. If you build from source, make sure read
+ the INSTALL file in the top level of the source tree for
+ instructions.</para>
<para>After you have a working Subversion client, you are now
poised to checkout a working copy of the Subversion source
@@ -1618,11 +1628,12 @@
earned—a government by meritocracy.
<footnote>
<para>While this may superficially appear as some sort of
- elitism, this "earn your commit priveleges" notion is
- about efficiency—whether it costs more in time and
- effort to review and apply someone else's changes that are
- likely to be safe and useful, versus the potential costs
- of undoing changes that are dangerous.</para>
+ elitism, this <quote>earn your commit priveleges</quote>
+ notion is about efficiency—whether it costs more in
+ time and effort to review and apply someone else's changes
+ that are likely to be safe and useful, versus the
+ potential costs of undoing changes that are
+ dangerous.</para>
</footnote>
The HACKING file is an invaluable resource when it comes to
making sure that your proposed changes earn the praises they
@@ -1647,9 +1658,10 @@
<para>Subversion has a fairly thorough
<footnote>
- <para>You might want to grab some popcorn. "Thorough", in
- this instance, translates to somewhere around thirty
- minutes of non-interactive machine churn.</para>
+ <para>You might want to grab some popcorn.
+ <quote>Thorough</quote>, in thtance, translates to
+ somewhere around thirty minutes of non-interactive machine
+ churn.</para>
</footnote>
regression test suite, and your proposed changes are expected
to not cause any of those tests to fail. By running
@@ -1692,8 +1704,9 @@
add your changes to the public source code tree. Recall that
permission to directly commit changes to the repository is
granted on merit—if you demonstrate comprehension of
- Subversion, programming competency, and a "team spirit", you
- will likely be awarded that permission.</para>
+ Subversion, programming competency, and a <quote>team
+ spirit</quote>, you will likely be awarded that
+ permission.</para>
</sect2>
</sect1>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Mar 17 20:48:15 2003