[Haskell-cafe] Hackage package "synopsis" sections

[Michael Snoyman]

On Tue, Sep 16, 2014 at 9:57 PM, Mateusz Kowalczyk <fuuzetsu at fuuzetsu.co.uk>
wrote:

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

Good summary. I've opened up an issue for this:
https://github.com/haskell/hackage-server/issues/262
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140917/6a771e82/attachment.html>