[svnbook] r3904 committed - Finish issue #100 ("Missing documentation about arguments passed to...

[svnbook at googlecode.com]

Revision: 3904
Author:   cmpilato at gmail.com
Date:     Fri Jul  8 13:43:10 2011
Log:      Finish issue #100 ("Missing documentation about arguments passed  
to
'pre-lock' hook"), updating the documentation for all hook scripts
while here.

* src/en/book/ch09-reference.xml
   (svn.ref.reposhooks.pre-commit): Note the lock-token stdin input to
     the pre-commit hook script.
   (svn.ref.reposhooks.pre-lock): Update to cover the COMMENT and
     STEAL-LOCK inputs, and to describe the lock token dictation (via
     stdout) feature.
   (svn.ref.reposhooks.pre-unlock): Document the LOCK-TOKEN and
     BREAK-UNLOCK parameters.

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

Modified:
  /trunk/src/en/book/ch09-reference.xml

=======================================
--- /trunk/src/en/book/ch09-reference.xml	Fri Jul  8 10:27:34 2011
+++ /trunk/src/en/book/ch09-reference.xml	Fri Jul  8 13:43:10 2011
@@ -10047,6 +10047,18 @@
              <para>Commit transaction name</para>
            </listitem>
          </orderedlist>
+
+        <para>Additionally, Subversion passes any lock tokens provided
+          by the committing client to the hook script via standard
+          input.  When present, these are formatted as a single line
+          containing the string <literal>LOCK-TOKENS:</literal>,
+          followed by additional lines—one per lock
+          token—which contain the lock token information.  Each
+          lock token information line consists of the URI-escaped
+          repository filesystem path associated with the lock,
+          followed by the pipe (<literal>|</literal>) separator
+          character, and finally the lock token string.</para>
+
        </refsect1>

        <refsect1>
@@ -10286,8 +10298,24 @@

          <para>If the <literal>pre-lock</literal> hook program returns
            a nonzero exit value, the lock action is aborted and
-          anything printed to <filename>stderr</filename> is marshalled  
back to the
-          client.</para>
+          anything printed to <filename>stderr</filename> is
+          marshalled back to the client.</para>
+
+        <para>The hook program may optionally dictate the lock token
+          which will be assigned to the lock by printing the desired
+          lock token to standard output.  Because of this,
+          implementations of this hook should carefully avoid
+          unexpected output sent to standard output.</para>
+
+        <warning>
+          <para>If the <literal>pre-lock</literal> script takes
+            advantage of lock token dictation feature, the
+            responsibility of generating a <emphasis>unique</emphasis>
+            lock token falls to the script itself.  Failure to
+            generate unique lock tokens may result in
+            undefined—and very likely,
+            undesired—behavior.</para>
+        </warning>

        </refsect1>

@@ -10308,6 +10336,14 @@
              <para>Authenticated username of the person attempting the
                lock</para>
            </listitem>
+          <listitem>
+            <para>Comment provided when the lock was created</para>
+          </listitem>
+          <listitem>
+            <para><literal>1</literal> if the user is attempting to
+              steal an existing lock; <literal>0</literal>
+              otherwise</para>
+          </listitem>
          </orderedlist>
        </refsect1>

@@ -10426,6 +10462,14 @@
              <para>Authenticated username of the person attempting the
                unlock</para>
            </listitem>
+          <listitem>
+            <para>Lock token associated with the lock which is to be
+              removed</para>
+          </listitem>
+          <listitem>
+            <para><literal>1</literal> if the user is attempting to
+              break the lock; <literal>0</literal> otherwise</para>
+          </listitem>
          </orderedlist>
        </refsect1>