-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 28/04/13 11:57, Joe Nash wrote:

On 28 Apr 2013 11:33, "Mateusz Kowalczyk" wrote:

...

...

If the flexibility of having it pandoc compatible is a desired feature, can this not be achieved through implementing markdown for haddock as well? Depending on what haddock specific features were required to be added to the superset, it may require only minimal changes to an existing markdown reader/writer in pandoc already.

It can, but the restriction comment applies here as well.

Does it? If it is suitable to write in another markup and convert to haddock with pandoc, why is it more restrictive to write in another markup and convert to pandoc-markdown? Have I missed a point here?

Extending core Haddock allows us to: 1. Write in any of the Pandoc supported formats, including Markdown 2. Convert it to pure Haddock. This can then be converted back into a different format if need be. Extending Haddock with a Markdown extension allows us to: 1. Write the documentation in any of Pandoc supported formats (including our new Markdown) 2. Convert it from a Pandoc supported format to our Markdown extension as Haddock isn't expressive enough as is to be used. It's a question of being able to go from `Many formats <-> Pandoc <-> Many formats' and `Markdown extension <-> Pandoc <-> Many formats'.

I think these are starting to form two projects with tangential, but slightly differing goals. It would be interesting to see the results if we diverged here and a proposal was submitted for both ideas.

I think the goal is still the same: in the end, people will be able to use Markdown to document their code. The means of achieving the goal would give us a different final product that achieves the goal in a slightly different way. - -- Mateusz K. -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRfQWCAAoJEM1mucMq2pqXSDYQAJDgstjhoDNctcvbQ6OagkOe TVrJ6V7jmSKHYHsQQziGAeEOmXgZ18UX5TEu5w+ZJ//Yf3zCulhMzAjy+jOqGFPY nOJM5kZL6e7udf/rfmrD8r4GKb3yQAvufJIVLZ8UmMZ3vCAqbOiUs7cKOVcgsoD/ nVs11ySfYfLrF64RGcMqJ6Y9AZMcv05UOOSI3aM++0rj96/34TWRwC5XvQqG08Y+ 8eEB0FZijpKFRwMS8eSrTvCTx93pZkRJpMuHawT19zmylvqoME5WCBkeiXrGUuXE VpYAU5ZZxkW03l65yHb8Ir6IB4kTvD09NprhReR5MRf0J4lbL7TX5WZhP/3APFPk on8gPn4XGqVyn93Y9GplfCCOGr6A1271xEwqOF5YV7Y6NkI/c+SBcPGitgBBE1SO 03BIjr02S9wUtk+Su3szXZ0rmU5/zTLgCAcH2aG1MfbV7tDTKrL6m/J80wjzNULQ nhfHPvqEtT/iH6G2BmyLTSuNUgakDYzA10LPRIuxgoCBaZr9mGcJ6wye/xWx6tud RcuG1a8BS02Xau+zPFKgbdp1UQ8sRW2wiqPsbvwHVMoXvJ1j8ro+Xcxv0+vmar67 tWnYRHH4WgG209j1mX3ssj0gWcFUaFHrPYR9Gpv154NxdOEFq32w9eZO1pXndo8f zW9RmOLRpqh30fX3E2iX =0um2 -----END PGP SIGNATURE-----

On 29/04/2013, at 3:26 AM, Chris Smith wrote:

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.

Why I find the idea of rejecting semantics appalling: Last week I was working with a documentation tool for another language which claims to be "Markdown" and where *bold* only allows one or more alphabetic words **bold** allows any text _italic_ only allows one or more alphabetic words __italic__ allows any text Today I had to revise some documentation for yet a third language which also claims to be "Markdown" and where *word* and _word_ both gave italics **word* and __word__ both gave bold. Oh, and the markup wasn't documented, because it was just "Markdown", and everyone knows Markdown, right? The syntax I was using was legal syntax, but the semantics was not the semantics I expected and was not written down. I don't care how formal the syntax and semantics are, but I care very much how complete they are.

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.

Sorry, but this is rubbish. If the semantics is not documented, then people will write their documentation, and it will look wrong, AND THEY WILL NEVER HAVE BEEN GIVEN A CLUE ABOUT WHAT TO WRITE INSTEAD.

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.

