[svnbook commit] r2074 - in trunk/src/nb: . book

sunny256 svnbook-dev at red-bean.com
Wed Mar 15 13:37:11 CST 2006

Author: sunny256
Date: Wed Mar 15 13:37:08 2006
New Revision: 2074


Sync the Norwegian and English book, r2056:2073.

  Updated by make sync.

* src/nb/book/ch07.xml
  Merged r2066, r2070, r2072.

  ch07.xml decreased to 26%.

Modified: trunk/src/nb/LAST_UPDATED
--- trunk/src/nb/LAST_UPDATED	(original)
+++ trunk/src/nb/LAST_UPDATED	Wed Mar 15 13:37:08 2006
@@ -1 +1 @@

Modified: trunk/src/nb/TRANSLATION-STATUS
--- trunk/src/nb/TRANSLATION-STATUS	(original)
+++ trunk/src/nb/TRANSLATION-STATUS	Wed Mar 15 13:37:08 2006
@@ -35,7 +35,7 @@
     2.1.2. In progress
-      book/ch07.xml (27%) -- sunny256
+      book/ch07.xml (26%) -- sunny256
     2.1.3. Needs update

Modified: trunk/src/nb/book/ch07.xml
--- trunk/src/nb/book/ch07.xml	(original)
+++ trunk/src/nb/book/ch07.xml	Wed Mar 15 13:37:08 2006
@@ -2472,6 +2472,101 @@
           file will be re-substituted with information that
           reflects the most recent known commit to that file.</para>
+        <para>Subversion 1.2 introduced a new variant of the keyword
+          syntax which brought additional, useful—though perhaps
+          atypical—functionality.  You can now tell Subversion
+          to maintain a fixed length (in terms of the number of bytes
+          consumed) for the substituted keyword.  By using a
+          double-colon (<literal>::</literal>) after the keyword name,
+          followed by a number of space characters, you define that
+          fixed width.  When Subversion goes to substitute your
+          keyword for the keyword and its value, it will essentially
+          replace only those space characters, leaving the overall
+          width of the keyword field unchanged.  If the substituted
+          value is shorter than the defined field width, there will be
+          extra padding characters (spaces) at the end of the
+          substituted field; if it is too long, it is truncated with a
+          special hash (<literal>#</literal>) character just before
+          the final dollar sign terminator.</para>
+        <para>For example, say you have a document in which you have
+          some section of tabular data reflecting the document's
+          Subversion keywords.  Using the original Subversion keyword
+          substitution syntax, your file might look something
+          like:</para>
+        <screen>
+$Rev$:     Revision of last commit
+$Author$:  Author of last commit
+$Date$:    Date of last commit
+        <para>Now, that looks nice and tabular at the start of things.
+          But when you then commit that file (with keyword substitution
+          enabled, of course), you see:</para>
+        <screen>
+$Rev: 12 $:     Revision of last commit
+$Author: harry $:  Author of last commit
+$Date: 2006-03-15 02:33:03 -0500 (Wed, 15 Mar 2006) $:    Date of last commit
+        <para>The result is not so beautiful.  And you might be
+          tempted to then adjust the file after the substitution so
+          that it again looks tabular.  But that only holds as long as
+          the keyword values are the same width.  If the last
+          committed revision rolls into a new place value (say, from
+          99 to 100), or if another person with a longer username
+          commits the file, stuff gets all crooked again.  However, if
+          you are using Subversion 1.2 or better, you can use the new
+          fixed-length keyword syntax, define some field widths that
+          seem sane, and now your file might look like this:</para>
+        <screen>
+$Rev::               $:  Revision of last commit
+$Author::            $:  Author of last commit
+$Date::              $:  Date of last commit
+        <para>You commit this change to your file.  This time,
+          Subversion notices the new fixed-length keyword syntax, and
+          maintains the width of the fields as defined by the padding
+          you placed between the double-colon and the trailing dollar
+          sign.  After substitution, the width of the fields is
+          completely unchanged—the short values for
+          <literal>Rev</literal> and <literal>Author</literal> are
+          padded with spaces, and the long <literal>Date</literal>
+          field is truncated by a hash character:</para>
+        <screen>
+$Rev:: 13            $:  Revision of last commit
+$Author:: harry      $:  Author of last commit
+$Date:: 2006-03-15 0#$:  Date of last commit
+        <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>
+        <warning>
+          <para>Be aware that because the width of a keyword field is
+            measured in bytes, the potential for corruption of
+            multi-byte values exists.  For example, a username which
+            contains some multi-byte UTF-8 characters might suffer
+            truncation in the middle of the string of bytes which make
+            up one of those characters.  The result will be a mere
+            truncation when viewed at the byte level, but will likely
+            appear as a string with an incorrect or garbled final
+            character when viewed as UTF-8 text.  It is conceivable
+            that certain applications, when asked to load the file,
+            would notice the broken UTF-8 text and deem the entire
+            file corrupt, refusing to operate on the file
+            altogether.</para> 
+        </warning>
       <sect3 id="svn.advanced.props.special.eol-style">
@@ -3291,18 +3386,19 @@
   <sect1 id="svn.advanced.pegrevs">
     <title>Peg and Operative Revisions</title>
-    <para>The ability to copy, move, and rename files and directories;
-      to be able to create an object, then delete it and then add a
-      new one at the same path—those are operations which we
-      perform on files and directories on our computers all the time,
-      and operations we tend to take for granted.  And Subversion
-      would like you to think they are granted.  Subversion's file
-      management support is quite liberating, affording almost as much
+    <para>We make use of the ability to copy, move, rename, and
+      completely replace files and directories on our computers all
+      that time.  And your version control system shouldn't get in the
+      way of your doing these things with your version controlled
+      files and directories, either.  Subversion's file management
+      support is quite liberating, affording almost as much
       flexibility for versioned files that you'd expect when
       manipulating your unversioned ones.  But that flexibility means
       that across the lifetime of your repository, a given versioned
       resource might have many paths, and a given path might represent
-      several entirely different versioned resources.</para>
+      several entirely different versioned resources.  And this
+      introduces a certain level of complexity to your interactions
+      with those paths and resources.</para>
     <para>Subversion is pretty smart about noticing when an object's
       version history includes such <quote>changes of address</quote>.
@@ -3487,7 +3583,7 @@
 svn: Unable to find repository location for 'concept/IDEA' in revision 1
-    <para>And when executed, has the expected results.  Peg revisions
+    <para>And when executed, it has the expected results.  Peg revisions
       generally default to a value of <literal>BASE</literal> (the
       revision currently present in the working copy) when applied to
       working copy paths, and of <literal>HEAD</literal> when applied

More information about the svnbook-dev mailing list