Talk:Literate programming
|
|
Suitability of the example
The example given is not literate programming (follow the link at the bottom of the page to see what literate programming is about). This article should be wound back, or the example section replaced with a better example (e.g. a java class with javadoc-style comments). See also Talk:Interpreter (computer software) -- AndrewKepert 04:56, 25 Aug 2003 (UTC)
A literate program is a descriptive document for people containing program text marked in such a way that a literate programming system can tell the difference between the program text and the rest of the document for processing purposes. Take a look at the article/program contained in the adventure.pdf file on the literate programming site. In principle there is no difference between that article and this one apart from the method used to mark the program text so it puzzles me that you do not consider this article to be an example of literate programming. Perhaps you can give your reasons in a little more detail.
As far as I can see, the entire Literate programming article constitutes a simplified literate programming example, usable by people for tutorial purposes, or by its "literate programming system", ie the example interpreter on the interpreter page, as stated. The facts that it does not extract the program code from the article to make a separate program, that it is not usable as much more than an example, and that it is not a CWEB system nor any of the other more functional literate programming systems, are neither here nor there. It is intended to be a simple example of the essence of a literate program which avoids the clutter introduced to real systems by the need for functions which are not directly related to literate programming or which are needed for realistically sized programs.
Furthermore this type of simple literate programming system is not original to me. I first saw it described as an Awk implementation in one of Jon Bentley's excellent Programming Pearls books in the early 1990s.
Admittedly the article does not tell the whole story about literate programming but that is not unusual for the Wikipedia. The answer to that is either to expand the article or, as you say, to follow the link at the bottom of the page. -- Derek Ross
- The example is essentially "code with comments", which is not what literate programming is. There is no description of the algorithms and intent in the design of the program, nor of decisions made in implementation. The point of literate programming is that the code is secondary and follows from this description. To a purist, the code need not even be read except to check that the implementation does what it the decription says. The example "adventure.pdf" has sections describing algorithms and storage (e.g. Section 19, sections 71+) which follow this structure, and other sections (23-70 -- essentially data dumps) where this is relaxed as the code becomes more self-documenting (particularly in light of some well-chosen macros and function names).
- The reason for my earlier brief comment was that the example is a poor example of literate programming since it is indistinguishable from non-literate programming. If there is a large grey area (which in this case includes a lot of javadoc stuff too) then examples given should strive to highlight what separates literate from other programming. To illustrate this with your code, I could suggest some modifications
- First let's find out the user's name
- In the interests of putting the user at ease, the program will simulate personal interest in the user by asking for their name, accepting the input and generating a greeting based on the input text.
- Now let's work out the area of a circle. The user will be asked for the radius first.
- Continuing the "query-response" mode of operation, prompt the user for the radius of a circle, which is then used to calculate the area of a circle using the standard formula for the area of a circle: A = πr2. Due to syntax limitations, this is done by multiplying the input value by itself, then by π. This calculated value is returned to the user. Note: the value of π used is an approximation that is sufficiently accurate for our purposes.
- However, I still don't think such suggestions shift the example sufficiently far from the grey area to make it a good example. Others' opinions may differ.
- Cheers, AndrewKepert 22:42, 25 Aug 2003 (UTC)
Okay, that makes it clear. The example is poor and needs improving. Well, I can live with that. Once I contribute something to Wikipedia, it belongs to Wikipedia, not to me, and I expect it to be improved mercilessly. Personally, I'd be quite happy to add your text to the article and will do so since it's manifestly better than the comment-like text which I used. On the other hand, you seem to think that the example needs total replacement. I don't think that that is really necessary but if you feel strongly about it, it's fine by me. My only proviso is that the example isn't too large and is based on a WEB like system rather than JavaDocs. The reason that I say this is that JavaDocs appears to me to be a system for processing programs containing document generation code rather than a system for processing documents containing program text. It's a subtle point but I think that it's important. To me the latter is what Knuth meant by "literate programming". -- Derek Ross
- IMHO a good example here need not be accessible as a piece of code, as the code (or fragment thereof) is embedded in the documentation. Consequently, there is nothing wrong with pulling a fragment (© allowing) from a well-written piece of real-world literate programming as an example. Having the algorithm/etc described and then the implementation would be a valuable illustration, even if the language of implementation is somewhat techincal. One possible source of examples is the LaTeX project. Its source files are in the form of self-documenting .dtx files. These can be typeset (via LaTeX of course) on their own to produce documentation (in the form of paragraphs with embedded snippets of code), or processed using docstrip to produce the style, class, etc files. I will have a scrounge through tetex to see if I can find a good small example. The reason why I (regrettably) orginally suggested javadoc is that someone might be able to dig out a good example that is small and illustrative of the qualities of LP. -- AndrewKepert 08:37, 27 Aug 2003 (UTC)
- PS btw I will fix the formula from "pr2" to πr2 -- AK
Sounds good, Andrew. Please go ahead. -- Derek Ross
Code Blocks
Another problem with the example is that it does not show code block rearrangement, though this is claimed as crucial for the effectiveness of literate programming before. -- Ar 13:16, 2004 Dec 5 (UTC)
- Well I do have an enhanced version of the current literate programming interpreter with a preprocessing stage which can handle code block re-arrangement too but I thought it a little too complex for the interpreter article. I suppose that I could add it to WikiSource and put links to it from this article. -- Derek Ross | Talk 15:50, 2004 Dec 6 (UTC)
Mention of Haskell
Someone inserted the note that Haskell makes "full use of literate programming". I have not been following the latest developments with Haskell and all the talk about an updated standard, but IIRC the "literate" mode most Haskell implementations support is essentially "excessive comments" together with the requirement of marking code by a prepended ">". But I still have to put "module Foo where" before any definitions in module Foo, and I cannot simply accumulate the list of exported identifiers by appending something to the list-of-exported-identifiers chunk whenever I define something. I would like someone more knowledgable about the state of literate programming in Haskell to comment on this and/or correct the mention in the article. -- Ar 16:57, 2005 Feb 7 (UTC)