Re: [PATCH v5 1/1] send-email: Add sendmail email aliases format

[Allen Hubbe <allenbh@gmail.com>]

On Sat, May 23, 2015 at 2:00 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> 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.
>

I initially thought to put it last, too.  I'll move it back to the end.

I moved it to the beginning, because it seemed odd to me for only the
last thing in the list to have a further description.  If the intent
is that eventually (perhaps in an ideal world), the other formats will
have expanded documentation, too, then you are right that adding new
things to the end makes the most sense.

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

Alright.

Thanks for showing me '--'.  I had some trouble with asciidoc, where
my intention was to insert a bulleted list between two paragraphs in a
containing definition-list item.  The paragraph that I intended to be
after the bulleted list was instead nested in the last bulleted item
in the list.

The documentation for asciidoc soesn't seem to be very helpful in
describing this construct.  There is one example, that I could find,
and I didn't find a description of the syntax for it.  Perhaps I
missed it among all the other uses of a series of '-'.  I don't see
any way for this to distinguish between different levels of nesting,
like a block of --/-- in another block of --/--; that might be
syntactically indistinguishable from a block of --/-- followed by
another block of --/--.

>
> That way, limitations and deviations of other formats can be added
> later in a consistent way.
>
> Just a thought.