From: Michael Witten <mfwitten@gmail.com>
Date: Mon, 20 Apr 2009 03:49:29 GMT
Subject: Re: [PATCH RFC3.5 06/12] send-email: Cleanup and streamline the SMTP code in send_message
Message-ID: <49ebf2f6.050cc00a.2e8d.ffffbde4@mx.google.com>
In-Reply-To: <7vzlecm4lg.fsf@gitster.siamese.dyndns.org>

On Sun, Apr 19, 2009 at 20:42, Junio C Hamano <gitster@pobox.com> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
> ...
>> Now, the 'host:port' server URI form is handled regardless of the
>> documentation deficiencies of Net::SMTP{,::SSL}.
>
> You said that in 01/12, too but I do not think there is any problem with
> Perl documentation.
>
> My installed copy of /usr/share/perl/5.10.0/Net/SMTP.pm has this:
>
>    B<Host> - SMTP host to connect to. It may be a single scalar, as defined for
>    the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
>    an array with hosts to try in turn. The L</host> method will return the value
>    which was used to connect to the host.
>
> and of course PeerAddr allows host:port.
>
> Please stop placing a false blame on others.  I think it is you who lack
> ability to read the documentation correctly in this particular case.

Take a look again at my commit message for 01/12:

	The 'host:port' form of argument for --smtp-server was only
	working for SSL connections, because the SSL connection code
	was relying on undocumented behavior of Net::SMTP::SSL (really,
	undocumented behavior of Net::SMTP's new method)...

Clearly my beef is with Net::SMTP--->::SSL<---

I touch upon this in the commit message for 06/12:

	The code could even be simplified further, because Net::SMTP{,::SSL}
	both take the PORT variable in their new methods (which, as of this
	commit, are actually the same method). Moreover, both take a server
	URI of the form 'host:port' that trumps any value passed to PORT.

	Unfortunately, none of this is documented publicly, so it isn't
	exploited out of purity.

Net::SMTP doesn't document the PORT key, even though it's the one that
implements the constructor for both Net::SMTP and Net::SMTP::SSL. Also,
Net::SMTP:SSL doesn't document whether PORT shadows the ':port' in any
'host:port' input.

So... I remain resolved in my stance: The documentation is poor and
"--smtp-server host:port" only worked because the code relies on the
undocumented behavior of the ':port' taking precedence of over any
PORT specification. 

> I think you just did not read the documentation carefully enough in this
> case.

Actually, I think I read it too carefully and thought about it too much.

On Sun, Apr 19, 2009 at 21:38, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Please stop placing a false blame on others.  I think it is you who lack
>> ability to read the documentation correctly in this particular case.
>
> Sorry, this came out stronger than I intended.

That's OK. I tend to sound harsher than I want as well.

> Your ability has never been an issue (otherwise there wouldn't have been
> this patch series).

I appreciate that remark; I'm admittedly not important, but I hope that
I'm at least useful.

Now let's get back to work!

Sincerely,
Michael Witten