[svnbook] r4040 committed - Merge from ^/trunk/en r4039, minus the allusion to a libmagic...

[svnbook at googlecode.com]

Revision: 4040
Author:   cmpilato at gmail.com
Date:     Mon Aug 29 08:23:43 2011
Log:      Merge from ^/trunk/en r4039, minus the allusion to a libmagic
integration.  An updated log message might read like so:

    Finish issue #96 ("ch03: svn:keywords failing on UTF-16 files as they
    are treated binary").

    * en/book/ch03-advanced-topics.xml
      (svn.advanced.props.auto): Mention the UTF-16 complication.
      (svn.advanced.props.special.mime-type): Remove some text redundant
        with, and now include a pointer to, the Automatic Property Setting
        section.
      (svn.advanced.props.special.keywords): Mention that keyword
        substitution only happens on non-binary files.

http://code.google.com/p/svnbook/source/detail?r=4040

Modified:
  /branches/1.6/en
  /branches/1.6/en/book/ch03-advanced-topics.xml

=======================================
--- /branches/1.6/en/book/ch03-advanced-topics.xml	Mon Aug 15 12:29:10 2011
+++ /branches/1.6/en/book/ch03-advanced-topics.xml	Mon Aug 29 08:23:43 2011
@@ -1305,9 +1305,10 @@
          mapping, it will set your file's
          <literal>svn:mime-type</literal> property to the MIME type it
          found.  If no mapping file is configured, or no mapping for
-        your file's extension could be found, Subversion runs a very
-        basic heuristic to determine whether the file contains nontextual
-        content.  If so, it automatically sets the
+        your file's extension could be found, Subversion will fall
+        back to its
+        own very basic heuristic to determine whether the file
+        contains nontextual content.  If so, it automatically sets the
          <literal>svn:mime-type</literal> property on that file to
          <literal>application/octet-stream</literal> (the generic
          <quote>this is a collection of bytes</quote> MIME type).  Of
@@ -1320,6 +1321,17 @@
          linkend="svn.advanced.props.special.mime-type" /> later in
          this chapter.)</para>

+      <note>
+        <para>UTF-16 is commonly used to encode files whose semantic
+          content is textual in nature, but the encoding itself makes
+          heavy use of bytes which our outside the typical ASCII
+          character byte range.  As such, Subversion will tend to
+          classify such files as binary files, much to the chagrin of
+          users who desire line-based differencing and merging,
+          keyword substitution, and other behaviors for those
+          files.</para>
+      </note>
+
        <para>Subversion also provides, via its runtime configuration
          system (see <xref linkend="svn.advanced.confarea" />), a more
          flexible automatic property setting feature that allows you
@@ -1498,11 +1510,10 @@
            property.</para>
        </warning>

-      <para>Users can configure the <literal>mime-types-file</literal>
-        runtime configuration parameter, which identifies the location
-        of a MIME types mapping file.  Subversion will consult this
-        mapping file to determine the MIME type of newly added and
-        imported files.</para>
+      <para>Subversion provides a number of mechanisms by which to
+        automatically set the <literal>svn:mime-type</literal>
+        property on a versioned file.  See
+        <xref linkend="svn.advanced.props.auto" /> for details.</para>

        <para>Also, if the <literal>svn:mime-type</literal> property is
          set, then the Subversion Apache module will use its value to
@@ -2326,13 +2337,27 @@
  $Date:: 2006-03-15 0#$:  Date of last commit
  </screen>
      </informalexample>
-
-    <para>The use of fixed-length keywords is especially handy
-      when performing substitutions into complex file formats that
-      themselves use fixed-length fields for data, or for which
-      the stored size of a given data field is overbearingly
-      difficult to modify from outside the format's native
-      application (such as for Microsoft Office documents).</para>
+
+    <para>The use of fixed-length keywords is especially handy when
+      performing substitutions into complex file formats that
+      themselves use fixed-length fields for data, or for which the
+      stored size of a given data field is overbearingly difficult to
+      modify from outside the format's native application (as is true
+      for the older Microsoft Office document formats).</para>
+
+    <note>
+      <para>Subversion will only perform keyword substitution on files
+        that it considers to be human-readable—this is, files
+        which don't carry an <literal>svn:mime-type</literal> property
+        whose value indicates otherwise.  To force keyword
+        substitution on binary files, you'll need to either lie or
+        feign ignorance about their true content type.  Understand,
+        however, that doing so will also enable for those files other
+        Subversion behaviors that you might not desire, including
+        line-based differencing and merging.  For more about content
+        types, see <xref linkend="svn.advanced.props.special.mime-type"
+        />.</para>
+    </note>

      <warning>
        <para>Be aware that because the width of a keyword field is