I think it's worth backing up here, and remembering the original point of the proposal, by thinking about what is and isn't a goal. I think I'd classify things like this: Goals: - Use a lightweight, common, and familiar core syntax for simple formatting. - Still allow haddock-specific stuff like links to other symbols. Non-Goals: - Compliance/compatibility with any specification or other system. - Have any kind of formal semantics. The essence of this proposal is about making Haddock come closer to matching all the other places where people type formatted text on the Internet. As Johan said, markdown has won. But markdown won because it ended up being a collection of general conventions with compatibility for the 95% of commonly used bits... NOT a formal specification. If there are bits of markdown that are just really, really awkward to use in Haddock, modify them or leave them out. I think the whole discussion is getting off on the wrong start by looking for the right specification against which this should be judged, when it's really just about building the most natural possible ad-hoc adaptation of markdown to documentation comments. Just doing the easy stuff, like switching from /foo/ to *foo* for emphasis, really is most of the goal. Anything beyond that is even better. Compatibility or compliance to a specification are non-issues: no one is going to be frequently copying documentation comments to and from other markdown sources. Haddock will unavoidably have its own extensions for references to other definitions anyway, as will the other system, so it won't be compatible. Let's just accept that. Formal semantics is a non-issue: the behavior will still be defined by the implementation, in that people will write their documentation, and if it looks wrong, they will fix it. We don't want to reason formally about the formatting of our comments, or prove that it's correct. Avoiding unpleasant surprises is good; but avoiding *all* possible ambiguous corner cases in parsing, even when they are less likely than typos, is not particularly important. If some ambiguity becomes a big problem, it will get fixed later as a bug. I think the most important thing here is to not get caught up in debates about advanced syntax or parsing ambiguities, or let that stop us from being able to emphasize words the same way we do in the whole rest of the internet. -- Chris Smith