On 29/04/2013, at 4:18 PM, Chris Smith wrote:
My point was not anything at all to do with programming. It was about writing comments, which is fundamentally a communication activity. That makes a difference. It's important to keep in mind that the worst possible consequence of getting corner cases wrong here is likely that some documentation will be confusing because the numbering is messed up in an ordered list.
The problem is not what it does to the formatting. The problem is what it does to *PEOPLE*. It wastes their time. Suppose there are 10,000 Haskell programmers (I have no idea what the true number of Haskell programmers who like to document is; I hope it's more) and they lose just 6 minutes a day working around glitches in their documentation tools. That's 1000 hours a day; call it 40 days of human life blown away in aggravation every day. To quote Jayne, "Where does that get to be fun?" Why is it acceptable to waste anyone's time with "confusing" documentation? Did anyone else read that Markdown-in-Haskell mentioned here recently whose author comments (quoting from memory) "any random string of garbage is legal Markdown", so that there is no possibility of catching errors early; by definition in that processor there are no errors.
Pointing out that different processors treat markdown differently with respect to bold or italics and such is ultimately missing the point.
It may be missing your point, but it hits mine square in the bulls-eye. It wasn't just that they were *different*, it was that the difference wasn't *documented*, and I had to waste an hour of my *LIFE* that I will never get back because some lazy swine couldn't be buggered doing documentation. About a documentation tool. Savour the irony!
That doesn't mean the choices should not be documented. Sure they should.
If we agree that the semantics should be documented, what are we arguing about?
But it seems ridiculous to sidetrack the proposal to do something nice by concerns about the minutiae of the syntax.
Nobody is suggesting that the proposal should be *CHANGED*. So talk about "sidetrack" is unwarranted. The pathetic request from a suffering humanity is that the mark(up/down/sideways) should be *DOCUMENTED* clearly. As for "minutiae of the syntax", *you* may call the fact that `` in the middle of a line and `` at the beginning of a line do different things "minutiae of the syntax", but *I* call it "wantonly squandering my few remaining hours because you think that no or confusing documentation is OK". The more I use Markdown, the better HTML looks. That is, the more effective HTML looks *AS A COMMUNICATION TOOL*, where effectiveness is measured in terms of the effort required to get the result you want. Other people may have other experiences, and that's wonderful. Having better documentation WILL NOT HURT THEM.