multistream-select specification isn't very clear

[dhuseby]

Reading the spec I noticed that the code blocks in the beginning show a pseudo-wire protocol representation by just showing the contents of each message without explicitly showing the varint message length and the newline suffix. For instance this example is like that:

multistream-select/README.md

Lines 45 to 48 in 77f0b44

	```
	> /multistream/1.0.0
	> /ipfs/kad/1.0.0
	```

Only later, in an easy-to-miss note do we point out the critical details that every message has a varint length and newline suffix:

multistream-select/README.md

Line 82 in 77f0b44

**Note 1:** Every multistream message is a "length-prefixed-message", which means that every message is preprended by a varint that describes the size of the message.

Farther down in the spec, the examples begin to show the varint length explicitly:

multistream-select/README.md

Lines 182 to 188 in 77f0b44

	```
	> <varint-ls-length>ls\n
	< <varint-ls-response-length><varint-protocol-length><protocol>\n
	< <varint-protocol-length><protocol>\n
	# ...more protocols
	< \n
	```

Suggestions for improvement:

1. Highlight the basic message wire format first and have an example showing the varint, message body, newline suffix.
2. Make all of the examples consistent in explicitly showing the varint lengths and newline suffixes. The way it is now is ambiguous. Does each protocol line constitute a message and thus has a varint length and newline suffix or is it only the overall message that does?
3. Add a little terminology/vocab note at the top explaining "initiator" and "responder" and explicitly stating that any message that starts with ">" is a message from the initiator to the responder and any message that starts with "<" is a message from the responder to the initiator.
4. Remove the newline suffixes. If you have varint length prefixes the newline suffixes are redundant framing.

[dhuseby]

I would make a PR right now to fix the problems but the spec, as it is, can be interpreted different ways and I don't want to dump raw messages to figure out the behavior in the wild. Once I confirm the actual wire protocol, I can submit a PR to clean this up.

[marten-seemann]

When using the TCP transport, the first multistream exchange happens in the clear, so it should be easy to inspect using Wireshark.