Syntactically invalid examples push learning curve higher than necessary

[filip26]

Examples should be treated in a better way, many of them are syntactically malformed, many of the others have wrong contexts or different, usually minor like comments, issues preventing from just grabbing an example as is and playing. 

I understand that to some examples are just illustrative, unimportant stuff.
To adopters, having examples in a form that is useful is invaluable and might dramatically boost progress with adopting a spec. 

Don't we have test vectors? Yes, but it's a different case, different phase of adoption - need for a compact test case, which is in contrast to examples, to grab and play. 

I'm happy to contribute to that.

(I know, unfortunately this is not the only W3C spec suffering it)

[msporny]

There are a few things we can do in this spec that we've done in others:

1. We mark comments and ... annotations as "ignore on copy" using some CSS tricks.
2. We try to make the first few examples syntactically valid.

We just need to do a full pass on the document and try to get it into proper shape, we haven't done that pass yet, but we should.

I'm waiting on PR #116 to land before doing a full pass.

[msporny]

PR #143 has been raised to address this issue. This issue will be closed once PR #143 has been merged.

[msporny]

PR #143 has been merged, closing.