Hmm. Just today, again, looking at the revision list for a Markdown processor, I see comments like "This changes the syntax from all previous versions... Code blocks and spans ... will now generate different output..." (which reminds me that the author may not be able to fix the looks of their documentation because it may have been perfectly fine when they wrote it, and they may be unavailable when the semantics changes) "Tweaked the rules ... this may affect existing content" (see above) Sort-of fixed a bug ... Given Markdown's list creation rules, I'm not sure this *can* be fixed." (which is the kind of thing that happens when you decide a clear syntax and semantics are not necessary).

If some ambiguity becomes a big problem, it will get fixed later as a bug.

As the comment extracted above suggests, it may not be fixable. We may not care about compatibility with other dialects of Markdown, but we should care about compatibility between versions of Haddock. Damn! Why did Watts Humphrey have to die before he'd convinced the world that the cheapest way to fix bugs is to keep them out in the first place?

On Mon, Apr 29, 2013 at 8:42 AM, Alexander Solla wrote:

I've been scoffed at during interviews for saying I solve problems on paper before I start typing!

That has to suck. I hope you're properly avenged when you find work in a savvier, respectful competitor and KICK THEIR ASSES! -- Kim-Ee

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.

I see the pluggable markup being pushed in this thread again. I just want to remind everybody that we currently have a flavor of a markup issue on github. The ghc source code uses literal haskell, and it does not work well on github. http://www.haskell.org/pipermail/ghc-devs/2013-April/001099.html Any markup that is not widely supported makes it harder for third parties to support and parse. The solution is *not* to reimplement github in haskell, but to standardize markup as much as possible. Pluggable markup makes the probability that a github-like service, IDEs and similar can make use of the documentation arbitrarily close to zero. Alexander On Mon, Apr 29, 2013 at 8:04 AM, Richard A. O'Keefe wrote:

I should add that as a consumer of Haddock documentation I can testify that fancier styling (in whatever format) would be of little benefit to _me_. What I need is more plain text and more examples.

To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation.

So I do agree that markup that doesn't get in the way of a _reader_ who is looking at the source code is an excellent thing.

I say this as someone who had to read some Java today and ended up stuffing it through a comment stripper so that I could easily find what I needed to find.

This thread is not about the "visually lightweight" aspect of Markdown. That's a good thing. No argument there.

The thread is about how well documented the notation should be.

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

On Mon, 29 Apr 2013 18:04:47 +1200 "Richard A. O'Keefe" wrote:

so that there is no possibility of catching errors early; by definition in that processor there are no errors.

Haddock's markup isn't any better in that regard. I spent two hours on my first day with haddock figuring out that I needed an empty comment line before a code block. It didn't issue any warnings or errors either.

To be perfectly honest, most of the time when looking at a Haddock page, I end up clicking on the Source button because there are things I need to know that are in the source but not the documentation.

Besides fixities, orphan instances, type family instances and partially exported records? It would be beneficial of Haddock to list orphan instances on top of the page. In red. Iff adding markdown doesn't require a major restructuring of haddock, then a GSOC might be better spent adding support for all of these instead; someone else could add markdown later on their own after ML bikeshedding came to some conclusion.

On 30 April 2013 09:28, Richard A. O'Keefe wrote:

On 29/04/2013, at 10:04 PM, kudah wrote:

...

On Mon, 29 Apr 2013 18:04:47 +1200 "Richard A. O'Keefe" wrote:

...

so that there is no possibility of catching errors early; by definition in that processor there are no errors.

Haddock's markup isn't any better in that regard.

Did I praise Haddock?

...

I spent two hours on my first day with haddock figuring out that I needed an empty comment line before a code block. It didn't issue any warnings or errors either.

Report that as a bug.

For what it's worth, I've resurrected an old design I did and have been playing with it to see just how bad it really is to use something like @i<word> than _word_.

Everyone agrees it's useful to have @i<legible> markup :) I'm impressed with Mateusz' balanced summary of the issues and look forward to his GSoC project submission about _Markdown_. Conrad.