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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 14, 2023, 01:17 UTC
Message-ID: <xmqqmt6loqxi.fsf@gitster.g>
In-Reply-To: <20230110211452.2568535-3-michael.strawbridge@amd.com>

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

Show 6 quoted lines

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