I'm not sure why the examples are good (for example, modern client code should probably use create_connection() with a host name, not connect()).
I disagree. create_connection is an advanced function - you shouldn't be using it unless you know what it is doing.
Can you explain? I would certainly use it myself, and I don't understand how it's "advanced". It's simply higher-level.
It uses getaddrinfo, which might return multiple addresses, which are then tried in sequence. So even though it's called "create_connection", it may actually attempt to create multiple connections. As a consequence, it may wait some time for one connection to complete, and then succeed on a different address. These phenomena can only be understood when you know what it is actually doing.
Actually, we've been actually replacing uses of connect() with create_connection() in various parts of the stdlib, so that our client modules get IPv6-compatible.
And that's fine - the people making this changes most certainly where capable of using advanced API.
No no no no no. Absolutely not. a) telling people who want to learn sockets "don't learn sockets, learn some higher-level library" is besides the point. What do you tell them when they did that, and now come back to learn sockets?
You said yourself that the HOWTO doesn't claim to explain sockets
Did I say that? If so, I didn't mean to. It explains how to use the socket API. Regards, Martin