[svnbook] r4501 committed - * en/book/ch03-advanced-topics.xml...

svnbook at googlecode.com svnbook at googlecode.com
Tue May 28 16:23:36 CDT 2013


Revision: 4501
Author:   cmpilato at gmail.com
Date:     Tue May 28 14:23:29 2013
Log:      * en/book/ch03-advanced-topics.xml
   (#svn.advanced.props.special.keywords): Document the new custom
     keywords feature of Subversion 1.8.

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

Modified:
  /trunk/en/book/ch03-advanced-topics.xml

=======================================
--- /trunk/en/book/ch03-advanced-topics.xml	Wed Mar 20 06:52:29 2013
+++ /trunk/en/book/ch03-advanced-topics.xml	Tue May 28 14:23:29 2013
@@ -2953,11 +2953,97 @@
        formatted as
         
<literal>$</literal><replaceable>KeywordName</replaceable><literal>$</literal>.</para>

+    <para>Adding keyword anchor text alone to your file does nothing
+      special.  Subversion will never attempt to perform textual
+      substitutions on your file contents unless explicitly asked to
+      do so.  After all, you might be writing a
+      document<footnote><para>… or maybe even a section of a
+      book …</para></footnote> about how to use keywords, and
+      you don't want Subversion to substitute your beautiful examples
+      of unsubstituted keyword anchors!</para>
+
+    <para>To tell Subversion whether to substitute keywords
+      on a particular file, we again turn to the property-related
+      subcommands.  The <literal>svn:keywords</literal> property,
+      when set on a versioned file, controls which keywords will
+      be substituted on that file.  The value is a space-delimited
+      list of keyword names or aliases.</para>
+
+    <para>For example, say you have a versioned file named
+      <filename>weather.txt</filename> that looks like
+      this:</para>
+
+    <informalexample>
+      <programlisting>
+Here is the latest report from the front lines.
+$LastChangedDate$
+$Rev$
+Cumulus clouds are appearing more frequently as summer approaches.
+</programlisting>
+    </informalexample>
+
+    <para>With no <literal>svn:keywords</literal> property set on
+      that file, Subversion will do nothing special.  Now, let's
+      enable substitution of the
+      <literal>LastChangedDate</literal> keyword.</para>
+
+    <informalexample>
+      <screen>
+$ svn propset svn:keywords "Date Author" weather.txt
+property 'svn:keywords' set on 'weather.txt'
+$
+</screen>
+    </informalexample>
+
+    <para>Now you have made a local property modification on the
+      <filename>weather.txt</filename> file.  You will see no
+      changes to the file's contents (unless you made some of your
+      own prior to setting the property).  Notice that the file
+      contained a keyword anchor for the <literal>Rev</literal>
+      keyword, yet we did not include that keyword in the property
+      value we set.  Subversion will happily ignore requests to
+      substitute keywords that are not present in the file and
+      will not substitute keywords that are not present in the
+      <literal>svn:keywords</literal> property value.</para>
+
+    <para>Immediately after you commit this property change,
+      Subversion will update your working file with the new
+      substitute text.  Instead of seeing your keyword anchor
+      <literal>$LastChangedDate$</literal>, you'll see its
+      substituted result.  That result also contains the name of
+      the keyword and continues to be delimited by the dollar sign
+      (<literal>$</literal>) characters.  And as we predicted, the
+      <literal>Rev</literal> keyword was not substituted because
+      we didn't ask for it to be.</para>
+
+    <para>Note also that we set the <literal>svn:keywords</literal>
+      property to <literal>Date Author</literal>, yet the keyword
+      anchor used the alias <literal>$LastChangedDate$</literal>
+      and still expanded correctly:</para>
+
+    <informalexample>
+      <programlisting>
+Here is the latest report from the front lines.
+$LastChangedDate: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $
+$Rev$
+Cumulus clouds are appearing more frequently as summer approaches.
+</programlisting>
+    </informalexample>
+
+    <para>If someone else now commits a change to
+      <filename>weather.txt</filename>, your copy of that file
+      will continue to display the same substituted keyword value
+      as before—until you update your working copy.  At that
+      time, the keywords in your <filename>weather.txt</filename>
+      file will be resubstituted with information that
+      reflects the most recent known commit to that file.</para>
+
      <para>All keywords are case-sensitive where they appear as
        anchors in files: you must use the correct capitalization
        for the keyword to be expanded.  You should consider the
        value of the <literal>svn:keywords</literal> property to be
