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

[Eric Sunshine <sunshine@sunshineco.com>]

On Mon, Jul 20, 2015 at 2:26 PM, Philip Oakley <philipoakley@iee.org> wrote:
> 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>
> ---
> 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:

Rather than calling this a "simple solution", you might instead say
that this is an example of a bare-bones script which just returns a
fixed list of email addresses without attempting to extract any
addresses from the patch file itself.

> +       #!/bin/sh
> +       echo <<\EOF
> +       person1@example.com
> +       person2@example.com
> +       EOF

I don't know if it deserves mention that the script must be executable
(chmod +x) or should we assume that readers are smart enough to
understand this implicitly? (It probably should be mentioned.)

Other than those minor points, the above looks fine, however...

> +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.

This entire above text about "cat $addressfile" seems awfully
inappropriate for a manual page, especially the bit about the terrible
"cat $file #" hack.

>  SEE ALSO
>  --------
>  linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
> --
> 2.4.2.windows.1.5.gd32afb6
>