[Niggles in chapters 0,1,2,3]
Thanks for proof-reading the book and submitting these patches. I agree with all of your changes in chapters 0, 1 and 2, and most of these in chapter 3 (exceptions below).
Please could you read the file "HACKING" in the root directory, at least the parts of it that describe submitting a patch. In particular, it would be helpful if you could format your log message in the required way. Since there are rather few changes in each chapter, and they are generally of the same kind in different chapters, it would be appropriate to make a single patch containing all of them.
Here is a partial log message to get you started. It begins with a brief summary of the reason for the patch, and then summarises what was changed in each file.
[[[
Fix niggles in the book.
Patch submitted by Chris Pepper <pepper@reppep.com>.
* doc/book/book/ch00.xml:
Consistently use "command-line" rather than "commandline".
Capitalise ASCII, as it is an acronym. [if you find others, you could just say "Capitalise acronyms."]
Remove spaces around '—' to conform with the style guide.
* doc/book/book/ch01.xml:
[...]
* doc/book/book/ch02.xml:
[...]
* doc/book/book/ch03.xml:
Clean up some redundant and awkward wording. [this single summary is enough to cover several of the changes]
[...]
]]]
Chris Pepper wrote:
> "specify a date by specifying the date" is redundant.
Yes.
> As written, .svn sounds like a read-only area; the injunction is
> really against direct manipulation.
I disagree that the wording makes it sound read-only (it is at worst ambiguous) and that appending "directly" clears up any such confusion. Anyway, indirect manipulation is also wrong except via Subversion itself. Perhaps the sentence is not as clear as it could be, but I don't think this particular change helps.
> "This places your working copy into" is awkward. I believe "This
> places your working copy in" is more correct, but am not certain.
Yes.
> The most important thing about svn add is that it adds, not that
> it's deferred.
Yes.
>> - changes coming from the repository didn't overlap in any
>> - way.</para>
>> + changes coming from the repository didn't overlap.</para>
>
> But of course, Subversion can't guarantee there's no (semantic)
> overlap. Tone it down to what can be guaranteed.
Yes. (Appending "with them" (i.e., with the local changes) would be better still, otherwise the clause can be interpreted as "the changes from the repository didn't overlap with each other".)
> Even better, specify in
> the text that the test used is for changes which affect the same line,
> or whatever svn uses internally.
That would be a possible enhancement to the text if the true test (which also takes into account changes to adjacent and nearby lines) can be described very concisely, but I don't think it is necessary here.
(If you write a formal log message of these changes for us, remember to leave this speculative sentence out of it and just mention the changes that you are making in this patch.)
> Rephrase active use of "log" (which implies adding/editing the log)
> to passive use (for reviewing existing log entries).
Yes.
> The final change is for a complicated sentence with three parts,
> which as written implied all three parts (including the transaction
> itself and discarding the log) take place before the transaction. I have
> tried to disentangle it with minimal revision.
I don't like the version in your patch. It still doesn't separate the clauses enough.
> Alternatively, change:
>
> Before changing anything it writes its intentions to a log file, then
> executes the commands in the log file, and finally removes the log file
> (this is similar in design to a journaled filesystem).
>
> to:
>
> Before changing the repository, Subversion writes its intentions to a
Not the repository, but the working copy.
> log file. Next it executes the commands in the log file to apply the
> requested change. Finally, Subversion removes the log file.
> Architecturally, this is similar to a journaled filesystem).
Apart from that error, this version is good.
Thanks again, and if you are happy to produce a revised, combined patch with a standard-format log message, that would be lovely. Even if you don't we'll still gratefully use your submissions.
- Julian
> Chris Pepper
>
> Index: ch03.xml
> ===================================================================
> --- ch03.xml (revision 11198)
> +++ ch03.xml (working copy)
> @@ -201,7 +201,7 @@
> <title>Revision Dates</title>
> <para>Anywhere that you specify a revision number or revision
> - keyword, you can also specify a date by specifying the date
> + keyword, you can also specify a date
> inside curly braces <quote>{}</quote>. You can even access
> a range of changes in the repository using both dates and
> revisions together!</para>
> @@ -370,7 +370,7 @@
> <filename>.svn</filename>. Usually, directory listing
> commands won't show this subdirectory, but it is nevertheless
> an important directory. Whatever you do, don't delete or
> - change anything in the administrative area! Subversion
> + change anything in the administrative area directly! Subversion
> depends on it to manage your working copy.</para>
>
> </sidebar>
> @@ -378,7 +378,7 @@
> <para>While you can certainly check out a working copy with the
> URL of the repository as the only argument, you can also specify
> a directory after your repository URL. This places your working
> - copy into the new directory that you name. For example:</para>
> + copy in the new directory that you name. For example:</para>
> <screen>
> $ svn checkout http://svn.collab.net/repos/svn/trunk subv
> @@ -636,7 +636,7 @@
> become a child of its parent directory. Note that if
> <filename>foo</filename> is a directory, everything
> underneath <filename>foo</filename> will be scheduled
> - for addition. If you only want to schedule
> + for addition. If you only want to add
> <filename>foo</filename> itself, pass the
> <option>--non-recursive</option> (<option>-N</option>)
> switch.</para>
> @@ -917,7 +917,7 @@
> might have a file in the repository, but you removed
> the file and created a directory in its place, without
> using the <command>svn delete</command> or
> - <command>svn add</command> commands.</para>
> + <command>svn add</command> command.</para>
> </listitem>
> </varlistentry>
>
> @@ -1259,8 +1259,7 @@
> from the repository. The <computeroutput>G</computeroutput>
> stands for mer<computeroutput>G</computeroutput>ed, which
> means that the file had local changes to begin with, but the
> - changes coming from the repository didn't overlap in any
> - way.</para>
> + changes coming from the repository didn't overlap.</para>
> <para>But the <computeroutput>C</computeroutput>
> stands for
> conflict. This means that the changes from the server overlapped
> @@ -1703,7 +1702,7 @@
> <sect2 id="svn-ch-3-sect-5.1">
> <title><command>svn log</command></title>
>
> - <para>To find out information about the history of a file or
> + <para>To find information about the history of a file or
> directory, use the <command>svn log</command>
> command. <command>svn log</command> will provide you with a
> record of who made changes to a file or directory, at what
> @@ -1799,12 +1798,12 @@
> supply no path, Subversion uses the current working
> directory as the default target. As a result, if you're
> operating in a subdirectory of your working copy and attempt
> - to log a revision in which neither that directory nor any of
> - its children was changed, Subversion will give you an empty
> - log. If you want to see what changed in that revision, try
> - pointing <command>svn log</command> directly at the top-most
> - URL of your repository, as in <command>svn log -r 2
> - http://svn.collab.net/repos/svn</command>.</para>
> + to see the log of a revision in which neither that directory
> + nor any of its children was changed, Subversion will show you
> + an empty log. If you want to see what changed in that
> + revision, try pointing <command>svn log</command> directly at
> + the top-most URL of your repository, as in <command>svn log -r
> + 2 http://svn.collab.net/repos/svn</command>.</para>
>
> </sidebar>
> @@ -2047,9 +2046,9 @@
>
> <para>When Subversion modifies your working copy (or any
> information within <filename>.svn</filename>), it tries to do
> - so as safely as possible. Before changing anything, it writes
> - its intentions to a log file, executes the commands in the log
> - file, then removes the log file (this is similar in design to
> + so as safely as possible. Before changing anything it writes
> + its intentions to a log file, then executes the commands in the
> log
> + file, and finally removes the log file (this is similar in
> design to
> a journaled filesystem). If a Subversion operation is
> interrupted (if the process is killed, or if the machine
> crashes, for example), the log files remain on disk. By
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Oct 2 14:41:55 2004