some small fixes

[Malte Helmert]

Hello,

I have attached a patch that fixes some minor omissions and imprecisions
in the current trunk. I don't know if the policy is to post a single
patch for everything or individual patches per change, so apologies in
advance if this should be in bad shape.

I also noticed a few things I could not resolve myself because I do not
know how to resolve them; these are discussed in the following.


1. This is more of a general issue than an individual problem. One
occurrence is around line 2197 in ch03.xml:
        version control; see
        <xref linkend="svn.advanced.locking.meanings"/> for
        clarification.</para>
Another is in around line 2075 in ch05.xml:
        the repository; see
        <xref linkend="svn.advanced.locking.meanings"/> for more
        information.)</para>

There are similar references elsewhere.

In the PDF version of the book, the examples above resolve to "see Three
meanings of 'lock' for more information".

One minor quibble I have with this is that the title "Three meanings of
'lock'" should have some formatting to distinguish it from the
surrounding text (e.g., it could be typeset in italics).

More importantly, there is no easy way to find the target of the
reference. Upon first reading, I thought it was a chapter or section
title and turned to the table of contents, without luck, as the target
is a "gray box", and these aren't listed in the table of contents or
table of figures. The only way to find the target on p. 142 (the links
above are from pages 42 and 89) is to leaf through the whole book.

Two possible fixes: Include the page number in the link, or add some
"table of gray boxes".

I don't know if (or how easily) the PDF toolchain supports either of
these changes -- if this is a known issue that cannot be resolved, I
apologize for the noise.


2. Around line 1730 in ch04.xml:

   <para>Note that while it's okay for your working copy to reflect a
      mixture of repository locations, these locations must all be
      within the <emphasis>same</emphasis> repository.  Subversion
      repositories aren't yet able to communicate with one another;
      that's a feature planned beyond Subversion
      1.0.

Given that Subversion 1.0 is quite old now, "planned beyond Subversion
1.0" should probably be rephrased, either to "planned for the future" or
preferably to something more precise. On the other hand, if this feature
has been planned but not implemented for a long time, maybe it's best to
drop the last part altogether, so that people don't hold their breath
waiting.


3. Around line 2119 in ch06.xml:

   ViewVC was originally written to display CVS repositories
   through the web,
   <footnote><para>Back then, it was called
       <quote>ViewCVS</quote>.</para>
   </footnote>
   and the latest bleeding-edge versions (at
   the time of writing) are able to understand Subversion
   repositories as well.</para>

As far as I can tell, this was written in January 2004 in revision 412,
so I would suggest removing the "bleeding edge" reference.


4. Around line 3421 in ch07.xml:

   <para>Note that while the repository demands UTF-8 filenames and
        log messages, it <emphasis>does not</emphasis> pay attention
        to file contents.  Subversion treats file contents as opaque
        strings of bytes, and neither client nor server makes an
        attempt to understand the character set or encoding of the
        contents.</para>

How does this relate to svn:eol-style?


5. Chapter 9 contains many lines of preformatted text that extend beyond
the bounds of the paper, and thus cannot be read in the printed version.
I suppose it is not worth fixing those before Trac ticket #9 is dealt
with, though.


6. Around line 1293 in ch05.xml:

   <varlistentry>
       <term><literal>deltify</literal></term>
       <listitem>
           <para>Run over a specified revision range, performing
                predecessor deltification on the paths changed in
                those revisions.  If no revisions are specified, this
                command will simply deltify the
                <literal>HEAD</literal> revision.</para>
       </listitem>
   </varlistentry>

Contrast with around line 4360 in ch09.xml:

   This command is deprecated and no longer needed.

I would suggest changing the text in Chapter 5 to point out that the
command is no longer needed and remove its description there.


7. Appendix B seems to be much less carefully edited than the rest of
the book (see also the large number of language mistakes fixed by the
patch), and also its style is somewhat different from the rest of the
book (e.g. in "We've had nothing but success with these products").



That's it, apologies for the long post, and thanks for the great book!

To me, the Subversion book is *the* shining example of good free
documentation. I am excited to hear that a 2nd edition of the O'Reilly
version is in the works.

Malte

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: svnbook-diff
URL: <http://www.red-bean.com/pipermail/svnbook-dev/attachments/20061223/c4d1a3df/attachment.ksh>