7 ms·

I was curious about how this worked so I looked into the source a little (even though Haskell isn't exactly my cup of tea), and WOW... This is just amazing. The

by pierrec 10y ago

I was curious about how this worked so I looked into the source a little (even though Haskell isn't exactly my cup of tea), and WOW... This is just amazing. The most important part of the source is highly educative literate haskell: https://github.com/jameysharp/corrode/blob/master/src/Language/Rust/Corrode/C.md https://github.com/jameysharp/corrode/blob/master/src/Langua...

vvanders 10y ago
That's an incredibly brilliant idea, there's some serious craftsmanship going on in that source file. Kinda taking Rust's doc unit tests format to a whole new level.
- moosingin3space 10y ago
  Rust should have a literate source format - with how much the community focuses on documentation, this would be an excellent addition.
  - steveklabnik 10y ago
    https://github.com/rust-lang/rust/issues/26097 https://github.com/rust-lang/rust/issues/26097
    - DanWaterworth 10y ago
      With the literate style, code is prefixed and comments are raw. So, instead of: -- foo is a function foo :: String -> String It's foo is a function > foo :: String -> String
      - vvanders 10y ago
        You could probably hack something together with a build.rs and a preprocessor, but that would probably not be very nice long term.
      - steveklabnik 10y ago
        Sorry, I am not understanding what you're implying here. I am well aware of the definition of literate programming. (And what you've said isn't actually enough to be considered literate programming under Knuth's definition: that's just tangle, still missing weave. Though notably, a lot of people argue that weave isn't needed with today's programming languages...)
        DanWaterworth 10y ago
        I mentioned it because I didn't see it in my scanning of the issue you linked to. Edit: I should have looked more closely, sorry.
        steveklabnik 10y ago
        Ah, no worries! I agree the issue is slightly down in the weeds, but don't worry, it's tracking the right thing :)
      - rekado 10y ago
        Literate programming is more than that. It is encouraged to order things such that they make sense to the reader, not to the compiler. You can give names to chunks of code and later glue them all together in a different order. My tool of choice for this is Emacs org-mode with noweb support. The source file is "tangled" (i.e. individual chunks of code are glued back together in a specified order) to create the source for the compiler to process. Haskell itself has only limited support for literate programming. Most importantly it lacks the ability to reorder chunks of code. (noweb or org-mode babel can be used with Haskell, of course.)
        fanf2 10y ago
        There's little need to reorder Haskell code because you can define things in any order. The literate programming tangle process mainly exists to remove Pascal's order restrictions.
        rekado 10y ago
        Reordering is still useful in Haskell. Just two examples for order dependent things in Haskell: top-level Template Haskell splicing; imports and GHC feature comments. It can be nice to have a single document explaining the whole project, producing individual source files upon tangling. For this approach you need control over order and target files. "Literate Haskell" is hardly more than a reversal of the meaning of comments and code.
  - killercup 10y ago
    There'a crate for that ;) https://github.com/pnkfelix/tango https://github.com/pnkfelix/tango
ctb_mg 10y ago
As someone who knows zero haskell, and little markdown, can someone explain how this works? haskell.org [1] says there is "bird style" and "LaTeX style" ways of marking off code vs documentation, and I see neither in the linked file. Is it the "```haskell" blocks? [1] https://wiki.haskell.org/Literate_programming#Haskell_and_literate_programming https://wiki.haskell.org/Literate_programming#Haskell_and_li...
- danidiaz 10y ago
  Yes, that seems to be the syntax used by literate markdown https://ghc.haskell.org/trac/ghc/wiki/LiterateMarkdown https://ghc.haskell.org/trac/ghc/wiki/LiterateMarkdown
  - ahakki 10y ago
    Just some additional info, because literate markdown support is not completly frictionless yet: To so this yourself you need to add the --markdown-unlit flag to ghc and add the package "markdown-unlit" to your dependencies. Additionally you have to symlink your .md file to .lhs, as ghc does not look at .md files (even with the --markdown-unlit flag, which I find kinda sad)
  - ahakki 10y ago
    Just some additional info, because literate markdown support is not completly frictionless yet: To so this yourself you need to add the --markdown-unlit flag to ghc and add the package "markdown-unlit" to your dependencies. Additionally you have to symlink your .md file to .lhs, as ghc does not look at .md files (even with the --markdown-unlit flag, which I find kinda sad)

by pierrec 10y ago

vvanders 10y ago

That's an incredibly brilliant idea, there's some serious craftsmanship going on in that source file. Kinda taking Rust's doc unit tests format to a whole new level.

moosingin3space 10y ago
Rust should have a literate source format - with how much the community focuses on documentation, this would be an excellent addition.
- steveklabnik 10y ago
  https://github.com/rust-lang/rust/issues/26097 https://github.com/rust-lang/rust/issues/26097
  - DanWaterworth 10y ago
    With the literate style, code is prefixed and comments are raw. So, instead of: -- foo is a function foo :: String -> String It's foo is a function > foo :: String -> String
    - vvanders 10y ago
      You could probably hack something together with a build.rs and a preprocessor, but that would probably not be very nice long term.
    - steveklabnik 10y ago
      Sorry, I am not understanding what you're implying here. I am well aware of the definition of literate programming. (And what you've said isn't actually enough to be considered literate programming under Knuth's definition: that's just tangle, still missing weave. Though notably, a lot of people argue that weave isn't needed with today's programming languages...)
      - DanWaterworth 10y ago
        I mentioned it because I didn't see it in my scanning of the issue you linked to. Edit: I should have looked more closely, sorry.
        steveklabnik 10y ago
        Ah, no worries! I agree the issue is slightly down in the weeds, but don't worry, it's tracking the right thing :)
    - rekado 10y ago
      Literate programming is more than that. It is encouraged to order things such that they make sense to the reader, not to the compiler. You can give names to chunks of code and later glue them all together in a different order. My tool of choice for this is Emacs org-mode with noweb support. The source file is "tangled" (i.e. individual chunks of code are glued back together in a specified order) to create the source for the compiler to process. Haskell itself has only limited support for literate programming. Most importantly it lacks the ability to reorder chunks of code. (noweb or org-mode babel can be used with Haskell, of course.)
      - fanf2 10y ago
        There's little need to reorder Haskell code because you can define things in any order. The literate programming tangle process mainly exists to remove Pascal's order restrictions.
        rekado 10y ago
        Reordering is still useful in Haskell. Just two examples for order dependent things in Haskell: top-level Template Haskell splicing; imports and GHC feature comments. It can be nice to have a single document explaining the whole project, producing individual source files upon tangling. For this approach you need control over order and target files. "Literate Haskell" is hardly more than a reversal of the meaning of comments and code.
