[SvnBook] #26: long list of suggestions

[SvnBook]

#26: long list of suggestions
----------------------+-----------------------------------------------------
  Reporter:  sussman  |       Owner:  nobody
      Type:  task     |      Status:  new   
  Priority:  normal   |   Milestone:        
 Component:  content  |     Version:        
Resolution:           |    Keywords:        
----------------------+-----------------------------------------------------
Comment (by cmpilato):

 Here is that prose portion, so you don't have to reference the attachment
 any more.

 ----

 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. 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.

 5. 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.

 6. 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").

-- 
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/26#comment:2>
SvnBook <http://svnbook.red-bean.com/>