On Tue, Sep 16, 2014 at 8:16 PM, Mateusz Kowalczyk
On 09/16/2014 06:04 PM, Michael Snoyman wrote:
On Tue, Sep 16, 2014 at 6:58 PM, Mateusz Kowalczyk < fuuzetsu@fuuzetsu.co.uk> wrote:
On 09/16/2014 05:13 AM, Michael Snoyman wrote:
So again, I really like the idea of doing the same thing for synopses as we have already for changelogs.
I also do, I am here merely to investigate why Markdown is so strongly preferred when Haddock does the job. Yes, the escaping was really bad in the past. Yes, it had some weird bugs. Yes, it has been fixed. To my knowledge, we have zero bugs open on the issue tracker[5]. There are some that are to do with GHC lexer + parser but those are not relevant at all here. If you know of bugs then please report them.
I don't think I can make my point any clearer. I demonstrated that the bug I brought up four years ago still exists,
…what? I just showed you that it no longer exists, linked to the source files used to generate it with your own input and linked to output. The bug was fixed, there's nothing more to it.
I think you're discussing a strawman. The original proposal I made is "let's do Markdown in a separate file, because the current cabal + Haddock situation doesn't work." I demonstrated that. You're now saying that "it's not Haddock, it's cabal." That may be true, but it doesn't negate my point in the least: we could realize use an alternative, and the alternative I'd like is README.md.
that a separate file makes more sense
Yes.
, that people are more familiar with markdown, that existing tools (editors and sites like Github) already have very solid Markdown support. You've used the same argument multiple times: Markdown has multiple flavors. I get it, you don't like Markdown. You made that clear. But many others- myself included- *do* like Markdown, and want to be able to use it. Your arguments don't convince me that my desires are invalid.
I don't neither dislike Markdown nor think your desires are invalid. I am only trying to understand what your problem with Haddock is. That's it. You say there's a bug, I show that it's fixed. What else is there?
I only mention various Markdown flavours for a simple reason: it is to deter any potential ‘Haddock should just support Markdown’ posts, like seen early in this thread.
It comes down to the fact that I like writing Markdown. Honestly, that's enough. As for the *reason* I like Markdown: it's because I'm __always__ writing Markdown. When I'm on Github's wiki or issue tracker, on Reddit, on Stack Overflow, on School of Haskell, or my blog. If you pay attention, even this email is Markdown-formatted. To my knowledge, Github does *not* support Haddock format, so I'd have to maintain both a README.md and README.haddock (part of the tooling issue I brought up). And on top of all that: I believe there are things that can be expressed in Markdown (via HTML blocks) that simply cannot be expressed in Haddock, such as tables. I could be mistaken on that point, however, can you clarify?
I'm not opposed to Hackage supporting multiple flavors of README files (much like Github does). But I really dislike someone saying "you shouldn't be able to edit in the file format that you like, because I have an objection to it." If you don't like Markdown, don't use it. But please don't tell me "Haddock markup is sufficient, you should use that." If you're hearing that "Markdown is so strongly preferred," maybe you should accept that people prefer Markdown.
No, again, I didn't say what you have to use and I even told you about a tool which can make it easy for you to write whatever you want in the existing system.
That's a non-starter and a cop-out. Saying "Hackage will only support Haddock, but you can use Markdown and manually convert to Haddock and hope that the conversion is lossless" is just another way of saying "you have to use Haddock."
So my ideal is: Hackage chooses some Markdown implementation- I don't really care which too much- and adds support for README.md files. It can also add support for README.html, README.haddock, README.asciidoc, and README.klingon for all I care. If people run into problems because Github flavored Markdown is different than Hackage flavored Markdown... well, that's a situation that people using Markdown are used to already, and have come to terms with. I won't be put off by that. I already encounter that when I copy-paste something from a Stack Overflow answer into a Reddit comment. I can deal with it. People with objections to Markdown are perfectly free to use whatever syntax they want as well.
Michael
OK, great. I'd still like to hear about this bug you mention as the only thing you pointed out has been fixed in June.
Lastly, who is going to implement all this stuff? It's easy to wish but I'm sure you have even less time than I do.
That's a great question, but irrelevant to whether this is a good feature. I'd rather figure out the first than conflate it with the second. Michael