Some poor quality Unix mail transfer agents replace LF by CRLF automatically (which leads to doubling CR if CRLF is used). This should be a last resort, as it does not comply with » RFC 2822.

PHP does not change SMTP behaviour, it complies with it. See section 2.1 of 
RFC2822 which states:

"Messages are divided into lines of characters.  A line is a series of
characters that is delimited with the two characters, carriage-return
and line-feed; that is, the carriage return (CR) character (ASCII
value 13) followed immediately by the line feed (LF) character (ASCII
value 10)."

The CRLF combination in the examples tells the mail agent that those lines are 
ended. It is quite legitimate to have LF characters within a line before its 
end, example one does this with the $message variable.

Mail should *never* use PHP_EOL as it would break the SMTP standard.

Correct, ASCII text transmitted across the network *must* use the two-character sequence:  CR LF. 

But PHP behaves differently, on windows it talks directly to the mail server using SMTP protocol. In this case it should comply with the RCF as the message travels the network.
Even more, on windows, PHP code ( in /win32/sendmail.c ) tries  to distinguish various system specific EOL cases and behaves accordingly to comply with the RFC. 

On unix systems, the php mail function sends commands  to the sendmail binary ( or whatever you set as the  ‘sendmail_path’ in php.ini ). This is the same as typing commands on the prompt, it *MUST* escape new lines with LF. At the end, the message will be stored in the appropriate folder and the mail server will take care to process it correctly. Finally, the message will be sent out on the network. 

That’s why you should use PHP_EOL with the mail function as it is the only way to ensure headers will terminate properly on  different platforms. 

I think you should remove the second note on  poor quality unix smtp server ( as that is never the case ), and change all the examples in the documentation page to reflect the correct usage of line termination with the PHP_EOL constant ( by the way, it looks like it was introduced for the mail function ):

OK, so I did some digging into this, and ran this past Joey, who's spent more time dealing with MTAs than I've had hot dinners, and we both believe the note's substantively right as it is.

There's no out and out spec for this: sendmail itself (which is ultimately the de facto standard for the command line sendmail(8) interface) implies via its manpage, but doesn't state explicitly, that messages should be in RFC 822 format.[0] POSIX and SUS don't refer to sendmail(8) at all. The only specification I found that actually makes a statement either way is the Linux Standard Base (which is obviously non-normative for non-Linux systems), which states:

"The format of messages shall be as defined in RFC 2822:Internet Message Format." [1]

RFC 2822 states:

"Messages are divided into lines of characters.  A line is a series of characters that is delimited with the two characters carriage-return and line-feed; that is, the carriage return (CR) character (ASCII value 13) followed immediately by the line feed (LF) character (ASCII value 10). (The carriage-return/line-feed pair is usually written in this document as "CRLF".)" [2]

Given the above, I think it's reasonable to state that Unix MTAs should be able to deal with CRLF as their line separators, and in fact most do. Realistically, qmail is at fault here, and it's on Matthias Andree's list of qmail bugs.[3]

I have changed the wording of the note slightly, both to remove the "low quality" part (it's not the PHP Manual's place to judge that) and to explicitly mention that qmail is the best known MTA that behaves differently here, but the note itself should stand.

[0] http://manpages.ubuntu.com/manpages/precise/man8/sendmail.sendmail.8.html
    RFC 822 is noted in the See Also section. The Ubuntu manpage is identical
    to that shipped by sendmail itself, but easier to link to. :)

[1] http://refspecs.linux-foundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/baselib-sendmail-1.html

[2] http://www.ietf.org/rfc/rfc2822.txt (page 5, section 2.1)

[3] http://www.dt.e-technik.uni-dortmund.de/~ma/qmail-bugs.html (section 4.13)

I see that you already made extensive investigations, I would just like to add a few comments and point your attention to a very simple fact:

any mail server on *nix ( and bsd ), even the buggy qmail, will accept mail from stdin. Why wouldn't you reflect the same in the docs when php is talking directly to /usr/bin/sendmail wrapper?

That file has nothing to do with an smtp connection, it happens to be just a wrapper, a link pointing to sendmail itself, exim, postfix, qmail or any other sendmail alternative. 

That same wrapper is used by the standard *nix mail command which expects [LF] EOL. 

Mentioning sendmail and the RFC821, check the -bs and -ba options [0] ( php.ini defaults to sendmail_path = "/usr/sbin/sendmail -t -i" ). 

These flags control the behavior you were mentioning ( ARPANET and SMTP mode ), which implies that if you don't use them sendmail will expect the native [LF] EOL sequence for *nix systems.   [0]  

Sendmail.postfix is quite similar [1],  basically it’s the same for any sendmail alternative.

Postfix has the same problem? Check out this conversation on postix-users mailing list. Note the problem and what Witese ( postfix creator ) says about “local input” ( stdin ). To solve the problem he proposes a consistent  END-OF-LINE terminator across platforms (PHP_EOL constant ?! ).  [2] 

We must agree that postfix is a very popular smtp server. [3] 

Even removing the “poor quality” note, the documentation will reflect something that many unix sys admins know is wrong.
“If mail is not received… try \n” is not an explanation. If you really come to the strange conclusion that PHP_EOL is useless in this matter I propose something like this: 

On Unix-like operating systems the mail function uses standard input to transfer files to the smtp  server. This process involves the command line interpreter, as such it expects new lines separated by \n ( the native Unix platform new line sequence ).  

I still believe that PHP_EOL is the way to go. Windows will have no problems, nor *nix ;)

Cheers
Dario

References:

[0] http://manpages.ubuntu.com/manpages/precise/man8/sendmail.sendmail.8.html  
The description part mentions stdin.
Parameters –ba –bs show usage when stdin is not expected 

[1] http://manpages.ubuntu.com/manpages/precise/man1/rmail.1.html 
An example alternative linked to the sendmail wrapper. The description part mentions stdin.

[2] http://tech.groups.yahoo.com/group/postfix-users/message/244805
postfix-users mailing list, Wietse points out to the solution 

[3] http://www.securityspace.com/s_survey/data/man.201110/mxsurvey.html
Recent mx server survey

Thank you for changing that page, now it looks much better

Regards
Dario