Update main document examples to latest interop code + add more examples

[EskoDijk]

• surrounding text also updated and clarified
• more examples added (based on interop code)
• formatting fixes related to examples and surrounding text.
• editorial updates where needed

[EskoDijk]

Appendix C examples will be covered in a separate PR.

[EskoDijk]

Closes #237