[PATCH] Various svnbook fixes
Max Bowsher
maxb at ukf.net
Wed Aug 17 06:31:28 CDT 2005
Michael W Thelen wrote:
> Øyvind A. Holm wrote:
>> I’ve had a working copy with lots of small fixes to the book lying
>> around for ages, with more small tweaks added over time, so maybe it’s
>> about time I pass it on. No word wrapping is done to make the patch
>> cleaner. There is no formal log message in this stage of the review,
>> it’s much less work to sort that out afterwards when the patch has been
>> filtered a bit. It’s only trivial changes anyway. But some explanation
>> can be done:
>
> It's been a while since this patch, but it looks like the changes
> haven't been applied or reviewed other than the "using RCS as a backend"
> changes. Should I file this as a patch issue in the issue tracker?
Miscellaneous cleanup patches tend to get forgotten in the issue tracker.
I've cleaned up the patch and updated it (mostly) to apply to the current
source.
Let's discuss it - here's my thoughts.
Index: appa.xml
===================================================================
--- appa.xml (revision 1614)
+++ appa.xml (working copy)
@@ -25,7 +25,7 @@
<title>Revision Numbers Are Different Now</title>
<para>In CVS, revision numbers are per-file. This is because CVS
- uses RCS as a backend; each file has a corresponding RCS file in
+ stores its data in RCS files; each file has a corresponding RCS file
in
the repository, and the repository is roughly laid out according
to the structure of your project tree.</para>
New wording as suggested by Ben. OK to apply?
Index: src/en/book/ch01.xml
===================================================================
--- src/en/book/ch01.xml (revision 1533)
+++ src/en/book/ch01.xml (working copy)
@@ -453,9 +453,11 @@
<para>This command creates a new directory
<filename>/path/to/repos</filename> which contains a Subversion
- repository. Make sure that this directory lives on a local
+ repository. If you are creating a Berkeley DB repository (i.e.
+ using the <option>--fs-type=bdb</option> option with the
+ <command>svnadmin</command> command), make sure that this directory
lives on a local
disk, <emphasis>not</emphasis> a network share. This new
- directory mainly contains a collection of Berkeley DB database
+ directory mainly contains a collection of database
files. You won't see your versioned files if you peek inside.
For more information about repository creation and maintenance,
see <xref linkend="svn.reposadmin"/>.</para>
The mention of network shares has gone from ch01 entirely. This change does
not apply.
Index: ch02.xml
===================================================================
--- ch02.xml (revision 1614)
+++ ch02.xml (working copy)
@@ -54,7 +54,7 @@
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
+ he 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.
The use of 'they' as a gender-agnostic singular pronoun is pretty common, if
perhaps not strictly grammatical. I would leave it.
@@ -531,8 +531,8 @@
number selects an entire tree, a particular state of the
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 <quote>revision 5 of
+ the repository filesystem after the Nth commit. When
+ Subversion users talk 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
Ditto, I don't feel that this is necessary.
Index: ch03.xml
===================================================================
--- ch03.xml (revision 1614)
+++ ch03.xml (working copy)
@@ -178,7 +178,7 @@
$ svn diff --revision HEAD
# compares your working file (with local mods) to the latest version
-# in the repository.
+# in the repository
$ svn diff --revision BASE:HEAD foo.c
# compares your <quote>pristine</quote> foo.c (no local mods) with the
Good for consistency, but if _this_ full stop is going away, so should the
others ~15 lines below.
@@ -1713,7 +1713,7 @@
<varlistentry>
<term><command>svn log</command></term>
<listitem>
- <para>Shows you broad information: log messages attached
+ <para>Shows you broad information: log messages with date and
author information attached
to revisions, and which paths changed in each
revision.</para>
</listitem>
Good, I think
.
Index: ch04.xml
===================================================================
--- ch04.xml (revision 1614)
+++ ch04.xml (working copy)
@@ -644,7 +644,7 @@
tree-changes.</para>
</footnote>
The <command>svn merge</command> command, however, can express
- tree-changes by directly applying them to your working
+ changes in tree structure and properties by directly applying
them to your working
copy.</para>
</sidebar>
De-jargonizing! Good!
@@ -885,7 +885,7 @@
Somebody can then run <command>svn log -r9238</command> to
read about the exact changeset which fixed the bug, and run
<command>svn diff -r9237:9238</command> to see the patch
- itself. And Subversion's merge command also uses revision
+ itself. And Subversion's <command>merge</command> command also
uses revision
numbers. You can merge specific changesets from one branch
to another by naming them in the merge arguments:
<command>svn merge -r9237:9238</command> would merge
Here we need to determine a convention. Does a subcommand name without a
leading "svn" go in <command/> tags? Think especially of the case of "diff"
which is a unix command in its own right. Elsewhere in the book, these have
been put into <literal/> tags... which might actually end up formatted the
same, now I think about it. Further instances of this kind of change are
snipped from this email.
@@ -1010,18 +1010,18 @@
...
notice that they're unrelated and first attempt to delete
the old file, then add the new file; you would see a
- <literal>D foo.c</literal> followed by a <literal>A
- foo.c</literal>.</para>
+ <literal>D foo.c</literal> followed by a
+ <literal>A foo.c</literal>.</para>
Good. Do we need to check for more cases like this?
...
@@ -1319,7 +1319,7 @@
directory, it may be gone from the <literal>HEAD</literal>
revision, but the object still exists in earlier revisions.
One of the most common questions new users ask is, <quote>How
- do I get my old file or directory back?</quote></para>
+ do I get my old file or directory back?</quote>.</para>
<para>The first step is to define exactly <emphasis
role="bold">which</emphasis> item you're trying to resurrect.
Yes.
...
@@ -1910,7 +1910,7 @@
changes made to your working copy, and you'd like a
collaborator to see them. Instead of running <command>svn
diff</command> and sending a patch file (which won't capture
- tree changes), you can instead use <command>svn copy</command>
+ tree changes, symlink changes or changes in properties), you can
instead use <command>svn copy</command>
to <quote>upload</quote> your working copy to a private area
of the repository. Your collaborator can then either checkout
a verbatim copy of your working copy, or use <command>svn
Yes.
@@ -1983,8 +1983,8 @@
working copies. If a user has a working copy of a particular
repository directory, your <command>svn move</command>
operation might remove the path from the latest revision.
- When the user next runs <command>svn update</command>, they'll
- be told that their working copy represents a path that no
+ When the user next runs <command>svn update</command>, she will
+ be told that her working copy represents a path that no
longer exists, and the user will be forced to <command>svn
switch</command> to the new location.
</para>
Ditto previous comments on "they", but un-contracting is good.
@@ -2039,7 +2039,7 @@
branch. In software development, though, it's also common to
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
+ a stable version of the <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
Yes.
Index: ch05.xml
===================================================================
--- ch05.xml (revision 1614)
+++ ch05.xml (working copy)
@@ -1120,7 +1120,7 @@
other queries, displaying subsets of bits of information
we've mentioned previously, reporting which paths were
modified in a given revision or transaction, showing textual
- and property differences made to files and directories, and
+ and property differences made to files, symlinks and directories,
and
so on. The following is a brief description of the current
list of subcommands accepted by <command>svnlook</command>,
and the output of those subcommands:</para>
Symlinks can sort of be considered a kind of file... and leaving it out here
avoids confusing people who don't know about symlinks.
...
@@ -2020,7 +2020,7 @@
equal to the size of the original data, it only takes up
enough space to say, <quote>I look just like this other
piece of data over here, except for the following couple of
- changes.</quote> Specifically, each time a new version of a
+ changes</quote>. Specifically, each time a new version of a
file is committed to the repository, Subversion encodes the
previous version (actually, several previous versions) as a
delta against the new version. The result is that most of
Yes.
@@ -2237,7 +2237,7 @@
requested range of revisions. Note that <command>svnadmin
dump</command> is reading revision trees from the repository
just like any other <quote>reader</quote> process would
- (<command>svn checkout</command>, for example.) So it's safe
+ (<command>svn checkout</command>, for example). So it's safe
to run this command at any time.</para>
<para>The other subcommand in the pair, <command>svnadmin
Yes.
@@ -2451,7 +2451,7 @@
<command>cvs2svn</command> utility (see <xref
linkend="svn.forcvs.convert"/>) uses the dump format to represent
the
contents of a CVS repository so that those contents can be
- moved in a Subversion repository.</para>
+ copied into a Subversion repository.</para>
</sect2>
Yes.
Index: ch06.xml
===================================================================
--- ch06.xml (revision 1614)
+++ ch06.xml (working copy)
@@ -5,7 +5,7 @@
<para>A Subversion repository can be accessed simultaneously by
clients running on the same machine on which the repository
- resides using the <literal>file:///</literal> method. But the
+ resides using the <literal>file://</literal> method. But the
typical Subversion setup involves a single server machine being
accessed from clients on computers all over the office—or,
perhaps, all over the world.</para>
I think this should stay as is. People who don't care about the details will
be more likely to get it right, and people who do care will understand that
the third slash is in recognition of the fact that the file:// URL scheme
authority component should be left empty.
@@ -398,7 +398,7 @@
<para>If the client successfully authenticates by any of the
methods listed above, it will attempt to cache the credentials
on disk (unless the user has disabled this behavior, as
- mentioned earlier.)</para>
+ mentioned earlier).</para>
</sect2>
@@ -512,7 +512,7 @@
repository directly needs to have proper read and write
permissions on the entire repository. If you're not
careful, this can lead to a number of headaches, especially
- if you're using a BerkeleyDB database rather than FSFS. Be
+ if you're using a Berkeley DB database rather than FSFS. Be
sure to read <xref
linkend="svn.serverconfig.multimethod"/>.</para>
<para>Secondly, when configuring <command>svnserve</command>,
@@ -645,7 +645,7 @@
client displays it in the authentication prompt, and uses it
as a key (along with the server's hostname and port) for
caching credentials on disk (see <xref
- linkend="svn.serverconfig.netmodel.credcache"/>.) The
+ linkend="svn.serverconfig.netmodel.credcache"/>). The
<literal>password-db</literal> variable points to a separate
file that contains a list of usernames and passwords, using
the same familiar format. For example:</para>
@@ -823,7 +823,7 @@
<para>You'd think that the story of SSH tunneling would end
here, but it doesn't. Subversion allows you to create custom
tunnel behaviors in your run-time <filename>config</filename>
- file (see <xref linkend="svn.advanced.confarea"/>.) For example,
+ file (see <xref linkend="svn.advanced.confarea"/>). For example,
suppose you want to use RSH instead of SSH. In the
<literal>[tunnels]</literal> section of your
<filename>config</filename> file, simply define it like
@@ -842,7 +842,7 @@
scenes. If you include a username in the URL (for example,
<literal>svn+rsh://username@host/path</literal>) the client
will also include that in its command (<command>rsh
- username at host svnserve -t</command>.) But you can define new
+ username at host svnserve -t</command>). But you can define new
tunneling schemes to be much more clever than that:</para>
<screen>
@@ -1016,7 +1016,7 @@
available to clients via the WebDAV/DeltaV protocol, which is an
extension to HTTP 1.1
(see <systemitem class="url">http://www.webdav.org/</systemitem>
- for more information.) This protocol takes the ubiquitous HTTP
+ for more information). This protocol takes the ubiquitous HTTP
protocol that is the core of the World Wide Web, and adds
writing—specifically, versioned
writing—capabilities. The result is a standardized,
@@ -1497,7 +1497,7 @@
will be cached in your private run-time
<filename>auth/</filename> area in just the same way your
username and password are cached (see <xref
- linkend="svn.serverconfig.netmodel.credcache"/>.) If cached,
Subversion will
+ linkend="svn.serverconfig.netmodel.credcache"/>). If cached,
Subversion will
automatically remember to trust this certificate in future
negotiations.</para>
@@ -2248,7 +2248,7 @@
</screen>
<para>Another common problem is often encountered on Unix-like
- systems. As a repository is used, BerkeleyDB occasionally
+ systems. As a repository is used, Berkeley DB occasionally
creates new log files to journal its actions. Even if the
repository is wholly owned by the <command>svn</command> group,
these newly created files won't necessarily be owned by that
Yes to all of the above.
Max.
More information about the svnbook-dev
mailing list