-      case-sensitive, too—certain keyword names will be recognized
+      case-sensitive, too—for the sake of backward
+      compatibility, certain keyword names will be recognized
        regardless of case, but this behavior is deprecated.</para>

      <para>Subversion defines the list of keywords available for
@@ -3098,91 +3184,6 @@
        versioned files are being changed regularly in the
        repository.</para>

-    <para>Simply adding keyword anchor text to your file does nothing
-      special.  Subversion will never attempt to perform textual
-      substitutions on your file contents unless explicitly asked to
-      do so.  After all, you might be writing a
-      document<footnote><para>… or maybe even a section of a
-      book …</para></footnote> about how to use keywords, and
-      you don't want Subversion to substitute your beautiful examples
-      of unsubstituted keyword anchors!</para>
-
-    <para>To tell Subversion whether to substitute keywords
-      on a particular file, we again turn to the property-related
-      subcommands.  The <literal>svn:keywords</literal> property,
-      when set on a versioned file, controls which keywords will
-      be substituted on that file.  The value is a space-delimited
-      list of keyword names or aliases.</para>
-
-    <para>For example, say you have a versioned file named
-      <filename>weather.txt</filename> that looks like
-      this:</para>
-
-    <informalexample>
-      <programlisting>
-Here is the latest report from the front lines.
-$LastChangedDate$
-$Rev$
-Cumulus clouds are appearing more frequently as summer approaches.
-</programlisting>
-    </informalexample>
-
-    <para>With no <literal>svn:keywords</literal> property set on
-      that file, Subversion will do nothing special.  Now, let's
-      enable substitution of the
-      <literal>LastChangedDate</literal> keyword.</para>
-
-    <informalexample>
-      <screen>
-$ svn propset svn:keywords "Date Author" weather.txt
-property 'svn:keywords' set on 'weather.txt'
-$
-</screen>
-    </informalexample>
-
-    <para>Now you have made a local property modification on the
-      <filename>weather.txt</filename> file.  You will see no
-      changes to the file's contents (unless you made some of your
-      own prior to setting the property).  Notice that the file
-      contained a keyword anchor for the <literal>Rev</literal>
-      keyword, yet we did not include that keyword in the property
-      value we set.  Subversion will happily ignore requests to
-      substitute keywords that are not present in the file and
-      will not substitute keywords that are not present in the
-      <literal>svn:keywords</literal> property value.</para>
-
-    <para>Immediately after you commit this property change,
-      Subversion will update your working file with the new
-      substitute text.  Instead of seeing your keyword anchor
-      <literal>$LastChangedDate$</literal>, you'll see its
-      substituted result.  That result also contains the name of
-      the keyword and continues to be delimited by the dollar sign
-      (<literal>$</literal>) characters.  And as we predicted, the
-      <literal>Rev</literal> keyword was not substituted because
-      we didn't ask for it to be.</para>
-
-    <para>Note also that we set the <literal>svn:keywords</literal>
-      property to <literal>Date Author</literal>, yet the keyword
-      anchor used the alias <literal>$LastChangedDate$</literal>
-      and still expanded correctly:</para>
-
-    <informalexample>
-      <programlisting>
-Here is the latest report from the front lines.
-$LastChangedDate: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $
-$Rev$
-Cumulus clouds are appearing more frequently as summer approaches.
-</programlisting>
-    </informalexample>
-
-    <para>If someone else now commits a change to
-      <filename>weather.txt</filename>, your copy of that file
-      will continue to display the same substituted keyword value
-      as before—until you update your working copy.  At that
-      time, the keywords in your <filename>weather.txt</filename>
-      file will be resubstituted with information that
-      reflects the most recent known commit to that file.</para>
-
      <sidebar>
        <title>Where's $GlobalRev$?</title>

