[svnbook] r4412 committed - For issue 178 ("document ephemeral txnprops (new in 1.8) and how hook...

[svnbook at googlecode.com]

Revision: 4412
Author:   cmpilato at gmail.com
Date:     Thu Feb  7 12:01:11 2013
Log:      For issue 178 ("document ephemeral txnprops (new in 1.8) and how  
hook
scripts might use them."), document the ephemeral transaction
properties in the property reference section.  We still need to give
examples of their utility.

* en/book/ch03-advanced-topics.xml
   (svn.advanced.props.ref.ephemeral): New section.
http://code.google.com/p/svnbook/source/detail?r=4412

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

=======================================
--- /trunk/en/book/ch03-advanced-topics.xml	Wed Feb  6 09:33:02 2013
+++ /trunk/en/book/ch03-advanced-topics.xml	Thu Feb  7 12:01:11 2013
@@ -2138,6 +2138,58 @@
              </listitem>
            </varlistentry>

+        </variablelist>
+      </sect3>
+
+      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
-->
+      <sect3 id="svn.advanced.props.ref.ephemeral">
+        <title>Ephemeral transaction properties</title>
+
+        <para>Subversion reserves a set of <firstterm>ephemeral
+          transaction properties</firstterm> for its own use.  These
+          are essentially commit transaction properties which are set
+          by the client at the earliest opportunity during the commit
+          process, but which are then automatically removed by the
+          server prior to the promotion of the transaction into a new
+          revision.  You can inspect these properties using the same
+          tools with which you'd inspect other unversioned properties
+          set on commit transactions during the timeframe between
+          which the start-commit and pre-commit repository hook
+          scripts would operate.  See
+          <xref linkend="svn.reposadmin.create.hooks" /> for more
+          about repository hook scripts.</para>
+
+        <note>
+          <para>Ephemeral transaction property support was a feature
+            introduced in Subversion 1.8.  Server and clients older
+            than that will not set or transmit these
+            properties.</para>
+        </note>
+
+        <variablelist>
+
+          <varlistentry>
+            <term><literal>svn:txn-client-compat-version</literal></term>
+            <listitem>
+              <para>Carries the Subversion library version string with
+                which the committing client claims compatibility.
+                This is useful for deciding whether the client
+                supports the minimal feature set required for proper
+                handling of the repository data.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>svn:txn-user-agent</literal></term>
+            <listitem>
+              <para>Carries the <quote>user agent</quote> string which
+                describes the committing client program.  Subversion's
+                libraries define the initial portion of this string,
+                but third-party consumers of the API (GUI clients,
+                etc.) can append custom information to it.</para>
+            </listitem>
+          </varlistentry>
+
          </variablelist>
        </sect3>
      </sect2>