3 ms·

Negative; you should look up literate programming (http://en.wikipedia.org/wiki/Literate_programming http://en.wikipedia.org/wiki/Literate_programming). Basical

by scscsc 17y ago

Negative; you should look up literate programming (http://en.wikipedia.org/wiki/Literate_programming http://en.wikipedia.org/wiki/Literate_programming). Basically you compile the lhs into a pdf before reading it ;-)

jmillikin 17y ago
I'm quite aware of what literate programming is -- it's more than just writing a lot of comments. If you'd like to see the PDF of a literate library, check out the source code to my Haskell DBus implementation at < http://ianen.org/haskell/dbus/core.pdf http://ianen.org/haskell/dbus/core.pdf >. Just because the source code can be rendered to PDF, or contains a lot of comments, does not make it "literate". Literate programming is designed to abstract the compiler's strict syntactic requirements from the reader. LHS does not do this -- whether you use LaTeX or Bird-style comment markers, they're still just comments. You can't use them to re-arrange or repeat source code.
- jerf 17y ago
  Curiousity: I have made the argument a few times that literate programming has failed to take off in large part because Knuth-style literate programming set off to solve two problems simultaneously: Poor documentation, and poor ability to structure code. Poor documentation remains a problem, but the poor structuring was largely solved. Nowadays, if a program is poorly structured it is most likely because the author wasn't going to structure it well no matter what tools you handed him. With one of the two pillars of Knuth-style LP removed, it didn't have enough vitality to capture a large chunk of programmer mindspace. Please note that A: I'm just referencing the argument so we are all on the same page and B: I intend it strictly as an analysis of why it did not take off, it is not a normative statement about whether it is a good idea. A language like Haskell really thoroughly obviates the structural part of LP; it arguably has radically more powerful composition capabilities built into the language than LP does. Yet here you are writing Haskell with LP. I am curious why you are doing this, and whether you plan on continuing to do so or if this was a one-off. (Incidentally, I have come to loath the style of documentation that Hackage affords, in the UI sense of "afford". I'm generally skeptical of LP, but I'm not asking this because I think the Haskell community has great docs that remove the need for LP documentation. Still, I would be interested in your thoughts.)
  - jmillikin 17y ago
    Haskell has a more liberal structure than the languages early LP research focused on, but it's still not as flexible as a LP file. All exports must be before imports, which must be before definitions; modules can't be interleaved; when pattern matching, all patterns must be on consecutive lines. I've found the usefulness of LP to be directly related to (1) how large a particular library is and (2) how much original thought went into it. Most of my Haskell libraries, so far, are relatively small -- a few hundred lines, at most. Furthermore, many are bindings to C libraries -- GNU SASL, CPython, YAJL -- and there's not much complex code involved. For Haskell, the tipping point seems to be around 1000 LOC for "native" code. dbus-core is just over 2500 LOC, and is a reasonably complete implementation of DBus in pure Haskell. Using literate programming (specifically, NoWeb) has been tremendously helpful. It's the only library I use LP for, but that's only because it's the largest I've written in Haskell. Notably, another of my libraries (network-protocol-xmpp) is approaching the 1000 LOC mark, and I've noticed some problems keeping track of the code. I plan to convert it to LP / NoWeb after the next release. If you have any large, complex libraries, I highly recommend at least experimenting with LP. It's relatively easy to convert existing libraries to LP, and because NoWeb is so flexible, you can convert them a little bit at a time as you become more comfortable with the tools.

by scscsc 17y ago

jmillikin 17y ago

I'm quite aware of what literate programming is -- it's more than just writing a lot of comments. If you'd like to see the PDF of a literate library, check out the source code to my Haskell DBus implementation at < http://ianen.org/haskell/dbus/core.pdf http://ianen.org/haskell/dbus/core.pdf >. Just because the source code can be rendered to PDF, or contains a lot of comments, does not make it "literate". Literate programming is designed to abstract the compiler's strict syntactic requirements from the reader. LHS does not do this -- whether you use LaTeX or Bird-style comment markers, they're still just comments. You can't use them to re-arrange or repeat source code.

jerf 17y ago
Curiousity: I have made the argument a few times that literate programming has failed to take off in large part because Knuth-style literate programming set off to solve two problems simultaneously: Poor documentation, and poor ability to structure code. Poor documentation remains a problem, but the poor structuring was largely solved. Nowadays, if a program is poorly structured it is most likely because the author wasn't going to structure it well no matter what tools you handed him. With one of the two pillars of Knuth-style LP removed, it didn't have enough vitality to capture a large chunk of programmer mindspace. Please note that A: I'm just referencing the argument so we are all on the same page and B: I intend it strictly as an analysis of why it did not take off, it is not a normative statement about whether it is a good idea. A language like Haskell really thoroughly obviates the structural part of LP; it arguably has radically more powerful composition capabilities built into the language than LP does. Yet here you are writing Haskell with LP. I am curious why you are doing this, and whether you plan on continuing to do so or if this was a one-off. (Incidentally, I have come to loath the style of documentation that Hackage affords, in the UI sense of "afford". I'm generally skeptical of LP, but I'm not asking this because I think the Haskell community has great docs that remove the need for LP documentation. Still, I would be interested in your thoughts.)
- jmillikin 17y ago
  Haskell has a more liberal structure than the languages early LP research focused on, but it's still not as flexible as a LP file. All exports must be before imports, which must be before definitions; modules can't be interleaved; when pattern matching, all patterns must be on consecutive lines. I've found the usefulness of LP to be directly related to (1) how large a particular library is and (2) how much original thought went into it. Most of my Haskell libraries, so far, are relatively small -- a few hundred lines, at most. Furthermore, many are bindings to C libraries -- GNU SASL, CPython, YAJL -- and there's not much complex code involved. For Haskell, the tipping point seems to be around 1000 LOC for "native" code. dbus-core is just over 2500 LOC, and is a reasonably complete implementation of DBus in pure Haskell. Using literate programming (specifically, NoWeb) has been tremendously helpful. It's the only library I use LP for, but that's only because it's the largest I've written in Haskell. Notably, another of my libraries (network-protocol-xmpp) is approaching the 1000 LOC mark, and I've noticed some problems keeping track of the code. I plan to convert it to LP / NoWeb after the next release. If you have any large, complex libraries, I highly recommend at least experimenting with LP. It's relatively easy to convert existing libraries to LP, and because NoWeb is so flexible, you can convert them a little bit at a time as you become more comfortable with the tools.