@@ -3210,6 +3211,138 @@

      </sidebar>

+    <para>In addition to previous set of stock keyword definitions and
+      aliases, Subversion 1.8 allows you the freedom to define and use
+      custom keywords.  To define a custom keyword, add a token to the
+      value of the <literal>svn:keywords</literal> property which is
+      of the form
+       
<userinput><replaceable>MyKeyword</replaceable>=<replaceable>FORMAT</replaceable></userinput>,
+      where <replaceable>MyKeyword</replaceable> is the keyword name
+      (which you'll use in the keyword anchor)
+      and <replaceable>FORMAT</replaceable> is a format string into
+      which information will be substituted when your keyword is
+      expanded inside your file.</para>
+
+    <para>The format string syntax used for custom keywords supports
+      the following format codes:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><literal>%a</literal></term>
+        <listitem>
+          <para>The author of the revision given
+            by <literal>%r</literal>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%b</literal></term>
+        <listitem>
+          <para>The basename of the URL of the file.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%d</literal></term>
+        <listitem>
+          <para>Short format of the date of the revision given by
+            <literal>%r</literal>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%D</literal></term>
+        <listitem>
+          <para>Long format of the date of the revision given by
+            <literal>%r</literal>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%P</literal></term>
+        <listitem>
+          <para>The file's path, relative to the repository
+            root.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%r</literal></term>
+        <listitem>
+          <para>The last known revision in which this file changed in
+          the repository.  (This is the same revision which would be
+          substituted for the <literal>Revision</literal>
+          keyword.)</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%R</literal></term>
+        <listitem>
+          <para>The URL to the root of the repository.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%u</literal></term>
+        <listitem>
+          <para>The URL of the file.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%_</literal></term>
+        <listitem>
+          <para>A space character. (Keyword definitions cannot contain
+            a literal space character.)</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%%</literal></term>
+        <listitem>
+          <para>A literal percent sign ('<literal>%</literal>').</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%H</literal></term>
+        <listitem>
+          <para>Equivalent to <literal>%P%_%r%_%d%_%a</literal>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><literal>%I</literal></term>
+        <listitem>
+          <para>Equivalent to <literal>%b%_%r%_%d%_%a</literal>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>As you can see, many of the individual format codes serve as
+      placeholders for the same information available through the
+      stock keywords.  But of course, the custom keyword format allows
+      you to more flexibly string together multiple bits of
+      information.  For example, you might wish to have a single
+      keyword in your files which reports the repository relative path
+      of the file and last-changed revision, formatted in a pleasant,
+      human-readable way.  To do so, you'd first define your custom
+      keyword:</para>
+
+    <informalexample>
+      <screen>
+$ svn pset svn:keywords "PathRev=%P,%_r%r" calc/button.c
+property 'svn:keywords' set on 'button.c'
+$
+</screen>
+    </informalexample>
+
+    <para>Next, you'd edit the file's contents to add the keyword
+      anchor for your custom keyword, which in this case
+      is <literal>$PathRev$</literal>.  After committing these
+      changes, an examination of your file's contents will show that
+      your custom keyword was substituted as you would
+      expect—where previously the file
+      contained <literal>$PathRev$</literal>, it now reads
+      <literal>$PathRev: trunk/calc/button.c, r23 $</literal>.</para>
+
+    <note>
+      <para>Subversion will automatically truncate any keyword
+        expansions which exceed 255 bytes in length.  Also custom
+        keywords defined with names that exceed 255 bytes will be
+        ignored altogether.</para>
+    </note>
+
      <para>You can also instruct 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




More information about the svnbook-dev mailing list