- killercup 10y ago
  There'a crate for that ;) https://github.com/pnkfelix/tango https://github.com/pnkfelix/tango

ctb_mg 10y ago

As someone who knows zero haskell, and little markdown, can someone explain how this works? haskell.org [1] says there is "bird style" and "LaTeX style" ways of marking off code vs documentation, and I see neither in the linked file. Is it the "```haskell" blocks? [1] https://wiki.haskell.org/Literate_programming#Haskell_and_literate_programming https://wiki.haskell.org/Literate_programming#Haskell_and_li...

danidiaz 10y ago
Yes, that seems to be the syntax used by literate markdown https://ghc.haskell.org/trac/ghc/wiki/LiterateMarkdown https://ghc.haskell.org/trac/ghc/wiki/LiterateMarkdown
- ahakki 10y ago
  Just some additional info, because literate markdown support is not completly frictionless yet: To so this yourself you need to add the --markdown-unlit flag to ghc and add the package "markdown-unlit" to your dependencies. Additionally you have to symlink your .md file to .lhs, as ghc does not look at .md files (even with the --markdown-unlit flag, which I find kinda sad)
- ahakki 10y ago
  Just some additional info, because literate markdown support is not completly frictionless yet: To so this yourself you need to add the --markdown-unlit flag to ghc and add the package "markdown-unlit" to your dependencies. Additionally you have to symlink your .md file to .lhs, as ghc does not look at .md files (even with the --markdown-unlit flag, which I find kinda sad)