From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mon, 20 Jul 2015 19:14:41 GMT
Subject: Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation
Message-ID: <CAPig+cQ2nTt60iw0Td_MTP7xftt2+OQAx63pOZ4XzH0qeOhDsA@mail.gmail.com>
In-Reply-To: <CAPig+cQ_G=Ar0uxbxDaO6oEZwkRi7FM4qEQexDohDGxN10OJUA@mail.gmail.com>

On Mon, Jul 20, 2015 at 2:50 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> 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>
>> ---
>> +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.

If you really want to give an example of how to use --cc-cmd
(--to-cmd) with a plain text file holding email addresses, maybe
something like this instead:

Create an EXAMPLES section.

Make the bare-bones, static address list script the first example:

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

Then add an example showing how to take the fixed address list from a
plain text file. Have the user create the following script (let's call
it "anticat") which cat's all of its input arguments except the final
one, which is the patch itself:

    #!/bin/sh
    while test $# -gt 1
    do
        cat $1
        shift
    done

And, to use: --to-cccmd='anticat myaddresses.txt'