[svnbook] r4351 committed - Finish issue 5 ("Document svnmucc")....

[svnbook at googlecode.com]

Revision: 4351
Author:   cmpilato at gmail.com
Date:     Mon Jan 21 21:42:37 2013
Log:      Finish issue 5 ("Document svnmucc").

* en/book/ch09-reference.xml
   (svn.ref.svnmucc.re.examples): Flesh out this section.

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

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

=======================================
--- /trunk/en/book/ch09-reference.xml	Mon Jan 21 11:30:40 2013
+++ /trunk/en/book/ch09-reference.xml	Mon Jan 21 21:42:37 2013
@@ -11285,8 +11285,9 @@
                  baseline revision for all changes made via
                  the <command>svnmucc</command> actions.  This is an
                  important option which users should habituate to using
-                correctly in order to avoid inadvertently undoing
-                contemporary changes made by fellow team members.</para>
+                whenever modifying existing versioned items to avoid
+                inadvertently undoing contemporary changes made by
+                fellow team members.</para>
              </listitem>
            </varlistentry>

@@ -11352,7 +11353,117 @@
        <refsect1 id="svn.ref.svnmucc.re.examples">
          <title>Examples</title>

-        <para>### TODO ###</para>
+        <para>To (safely) modify a file's contents without using a
+          working copy, use <command>svn cat</command> to fetch the
+          current contents of the file, and <command>svnmucc
+          put</command> to commit the edited contents thereof.</para>
+
+        <informalexample>
+          <screen>
+$ # Calculate some convenience variables.
+$ export FILEURL=http://svn.example.com/projects/sandbox/README
+$ export BASEREV=`svn info ${FILEURL} | \
+                  grep '^Last Changed Rev' | cut -d ' ' -f 2`
+$ # Get a copy of the file's current contents.
+$ svn cat ${FILEURL}@${BASEREV} > /tmp/README.tmpfile
+$ # Edit the (copied) file.
+$ vi /tmp/README.tmpfile
+$ # Commit the new content for our file.
+$ svnmucc -r ${BASEREV} put README.tmpfile ${FILEURL} \
+          -m "Tweak the README file."
+r24 committed by harry at 2013-01-21T16:21:23.100133Z
+# Cleanup after ourselves.
+$ rm /tmp/README.tmpfile
+</screen>
+        </informalexample>
+
+        <para>Apply a similar approach to change a file or directory
+          property.  Simply use <command>svnmucc propget</command>
+          and <command>svnmucc propsetf</command> instead
+          of <command>svn cat</command> and <command>svnmucc
+          put</command>, respectively.</para>
+
+        <informalexample>
+          <screen>
+$ # Calculate some convenience variables.
+$ export PROJURL=http://svn.example.com/projects/sandbox
+$ export BASEREV=`svn info ${PROJURL} | \
+                  grep '^Last Changed Rev' | cut -d ' ' -f 2`
+$ # Get a copy of the directory's "license" property value.
+$ svnmucc -r ${BASEREV} propget license ${PROJURL} > /tmp/prop.tmpfile
+$ # Tweak the property.
+$ vi /tmp/prop.tmpfile
+$ # Commit the new property value.
+$ svnmucc -r ${BASEREV} propsetf prop.tmpfile ${PROJURL} \
+          -m "Tweak the project directory 'license' property."
+r25 committed by harry at 2013-01-21T16:24:11.375936Z
+# Cleanup after ourselves.
+$ rm /tmp/prop.tmpfile
+</screen>
+        </informalexample>
+
+        <para>Let's look now at some multi-operation examples.</para>
+
+        <para>To implement a <quote>moving tag</quote>, where a single
+          tag name is recycled to point to different snapshots (for
+          example, the current latest stable version) of a codebase,
+          use <command>svnmucc rm</command> and <command>svnmucc
+          cp</command>:</para>
+
+        <informalexample>
+          <screen>
+$ svnmucc -U http://svn.example.com/projects/doohickey \
+          rm tags/latest-stable \
+          cp HEAD trunk tags/latest-stable \
+          -m "Slide the 'latest-stable' tag forward."
+r134 committed by harry at 2013-01-12T11:02:16.142536Z
+$
+</screen>
+        </informalexample>
+
+        <para>In the previous example, we slyly introduced the use of
+          the <option>--root-url (-U)</option> option.  Use this
+          option to specify a base URL to which all other operand URLs
+          are treated as relative (and save yourself some
+          typing).</para>
+
+        <para>The following shows an example of using
+          <command>svnmucc</command> to, in a single revision, create
+          a new tag of your project which includes a newly created
+          descriptive file and which lacks a directory which shouldn't
+          be included in, say, a release tarball.</para>
+
+        <informalexample>
+          <screen>
+$ echo "This is the 1.2.0 release." | \
+       svnmucc -U http://svn.example.com/projects/doohickey \
+               -m "Tag the 1.2.0 release." \
+               -- \
+               cp HEAD trunk tags/1.2.0 \
+               rm tags/1.2.0/developer-notes \
+               put - tags/1.2.0/README.tag
+r164 committed by cmpilato at 2013-01-22T05:26:15.563327Z
+$ svn log -c 164 http://svn.example.com/projects/doohickey
+------------------------------------------------------------------------
+r164 | cmpilato | 2013-01-22 00:26:15 -0500 (Tue, 22 Jan 2013) | 1 line
+Changed paths:
+   A /tags/1.2.0 (from /trunk:163)
+   A /tags/1.2.0/README.tag
+   D /tags/1.2.0/developer-notes
+
+Tag the 1.2.0 release.
+$
+</screen>
+        </informalexample>
+
+        <para>The previous example demonstrates not only how to do
+          several different things in a single <command>svnmucc</command>
+          invocation, but also the use of standard input as the source
+          of new file contents.  Note the presence of <literal>--</literal>
+          to indicate that no more options follow on the command line.
+          This is required so that the bare <literal>-</literal> used
+          in the <command>svnmucc put</command> action won't be
+          flagged as a malformed option indicator.</para>

        </refsect1>