Re: [PATCH v5 1/1] send-email: Add sendmail email aliases format
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 23, 2015, 18:00 UTC
- Message-ID
- <xmqq7frzcgx2.fsf@gitster.dls.corp.google.com>
- In-Reply-To
- <xmqqfv6nchmf.fsf@gitster.dls.corp.google.com>
Junio C Hamano <gitster@pobox.com> writes:
Show 10 quoted lines
>> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt >> index 804554609def..97387fd27a8d 100644 >> --- a/Documentation/git-send-email.txt >> +++ b/Documentation/git-send-email.txt >> @@ -383,7 +383,42 @@ sendemail.aliasesFile:: >> >> sendemail.aliasFileType:: >> Format of the file(s) specified in sendemail.aliasesFile. Must be >> - one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'. >> + one of 'sendmail', 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'.
We prefer to append to an existing list of equals, not prepend.
>> ++ >> +If the format is 'sendmail', then the alias file format is described below. >> +Descriptions of the other file formats can be found by searching the >> +documentation of the email program of the same name.
The phrasing feels somewhat awkward. How about dropping the first line, pretending as if 'sendmail' is also fully 'sendmail' format, and then describe the limitations (like you already did below)? I have a feeling that other formats have similar limitations (e.g. I do not think piping to commands in any other formats would be supported by send-email), and other people can follow suit and describe the limitations.
That is, drop the paragraph that describes the basics (which can be learned by searching the documentation of the email program of the same name), and dive right into the differences.
IOW,
What an alias file in each format looks like can be found in
the documentation of the email program of the same name. The
differences and limitations from the standard formats are
described below:
+
--
sendmail;;Show 7 quoted lines
>> +* Quoted aliases and quoted addresses are not supported: lines that >> + contain a `"` symbol are ignored. >> +* Line continuations are not supported: any lines that start with >> + whitespace, or end with a `\` symbol are ignored. >> +* Warnings are printed on the standard error output for any explicitly >> + unsupported constructs, and any other lines that are not recognized >> + by the parser.
--
That way, limitations and deviations of other formats can be added later in a consistent way.
Just a thought.