--- root <[EMAIL PROTECTED]> wrote:
> > 1. LaTeX does not have standard markup specific to software > > documentation, such as examples or argument lists. I had > > to define new LaTeX commands to get what I wanted. > > I don't generally typeset code since the actual code is quoted > in the text. The documents I write are alternating code/text > sequences. So far I haven't had to write any latex macros and > I've been using noweb/latex/lisp for a few years now. As an alternative, there is a LaTeX package called Listings (http://www.ctan.org/tex-archive/macros/latex/contrib/listings/) that will provide pretty-printing for code. Apparently it can be used with noweb: http://ebit.lbl.gov/~arun/noweb.php I've been intending to give this a try but have not had time to do anything much coding wise this week. Even if Listings doesn't have what you want out of box perhaps a new language definition can be created. [snip] > How many times have you seen papers presented giving "results" > of programs you can't see and can't run? Why isn't the code > embedded in the paper? Quite a few, actually. I think oftentimes this is due to the hope of commercializing the code behind the result, although I find this rather sad in an academic setting. > Is the lisp garden going to turn into a javadoc-like, developer-only, > collection of code snippets? Or are we going to write thoroughly > documented, carefully structured programs that can be maintained > and modified? Probably the latter come after the former to a large extent. Literate Programming forces the programmer to think about what they are doing, and it rules out solutions that work but are not fully understood. As a beginner myself I know that temptation - you want to see something work, not spend long periods of time learning how to do it right. In the end I think the rewards (and the results) are much greater when one learns to do it right though. And the knowledge thus gained can be released as a freely available document, not a pay-only journal or book. (To be sure, both journals and books are indicated since they provide both editorial standards and a more stable physical medium than computers, but for the beginning coder with no resources it means the electronic version can still be freely had, and they need not wait on support or excess cash to begin learning.) [snip] > Will we do the same thing with Lisp? Why? It should be the case > that the whole X3J13 document is interwoven with the actual code > that implements it. If I REALLY want to know how setf forms work > then I can read both the standard description and the actual > implementation code in the same chapter. I need to get back to work on that, actually. The first tentative attempts to find people's contact info were not encouraging, so I suspect this will be a monumental undertaking. I don't suppose the ANSI folk would be willing to give us an "unofficial" copy of the tex files with clear license though (sigh). I need to break up the large table into smaller ones so I don't hit the wiki character limit. Gah. I would actually like to see it taken one step further - I think programming language standards should consist of both text and code as a literate document, and that way the spec is not only defined unambiguously but is also runnable - the spec not only will DEFINE the functionality, it will also PROVIDE it, with as much of the logic as makes sense defined in the language itself, and with the minimal necessary assembler code or other bootstrapping code present and defined in another, also standard language. Unfortunately, even the FSF's definition of Free does not take this vision into account - their own documents use the highly problematic GFDL. And Lisp presents even more problems. This is in fact why I would prefer to see a vanilla Modified BSD license on both code and documentation for efforts like this - that way the lawyers have no way and no reason to make any kind of fuss, and I think for things like standards the wider the use (commercial, free, whatever) the better for the standard. LGPL or LLGPL would probably work but there remains the difficulty of characterizing the relationships between lisp libraries in terms of the thinking of the *GPL licenses. If and when a really Free version of dpANS3 is available, I think it will be a highly worthwhile project to take CMUCL and SBCL, and start weaving the best available code from both into the spec document. I don't know if that would be a Gardner's project or not, but either way very much worth doing. (And talk about a perfect way to learn the in-depth gory details of Lisp...) > Why isn't the CLIM spec woven into the CLIM implementation code? > Why can't I look for how a line is drawn and see both the spec > and the implementation in the same place? As to the CLIM spec, I have never obtained any satisfactory answer on the copyright of that document. Apparently it was created by a number of lisp vendors back in the day, but it doesn't seem to contain any useful information in that respect. Perhaps that means it was intended to be public domain, and certainly no one I know of has raised any objection to it's being included in McCLIM and online as the annotateable spec. However, I think a second effort similar to the FreeSpec project for dpANS3 might eventually needed to resolve the issue completely. Garnet's docs aren't actually as free as I first thought, but the Garnet code itself is unambiguously public domain and (at least to my brain) seems a little simpler to grasp. I think there is probably room for both Garnet and McCLIM in the lisp world (look at how many GUI toolkits exist for other languages!) and since the Garnet source is public domain there is no question as to its being usable in a literate document. It probably would amount to the virtual creation of another spec or two from scratch, but with (mostly) working code. My ideal picture of the eventual layout of the lisp world would be: Community Lisp - created from dpANS3, CMUCL, and SBCL - ANSI CL+, basically. Hopefully CFFI will become something capable of being the foundation for a FFI specification, at least at the low level CLX - exists, needs a little updating and needs to be woven together with spec - the CLX manual would probably serve as the foundation document for a literate spec document. If I'm not mistaken the CLX manual is under a very liberal license. cl-gdi - beginngs exist in Dan Stanger's work on GDI for clisp - might need a fair bit of work for something robust but well worth it. Document would need to be created from scratch. cl-carbon - Beginnings of this one exist, too. Document would need to be created from scratch Garnet - created from current source code, with document written more or less from scratch. Updated look and feel, modernized Gadgets McCLIM - created from CLIM spec (with some updating, I understand various parts of the current document are almost unusably vague) and McCLIM source code. Obviously there are other components I would like to see, such as a TeX/Lout style typesetting package (cl-typesetting is a good start but a bit short on docs for this purpose :-/) a graphing module, a raytracer (for high level rendering) and other fun stuff. As literate documents, we could not only claim how high quality they were (like we all do with lisp) but we could invite any skeptic to read and see how the research done before and during the creation of the library measured up. > Why can't I learn about garbage collection by reading the source > code of my lisp implementation? Why doesn't it contain the text > of the book "Garbage Collection: Algorithms for Automatic Dynamic > Memory Management" for the algorithm used? Heh - unfortunately, in THAT case I doubt we'd ever get permission. We'd have to write our own paper based on the available work. I wonder how many thousands of pages the Lisp spec will wind up being if it does get made into a full fledged literate document? That would be something to see :-). > How come there is not "paper" on hashtables that contains the lisp > code so I can just drag-and-drop it onto my running lisp and have > a new hash table implementation with the documentation that explains > the theory? > > It's the late 90s... we should be able to do this. > > (throw 'soapbox-exit nil) IMHO the biggest problem other than just lack of interest is the traditional restrictions that exist on academic books and papers. I have a feeling Literate Programming, if it takes off, will have to update the definition of free software with a caveot: "A program is only as free as its documentation." Even if a program is not literate, making it literate without being able to freely incorporate its documentation makes the job almost as bad as a re-write in some ways. Of course, it can also be viewed as an opportunity to make a better library than existed previously, but its still a lot of work. Cheers, CY __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
