Initial support for supporting School of Haskell Markdown #832

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
2 participants
@stepcut

stepcut commented Apr 18, 2013

Add some support for a School of Haskell markdown extensions. My primary use case is to down-convert pandoc markdown documents to school of haskell compatible documents.

https://www.fpcomplete.com/school/how-to-use-the-school-of-haskell/soh-markdown

School of Haskell markdown is mostly strict markdown with two extensions.

  • @@@ fences to 'hide solution'
  • 
    

The current github code block parser only supports a single atttribute like:

But School of Haskell (http://www.fpcomplete.org) allows multiple attributes like:

 ``` haskell active web

This patch adds a new extension

    Ext_backtick_code_multi

which could probably be better named. Or, perhaps the normal github parser should be extended to always allow this?

The Markdown Reader has been extended with:

           <|> (guardEnabled Ext_backtick_code_multi >> ((\xs -> ("", xs, [])) <$> (identifier `sepBy1` (many1 (char ' ')))))

Which could possibly be improved. The writer has been extended as well.
Add some support for School of Haskell markdown extensions.
https://www.fpcomplete.com/school/how-to-use-the-school-of-haskell/soh-markdown

School of Haskell markdown is mostly strict markdown with two extensions.

 - @@@ fences to 'hide solution'
 - ``` style github code blocks

The current github code block parser only supports a single atttribute like:

 ``` haskell

But School of Haskell (http://www.fpcomplete.org) allows multiple attributes like:

 ``` haskell active web

This patch adds a new extension

    Ext_backtick_code_multi

which could probably be better named. Or, perhaps the normal github parser should be extended to always allow this?

The Markdown Reader has been extended with:

           <|> (guardEnabled Ext_backtick_code_multi >> ((\xs -> ("", xs, [])) <$> (identifier `sepBy1` (many1 (char ' ')))))

Which could possibly be improved. The writer has been extended as well.
@jgm

This comment has been minimized.

Show comment
Hide comment
@jgm

jgm Apr 18, 2013

Owner

I wish they'd taken my suggestion to use a single class,
activehaskell. Then their syntax would be more compatible with
what github (and pandoc) will accept. I did suggest this to them
but didn't get any response. Maybe you could try as well; increasing
fragmentation of markdown dialects is a bad thing.

It would be easy to write a program that auto-converted existing
School-of-Haskell markdown documents to use activehaskell
instead of haskell active.

Owner

jgm commented Apr 18, 2013

I wish they'd taken my suggestion to use a single class,
activehaskell. Then their syntax would be more compatible with
what github (and pandoc) will accept. I did suggest this to them
but didn't get any response. Maybe you could try as well; increasing
fragmentation of markdown dialects is a bad thing.

It would be easy to write a program that auto-converted existing
School-of-Haskell markdown documents to use activehaskell
instead of haskell active.

@stepcut

This comment has been minimized.

Show comment
Hide comment
@stepcut

stepcut Apr 23, 2013

I passed on the suggestion. They would need to support haskell, haskellactive, and haskellactiveweb. And possibly other variations in the future.
That said -- they do have other extensions listed here:

https://www.fpcomplete.com/school/how-to-use-the-school-of-haskell/soh-markdown

The most obvious is the @@@ fences which allow you to hide content until the user clicks on 'show more'. Useful for hiding punch lines, solutions, etc.

But, they also have a bunch of extensions to what can go in an source code block, such as hoogle links, the ability to hide/show/highlight stuff within the code block and more.

Obviously, not all these features can be supported by all output formats. And, supporting them would requiring modifying the internal representation of a code block to be more sophisticated. It is not yet clear that SoH is going to be popular enough to warrant adding explicit support for their extensions.

But, if it does become popular, I expect that they only way to support whatever other extensions they provide will be to create a markdown_soh format.

Anyway, I can understand not wanting to support yet another markdown dialect that may not even stick around.

It's too bad that we can't just add new formats and dialects as 3rd party plugins. Like, pandoc-markdown-soh. Then it could be its own separate thing maintained by fpcomplete.

stepcut commented Apr 23, 2013

I passed on the suggestion. They would need to support haskell, haskellactive, and haskellactiveweb. And possibly other variations in the future.
That said -- they do have other extensions listed here:

https://www.fpcomplete.com/school/how-to-use-the-school-of-haskell/soh-markdown

The most obvious is the @@@ fences which allow you to hide content until the user clicks on 'show more'. Useful for hiding punch lines, solutions, etc.

But, they also have a bunch of extensions to what can go in an source code block, such as hoogle links, the ability to hide/show/highlight stuff within the code block and more.

Obviously, not all these features can be supported by all output formats. And, supporting them would requiring modifying the internal representation of a code block to be more sophisticated. It is not yet clear that SoH is going to be popular enough to warrant adding explicit support for their extensions.

But, if it does become popular, I expect that they only way to support whatever other extensions they provide will be to create a markdown_soh format.

Anyway, I can understand not wanting to support yet another markdown dialect that may not even stick around.

It's too bad that we can't just add new formats and dialects as 3rd party plugins. Like, pandoc-markdown-soh. Then it could be its own separate thing maintained by fpcomplete.

@jgm

This comment has been minimized.

Show comment
Hide comment
@jgm

jgm Apr 23, 2013

Owner

+++ stepcut [Apr 23 13 11:28 ]:

It's too bad that we can't just add new formats and dialects as 3rd
party plugins. Like, pandoc-markdown-soh. Then it could be its own
separate thing maintained by fpcomplete.

If they changed to single-word classes, then with current pandoc you
could just write some simple json filters using the pandoc API.
These would find the appropriately labeled code blocks and process
them appropriately. They could maintain the json filters, and
keep them up to date as they added features.

It would actually not be hard for me to allow multiple classes
on backtick code blocks, and maybe I should, but I'm trying
to keep compatibility with github there -- it seems a worthy
goal.

Owner

jgm commented Apr 23, 2013

+++ stepcut [Apr 23 13 11:28 ]:

It's too bad that we can't just add new formats and dialects as 3rd
party plugins. Like, pandoc-markdown-soh. Then it could be its own
separate thing maintained by fpcomplete.

If they changed to single-word classes, then with current pandoc you
could just write some simple json filters using the pandoc API.
These would find the appropriately labeled code blocks and process
them appropriately. They could maintain the json filters, and
keep them up to date as they added features.

It would actually not be hard for me to allow multiple classes
on backtick code blocks, and maybe I should, but I'm trying
to keep compatibility with github there -- it seems a worthy
goal.

@stepcut

This comment has been minimized.

Show comment
Hide comment
@stepcut

stepcut Apr 24, 2013

Ah neat. The json filter thing sounds interesting. Also, I forgot to mention something that seemed important.

The downside of doing activehaskell, activehaskellweb, etc, is that syntax highlighters wouldn't know that those are really just Haskell code?

In my patch if you read something as markdown_soh and outputted it as markdown_github, it would use just he first parameter, which is usually ``` haskell. So at least highlighting would still work?

But, perhaps the json filter could rewrite that as well? I need to look more into this I guess.

stepcut commented Apr 24, 2013

Ah neat. The json filter thing sounds interesting. Also, I forgot to mention something that seemed important.

The downside of doing activehaskell, activehaskellweb, etc, is that syntax highlighters wouldn't know that those are really just Haskell code?

In my patch if you read something as markdown_soh and outputted it as markdown_github, it would use just he first parameter, which is usually ``` haskell. So at least highlighting would still work?

But, perhaps the json filter could rewrite that as well? I need to look more into this I guess.

@jgm

This comment has been minimized.

Show comment
Hide comment
@jgm

jgm Apr 24, 2013

Owner

+++ stepcut [Apr 23 13 20:40 ]:

But, perhaps the json filter could rewrite that as well? I need to look
more into this I guess.

Yes, my thought is that the json filter would do some serious rewriting.
In the simplest case, it could just change the attributes: going
from one class "activehaskell" to two ["active","haskell"].

But really, you're going to want to do something more interesting
with the contents of the code block, or what's the point?

For example, for "hidden" bits you might want to provide some
hooks for javascript. This would mean generating the HTML for the
code block in the json filter, since pandoc code blocks can't contain
raw HTML. You could also do things like shell out to GHCI to run
examples.

Anyway, my thought is that "school of Haskell markdown" might be a bit
too specialized to support in pandoc, and that it might make more sense
for THEM to support just the tool they want -- which could be done
via a json filter.

Owner

jgm commented Apr 24, 2013

+++ stepcut [Apr 23 13 20:40 ]:

But, perhaps the json filter could rewrite that as well? I need to look
more into this I guess.

Yes, my thought is that the json filter would do some serious rewriting.
In the simplest case, it could just change the attributes: going
from one class "activehaskell" to two ["active","haskell"].

But really, you're going to want to do something more interesting
with the contents of the code block, or what's the point?

For example, for "hidden" bits you might want to provide some
hooks for javascript. This would mean generating the HTML for the
code block in the json filter, since pandoc code blocks can't contain
raw HTML. You could also do things like shell out to GHCI to run
examples.

Anyway, my thought is that "school of Haskell markdown" might be a bit
too specialized to support in pandoc, and that it might make more sense
for THEM to support just the tool they want -- which could be done
via a json filter.

@stepcut

This comment has been minimized.

Show comment
Hide comment
@stepcut

stepcut Apr 24, 2013

Thanks! I'll look into that. THEM is mostly ME at the moment. I am trying to convert the Happstack Crash Course from a horrible mess of Makefile, sed, markdown.pl and HsColour, to using pandoc. And I want to be able to target HTML, PDF, ePub, kindle, and SoH. Obviously, I have to make some compromises to do that. But, I think the solution is that I have my own markdown variant that supports things like ``` activehaskell, and then outputs things the way I want them using the json filter stuff.

Thanks!

stepcut commented Apr 24, 2013

Thanks! I'll look into that. THEM is mostly ME at the moment. I am trying to convert the Happstack Crash Course from a horrible mess of Makefile, sed, markdown.pl and HsColour, to using pandoc. And I want to be able to target HTML, PDF, ePub, kindle, and SoH. Obviously, I have to make some compromises to do that. But, I think the solution is that I have my own markdown variant that supports things like ``` activehaskell, and then outputs things the way I want them using the json filter stuff.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment