[Haskell-cafe] Hackage package "synopsis" sections

Tue Sep 16 18:57:38 UTC 2014

On 09/16/2014 07:38 PM, Michael Snoyman wrote:
> On Tue, Sep 16, 2014 at 8:16 PM, Mateusz Kowalczyk <fuuzetsu at fuuzetsu.co.uk>
> wrote:
> 
>> On 09/16/2014 06:04 PM, Michael Snoyman wrote:
>>> On Tue, Sep 16, 2014 at 6:58 PM, Mateusz Kowalczyk <
>> fuuzetsu at 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.

OK, if that's what you want then that's fine. I am simply trying to
clarify that it's not ‘let's use Markdown because Haddock can't do X, Y
and Z’.

> 
>>> 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).

Fair.

> 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?

It is correct you can't include HTML for the same reason we don't allow
embedding LaTeX: we want to be able to target multiple back-ends and it
is unclear what to do with HTML when rendering as LaTeX and vice-versa.
So you're correct that Haddock is not suited as a formatting tool for
web pages, it's a code documentation tool.

It does go the other way too by the way, Markdown won't let you link to
modules, identifiers and all that, so Markdown is not suited for code
documentation. It really depends what you're after I suppose.

> 
>>> 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."

I specifically said ‘existing system’. If you *right now* wanted to be
able to write your comments/synopsis in Markdown then you can, it's just
not Hackage-native.

> 
>>> 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
> 

OK, to summarise:

* separate file for synopsis is a good idea

* Currently Hackage only supports Haddock descriptions

* Ideally Hackage should support more formats

* You want to use Markdown as one of the formats because you like it
rather than because Haddock has bugs which stop you from doing so.

* The workaround to be able to use Markdown before this proposal is
implemented is to use pandoc

As long as there is no disagreement as to this summary, we are on the
same page, I consider the previous exchange more of a miscommunication
rather than disagreement.

-- 
Mateusz K.