Hello all, Is literate programming something you guys actually do (I only know that Paul Hudak does), or is it basically a nice idea from days gone by? In case you do, then how do you do it? Do you use lhs2TeX or what? Do you use "bird" style of full-blown LaTeX? Does any of you use leksah? I failed to see any support for literate programming in leksah. It candies the backslashes in e.g. \documentclass{article} to λdocumentclass{article}. In case you don't, then how do you document your code? If you write a paper which explains what your code does, then how do you do that? -- Martin
It's weird I was just thinking about LP in Haskell this morning. Check out John Milliken's dbus-core [1] written entirely in noweb. It is a pleasure to read and I am seriously considering adopting the technique for my Haskell projects. -deech [1] http://ianen.org/haskell/dbus/ On Sat, Jun 12, 2010 at 12:21 PM, Martin Drautzburg < Martin.Drautzburg@web.de> wrote:
Hello all,
Is literate programming something you guys actually do (I only know that Paul Hudak does), or is it basically a nice idea from days gone by?
In case you do, then how do you do it? Do you use lhs2TeX or what? Do you use "bird" style of full-blown LaTeX?
Does any of you use leksah? I failed to see any support for literate programming in leksah. It candies the backslashes in e.g. \documentclass{article} to λdocumentclass{article}.
In case you don't, then how do you document your code? If you write a paper which explains what your code does, then how do you do that?
-- Martin _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
On Sat, Jun 12, 2010 at 12:34:37PM -0400, aditya siram wrote:
It's weird I was just thinking about LP in Haskell this morning. Check out John Milliken's dbus-core [1] written entirely in noweb. It is a pleasure to read and I am seriously considering adopting the technique for my Haskell projects.
At my work we've recently started doing something similar to LP. "Real" LP didn't suite our needs, but we still wanted most of the benefits. Here are some thoughts, in no particular order: * We wanted something really easy, so that non-developers / non-latex people wouldn't be scared off. We decided on textile/markdown with the ability to embed latex math. We needed docs that were readable and "nice enough" rather than requiring publication quality typesetting. * We wanted source code to be source code, rather than having to preprocess it before compile or script execution. This suites us because the code is the product for us, not a paper about the code. * We wanted something language agnostic. Period. Six different LP tools for six languages is insane. Noweb would have worked nicely but for requirements above. There are a great many LP and LP-like solutions out there, but none of them that we saw meet the above points. We decided to roll our own solution by making a simple utility program to make documents from source code. It simply flips things "inside out" by extracting comments as the document and putting non-comments in \verbatim blocks. We only see comments as document when there's only whitespace and no code in front, as end of line comments tend to be techy comments and not real documentation. If it weren't for the firm desire that source code be source code we would have went with noweb, despite wanting to keep it simpler than latex. But our solution is a small amount of effort to get working with a front-end for "token to EOL" style comments like shell or haskell "--" comments. Doing front-ends for block comments adds effort, but not so much. Using Pandoc or similar for actual document processing gives you lots of options on the back-end and makes everything but the front end trivial. This isn't for everyone, and depends heavily on the three points above. -- Darrin Chandler | Phoenix BSD User Group | MetaBUG dwchandler@stilyagin.com | http://phxbug.org/ | http://metabug.org/ http://www.stilyagin.com/ | Daemons in the Desert | Global BUG Federation
On Saturday, 12. June 2010 19:06:39 Darrin Chandler wrote:
On Sat, Jun 12, 2010 at 12:34:37PM -0400, aditya siram wrote:
It's weird I was just thinking about LP in Haskell this morning. Check out John Milliken's dbus-core [1] written entirely in noweb.
Okay I'll check out noweb. My personal opionion as a haskell newbie is that I love literate programming. I can write down my train of thoughts along with the source code, then I read the generated document an I can find flaws in it much more easily than when reading the bare source. I understand that this becomes less of an issue when you become more experienced with haskell. Still it will always be a good way to promote haskel-style solutions. I don't have any problems with LaTeX, but a less verbose solution would do just fine. My biggest problem is actually literate programming in conjunction with leksah. Can anybody comment on this issue? Do you guys use leskah at all? -- Martin
On Sat, Jun 12, 2010 at 9:21 AM, Martin Drautzburg wrote: Hello all, Is literate programming something you guys actually do (I only know that
Paul
Hudak does), or is it basically a nice idea from days gone by? In case you do, then how do you do it? Do you use lhs2TeX or what? Do you
use "bird" style of full-blown LaTeX? Does any of you use leksah? I failed to see any support for literate
programming in leksah. It candies the backslashes in e.g.
\documentclass{article} to λdocumentclass{article}. In case you don't, then how do you document your code? If you write a paper
which explains what your code does, then how do you do that? This is all my opinion, but it's largely based on my experience with reading
lots of haskell source, especially the darcs source which used to be almost
completely in the latex style of literate haskell. These days, very little
of it is literate haksell.
I think literate haskell is a mistake for most programs and libraries. If
your goal is to write API level documentation then haddock is more suitable
for the task. The documents created by haddock always have the same layout
and consistent look so people new to your API can jump right in and not have
to worry about learning how to navigate the docs too much. And any
improvements to haddock as an API level documentation system will instantly
benefit your sources. In other words, you don't have to maintain any
special latex macros or preprocessors to get good API docs. Another
important aspect is that hackage can run haddock on your sources and present
the result to people. This helps for anyone who is interested in your
library.
I think that literate haskell is particularly a bad idea when your goal is
to insert the user manual into a program's source code. My experience with
the darcs source was that mostly developers would ignore the huge sections
of latex when editing the code and it would get out of sync with the code.
It was too much of a distraction. People trying to edit the manual often
didn't know Haskell or the darcs source so they would fumble around and
resort to grep to find what the wanted to change then they'd have to send a
patch that edits haskell files. This then makes you need to review the
patches carefully to review it for edits to code. That is, documentation
changes need less rigorous review typically than code changes, but when the
patch mentions modules with core functionality you end up double checking
the patch for changes to the core logic.
For papers, emails, and blog posts literate haskell is probably a really
good idea. When you want to write a tutorial style explanation of the code,
literate seems to be a win.
If you are going to use literate haskell, then I believe the latex style is
much nicer because you don't have to prefix every single line with a
character. Plus when used over email, having lines start with "> " confuses
email clients because that's the most common character inserted for replies.
If it confuses the software people use, you can assume that at least some
members of your audience will also get confused.
This is all just my opinion, but hopefully it's still helpful,
Jason
On Sat, Jun 12, 2010 at 09:21, Martin Drautzburg
Is literate programming something you guys actually do (I only know that Paul Hudak does), or is it basically a nice idea from days gone by?
I use it occasionally for large projects -- its usefulness seems to be strongly related to how complex / large the codebase is. About 1000 SLOC of code (disregarding constants, comments, etc) is my personal tipping point.
In case you do, then how do you do it? Do you use lhs2TeX or what? Do you use "bird" style of full-blown LaTeX?
I've experimented with LHS, NoWeb, and NuWeb. LHS is useless -- you can achieve the exact same effect with standard comments. I can't figure out why it exists. NuWeb is nice, but immature -- I had trouble getting it to generate correct output without jumping through hoops. NoWeb is my current preference for literate programming with Haskell. I'm writing my own preprocessor, designed for Haskell, though it's more of a "something to avoid washing the dishes" project than a "this will ever be released or useful" project. All commentary is marked up with LaTeX. I suppose you could use reStructuredText or HTML, but LaTeX has better support for embedding maths. Something to note is that Cabal really can't handle literate programming well. Its preprocessor support assumes a 1:1 correspondence for generated files, which is not present in any non-trivial project. This can be worked around by using Make to run the preprocessor, and distributing the generated files in Hackage tarballs.
Does any of you use leksah? I failed to see any support for literate programming in leksah. It candies the backslashes in e.g. \documentclass{article} to λdocumentclass{article}.
I've tried using Leksah, but it doesn't display tabs, which obviously makes formatting rather difficult / impossible. I wonder how anybody can use it -- do they just use spaces and avoid indenting completely? GEdit and Vim both work well.
I've experimented with LHS, NoWeb, and NuWeb. LHS is useless -- you can achieve the exact same effect with standard comments. I can't figure out why it exists. NuWeb is nice, but immature -- I >had trouble getting it to generate correct output without jumping through hoops. NoWeb is my current preference for literate programming with Haskell.
This is not true. You can't have for instance a HTML documentation mixed with your source with just plain comments, style code blocks etc and only have to maintain one source.
I'm writing my own preprocessor, designed for Haskell, though it's more of a "something to avoid washing the dishes" project than a "this will ever be released or useful" project.
All commentary is marked up with LaTeX. I suppose you could use reStructuredText or HTML, but LaTeX has better support for embedding maths.
So... You're basically recreating LHS. You do know that LHS supports latex style documentation. LHS is far from useless since It's a good way to for instance write a paper. I've seen a great deal of papers written in LHS, the advantage is that when you change the code, you don't have to update a separate file. (see lhs2tex)
Something to note is that Cabal really can't handle literate programming well. Its preprocessor support assumes a 1:1 correspondence for generated files, which is not present in any non-trivial ?>project. This can be worked around by using Make to run the preprocessor, and distributing the generated files in Hackage tarballs.
I've tried using Leksah, but it doesn't display tabs, which obviously makes formatting rather difficult / impossible. I wonder how anybody can use it -- do they just use spaces and avoid indenting >completely?
This one completely confused me. You need to see a tab to know how the formatting would look? Or how the indented line looks?
GEdit and Vim both work well.
Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
On 13 Jun 2010, at 08:33, John Millikin wrote:
Does any of you use leksah? I failed to see any support for literate programming in leksah. It candies the backslashes in e.g. \documentclass{article} to λdocumentclass{article}.
I've tried using Leksah, but it doesn't display tabs, which obviously makes formatting rather difficult / impossible. I wonder how anybody can use it -- do they just use spaces and avoid indenting completely?
Pressing the tab key in Leksah inserts spaces to take you to the appropriate place. Backspace key does not currently work as well as it should to go back a level of indentation. Using tab characters in Haskell code is a bad idea... http://urchin.earth.li/~ian/style/haskell.html If you don't have time to read the full article, then here is the conclusion they reach... "Do not use tabs. At all. Now all programs look identical everywhere, and everyone is happy, regardless of their editor settings! From simplicity comes beauty." Hamish
participants (7)
-
aditya siram -
Darrin Chandler -
Hamish Mackenzie -
Jason Dagit -
John Millikin -
Martin Drautzburg -
Phyx