[Haskell-cafe] Hackage package "synopsis" sections

[Michael Snoyman]

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.


> > 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140916/731230a1/attachment-0001.html>