Re: [PATCH v5 2/2] send-email: expose header information to git-send-email's sendemail-validate hook

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

"Strawbridge, Michael" <Michael.Strawbridge@amd.com> writes:

> +It takes these command line arguments:
> +1. the name of the file that holds the e-mail to be sent.
> +2. the name of the file that holds the SMTP headers to be used.
> +
> +The hook doesn't need to support multiple header names (for example only Cc
> +is passed).

I think you meant, by "multiple header names", "header names spelled
in different cases".

That may be a correct statement, but is more or less a useless one
that does not help hook writers.  Different people spell these
headers in different capitalization (for example, your message came
with "CC:" to various people, not "Cc:"), so the hook MUST know
which case the feature adds to its input, if it chooses not to
support different cases like "Cc:", "cc:", and "CC:".  IOW, "only Cc
is passed" is not something they need to hear as a mear example.
They need to be told what headers are given to them and in what
capitalization for all headers in the input to them.

> However, it does need to understand that lines beginning with
> +whitespace belong to the previous header.  The header information follows
> +the same format as the confirmation given at the end of send-email.

I suspect that many people (including me) disable the confirmation
and to them, the above description would not help.

In general, documentation should not depend on the reader having an
access to an environment where they can readily run commands and see
their output.

Thanks.