[PATCH 3/3] doc: give examples for send-email cc-cmd operation

[Philip Oakley <philipoakley@iee.org>]

Explain how the cc-cmd (and to-cmd) is invoked, along with two
simple examples (and a how-not-to example) to help in getting started.

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
http://article.gmane.org/gmane.comp.version-control.git/274302
---
 Documentation/git-send-email.txt | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index ddc8a11..9f991cf 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -436,6 +436,42 @@ following commands:
 Note: the following perl modules are required
       Net::SMTP::SSL, MIME::Base64 and Authen::SASL
 
+Creating a cc-cmd (and to-cmd) action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+git-send-email invokes the cc-cmd like this:
+
+	$cc-cmd $patchfilename
+
+Thus the patch itself can be processed to locate appropriate email address
+information if required.
+
+A simple solution for a basic address list is to create a 'cc-cmd' file
+(executable) which provides a list of addressees:
+
+	#!/bin/sh
+	echo <<\EOF
+	person1@example.com
+	person2@example.com
+	EOF
+
+Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text file
+of email addresses), does not work as expected as the invocation becomes:
+
+	$cat cc-cmd $patchfilename
+
+and since 'cat' copies the concatenation of its input files to its output,
+this adds the patch file to the address list resulting in an error
+"unable to extract a valid address from:".
+
+The quick-and-dirty work-around is to use '#' to effectively comment out
+the patch file name:
+
+    --cc-cmd='cat cc-cmd #'
+
+which works, but is very, very ugly.
+
+
 SEE ALSO
 --------
 linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
-- 
2.4.2.windows.1.5.gd32afb6