libssh2_sftp_write.3: added blurb about the "write ahead"

Documented the new SFTP write concept

docs/libssh2_sftp_write.3

@@ -27,6 +27,28 @@ possible to write all bytes as requested.
 put it into a single SFTP protocol packet. This means that to get maximum
 performance when sending larger files, you should try to always pass in at
 least 32K of data to this function.
+
+.SH WRITE AHEAD
+Starting in libssh2 version 1.2.8, the default behavior of libssh2 is to
+create several smaller outgoing packets for all data you pass to this function
+and it will return a positive number as soon as the first packet is
+acknowledged from the server.
+
+This has the effect that sometimes more data has been sent off but isn't acked
+yet when this function returns, and when this function is subsequently called
+again to write more data, libssh2 will immediately figure out that the data is
+already received remotely.
+
+In most normal situation this should not cause any problems, but it should be
+noted that if you've once called libssh2_sftp_write() with data and it returns
+short, you MUST still assume that the rest of the data might've been cached so
+you need to make sure you don't alter that data and think that the version you
+have in your next function invoke will be detected or used.
+
+The reason for this funny behavior is that SFTP can only send 32K data in each
+packet and it gets all packets acked individually. This means we cannot use a
+simple serial approach if we want to reach high performance even on high
+latency connections. And we want that.
 .SH RETURN VALUE
 Actual number of bytes written or negative on failure.