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

[Junio C Hamano <gitster@pobox.com>]

Philip Oakley <philipoakley@iee.org> writes:

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

That's not even a valid command line (cc-cmd cannot be a shell
variable name), so why bother writing it that way?  Rather

    The program that is specified by `cc-cmd` is invoked by `git
    send-email` with the name of the patch file as an argument;
    the program can read from it and customize its output based on
    what the patch file contains.
    
or something like that, perhaps.

> +
> +A simple solution for a basic address list is to create a 'cc-cmd' file
> +(executable) which provides a list of addressees:

There is no "problem" stated here that requires your "solution".  In
fact, what problem are you solving?

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

That is one simple and denegerate use case; if the program does not
need any information from the patch file, it surely has an option
not to look at it.  But it is not an interesting usage.

If you want to add a single example to illustrate how cc-cmd (or
to-cmd, or anything that goes thru recipients_cmd()), you should
have an example that reads the input and then adds a few hardcoded
one.

	#!/bin/sh
	# always send it to the logger service
        echo "patchlog@example.com"
	# tell the bug tracker as necessary
	if fixes=$(sed -ne 's/^Fixes bug#\([0-9]*\)/\1/p' "$1")
        then
		echo "bugs+$fixes@example.com"
	fi

or something silly like that.

And this ...

> +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 the rest of the patch is unnecessary noise to a reader who
read that the single argument to the program is the name of the
patchfile, I think.  You were trying to avoid the same confusion
caused by the sketchy documentaiton, and you already "solved" that
problem by telling the reader what the command takes as its input.

> +    --cc-cmd='cat cc-cmd #'

This heavily depends on the current implementation that happens to
pass the command line string to a shell.