Junio C Hamano <gitster@xxxxxxxxx> writes:
>> 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;;
>> +* 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html