search

jgm / cheapskate

Experimental markdown processor in Haskell
BSD 3-Clause "New" or "Revised" License
107 stars 18 forks source link

Adapting cheapskate for use in Haddock #23

Open harpocrates opened 6 years ago

harpocrates commented 6 years ago

This is more of a question that an issue.

One of the most common requests for Haddock is to support markdown. This has somewhat controversial - everyone agrees Haddock is suboptimal but the path forward is still unclear. I'd like to try implementing a module level option where Haddock-the-tool expects all documentation to be markdown instead.

There are already a bunch of things to solve here, not the least of which is parsing markdown without adding any dependencies to Haddock. This package seems like a really good candidate for this. Would you be OK if some form of this library ended up in Haddock?

Furthermore, are there any licensing issues here?

Thanks in advance!

jgm commented 6 years ago

Cheapskate has some serious parsing bugs (I'm sorry, I don't recall the details), and it's not maintained any more.

My recommendation would be to use cmark or cmark-gfm. In fact, I showed how to do this a long time ago:

https://www.reddit.com/r/haskell/comments/325il3/markdown_in_haddock_proof_of_concept/

The only problem is that this is a C library, with the potential safety issues that brings. But it's pretty battle-tested and undergoes continuous fuzz testing.

I'd love it if someone wrote an efficient CommonMark parser in pure Haskell.

+++ Alec Theriault [Jan 10 18 19:13 ]:

This is more of a question that an issue.

One of the most common requests for Haddock is to support markdown. This has somewhat controversial - everyone agrees Haddock is suboptimal but the path forward is still unclear. I'd like to try implementing a module level option where Haddock-the-tool expects all documentation to be markdown instead.

There are already a bunch of things to solve here, not the least of which is parsing markdown without adding any dependencies to Haddock. This package seems like a really good candidate for this. Would you be OK if some form of this library ended up in Haddock?

Furthermore, are there any licensing issues here?

Thanks in advance!

— You are receiving this because you are subscribed to this thread. Reply to this email directly, [1]view it on GitHub, or [2]mute the thread.

References

  1. https://github.com/jgm/cheapskate/issues/23
  2. https://github.com/notifications/unsubscribe-auth/AAAL5M1RXE9b4-vK9rghdG2er_k4Og5Bks5tJQvUgaJpZM4RZzoG
harpocrates commented 6 years ago

Cheapskate has some serious parsing bugs (I'm sorry, I don't recall the details), and it's not maintained any more.

That's OK! It just needs to be roughly correct. Of the pure-Haskell markdown libraries, I think it is probably the best one. Also, I'm proposing to copy large swaths of cheapskate code directly into Haddock, so any maintenance would fall on Haddock. In fact, I've already done this on a local branch of Haddock I have. The changes aren't really fundamental, but they touch everything

My recommendation would be to use cmark or cmark-gfm. In fact, I showed how to do this a long time ago:

Unfortunately, I don't think Haddock would consider adding a dependency on a C library (otherwise, I completely agree with your comment), or for that matter, any external package (let alone text).

Besides, I'm sure that we'd end up having to support some markdown-like dialect that isn't quite markdown, so having a pure Haskell parser that we can freely tweak is important.

My question remains though: are you OK with code from cheapskate hypothetically ending up in Haddock?

jgm commented 6 years ago

+++ Alec Theriault [Jan 10 18 19:38 ]:

Cheapskate has some serious parsing bugs (I'm sorry, I don't recall
the details), and it's not maintained any more.

That's OK! It just needs to be roughly correct. Also, I'm proposing to copy large swaths of cheapskate code directly into Haddock, so any maintenance would fall on Haddock. In fact, I've already done this on a local branch of Haddock I have. The changes aren't really fundamental, but they touch everything

  • take out HTML rendering
  • take out XSS sanitation
  • switch Text to String (Haddock can't depend on text)

  • prune all dependencies save for containers, transformers, and base

    My recommendation would be to use cmark or cmark-gfm. In fact, I showed how to do this a long time ago:

    Unfortunately, I don't think Haddock would consider adding a dependency on a C library (otherwise, I completely agree with your comment), or for that matter, any external package (let alone text).

    Besides, I'm sure that we'd end up having to support some markdown-like dialect that isn't quite markdown, so having a pure Haskell parser that we can freely tweak is important.

    My question remains though: are you OK with code from cheapskate hypothetically ending up in Haddock?

Well, I released it under a permissive license, so sure.

Still, I don't think it's a terribly good foundation for markdown parsing in Haddock.