[Haskell-cafe] Markdown extension for Haddock as a GSoC project

[Chris Smith]

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