1-Jul-1998 10:53:14-GMT,2308;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id EAA07454 for ; Wed, 1 Jul 1998 04:53:13 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Jul 1998 05:46:37 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: The `habitability' of source code Date: 29 Jun 1998 13:30:16 GMT Message-ID: <6n84t8$g4r$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 28 Jun 1998, Paolo Amoroso wrote: > Richard Gabriel, in his book "Patterns of Software - Tales from the > Software Community" (Oxford University Press, 1996), provides the following > definition of "habitability" (page 11; of course, his discussion is more > complex than what this definition may suggest): > > "Habitability is the characteristic of source code that enables > programmers, coders, bug-fixers, and people coming to the code later in its > life to understand its construction and intentions and to change it > comfortably and confidently. Either there is more to habitability than > clarity or the two characteristics are different." > > Although Gabriel knows Knuth's work very well, literate programming is > never mentioned in the book. Can literate programming be seen as a way of > improving - or even enabling - the habitability of source code? I'm > particularly interested in the opinions of those who have read the book. It certainly seems to me that habitability (by Gabriel's definition) is *precisely* what LP is all about. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | "Begin at the middle...then you're not so Computer Science Department | far from either the beginning or the Kean University | ending." Union, NJ 07083 | | -- Erle Stanley Gardner leew@samson.kean.edu | "The Case of the Fugitive Nurse" (1954) ------------------------------------------------------------------------ 1-Jul-1998 23:55:49-GMT,1051;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id RAA24775 for ; Wed, 1 Jul 1998 17:55:49 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Jul 1998 18:46:13 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: New noweb alpha version 980701 Date: 1 Jul 1998 23:17:40 GMT Message-ID: <6neg2k$s8m$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Thanks to a timely bug report from Barry Gaunt, I have repaired a memory-allocation bug in the lua-2.5+nw code used by noweb, version 3. This error could cause assertion failures or core dumps. Alpha testers should avoid versions before 980701, which is available now from http://www.cs.virginia.edu/~nr/noweb. Norman -- Norman Ramsey http://www.cs.virginia.edu/~nr 2-Jul-1998 6:41:37-GMT,1028;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id AAA03192 for ; Thu, 2 Jul 1998 00:41:36 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Jul 1998 01:37:49 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: prettyprinting question Date: 30 Jun 1998 18:39:15 GMT Message-ID: <6nbbcj$5rf$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu > > >> Has anybody come up with a good TeX hack for prettyprinting the box > > >> used in Dijkstra's calculus to mark arms of an if statement? > Can't you use LaTeX's \framebox with nothing inside? Yes. The dumb questions of the morning are: (a) what size should the nothing be? (b) how thick should the lines around the nothing be? 2-Jul-1998 6:56:36-GMT,1240;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id AAA03462 for ; Thu, 2 Jul 1998 00:56:35 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Jul 1998 01:54:04 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: Re: Alpha version of Noweb 3 available for your amusement Date: 30 Jun 1998 16:31:27 GMT Message-ID: <6nb3sv$19c$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu On 22 Jun 1998 21:44:11 GMT, Norman Ramsey wrote: > The means to all these good ends is to replace the shell scripts and > the Icon code with the embedded language Lua-2.5+nw. (This is Lua Do you mean that noweb 3 will have an `extension language' - in the Tcl sense - based on Lua? I'm not familiar with that language. Could you please provide a few basic references? Paolo -- Paolo Amoroso 2-Jul-1998 7:29:24-GMT,989;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id BAA04057 for ; Thu, 2 Jul 1998 01:29:23 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Jul 1998 02:26:44 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Pre-Announce and RFC for LP tool Date: 30 Jun 1998 20:07:25 GMT Message-ID: <6nbght$8p4$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6nau9r$ah6$1@elna.ethz.ch>, John Skaller wrote: >BTW: is there an online reference to 'NoWeb'? It would be useful to write >a noweb filter for the system. http://www.cs.virginia.edu/~nr/noweb contains pointers to the man pages and the hacker's guide. Norman 2-Jul-1998 10:30:02-GMT,1763;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id EAA07295 for ; Thu, 2 Jul 1998 04:30:01 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Jul 1998 05:24:56 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: prettyprinting question Date: 30 Jun 1998 18:39:21 GMT Message-ID: <6nbbcp$5rg$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 28 Jun 1998, Norman Ramsey wrote: > In article <6n36i6$io4$1@news.interlog.com>, > Michael Norrish wrote: > >> Has anybody come up with a good TeX hack for prettyprinting the box > >> used in Dijkstra's calculus to mark arms of an if statement? > > > \newcommand\dbox{\mbox{\large$[\:\!\!]$}} > > This isn't bad, although it's a little skinnier than what I had in > mind. Can't you use LaTeX's \framebox with nothing inside? Or do you want something that will work in plain TeX, as well? -- Lee ------------------------------------------------------------------------ Lee Wittenberg | "Begin at the middle...then you're not so Computer Science Department | far from either the beginning or the Kean University | ending." Union, NJ 07083 | | -- Erle Stanley Gardner leew@samson.kean.edu | "The Case of the Fugitive Nurse" (1954) ------------------------------------------------------------------------ 2-Jul-1998 17:50:32-GMT,1264;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id LAA16688 for ; Thu, 2 Jul 1998 11:50:24 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from brussel.planetinternet.be by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Jul 1998 12:41:35 EST Received: from ubnd-120.pop-gent2.planetinternet.be (ubnd-120.pop-gent2.planetinternet.be [194.119.236.120]) by brussel.planetinternet.be (8.9.0/8.9.0) with SMTP id TAA17086 for ; Thu, 2 Jul 1998 19:41:18 +0200 (MET DST) Message-ID: <199807021741.TAA17086@brussel.planetinternet.be> From: "=?iso-8859-0?q?J=81rgen_Defurne?=" To: "Literate Programming Newslist" Date: Thu, 02 Jul 98 19:36:14 Reply-To: LitProg@SHSU.edu, "=?iso-8859-0?q?J=81rgen_Defurne?=" MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by csc-sun.math.utah.edu id LAA16688 subscribe "Jrgen Defurne" 2-Jul-1998 22:28:03-GMT,1675;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id QAA23422 for ; Thu, 2 Jul 1998 16:28:02 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Jul 1998 17:22:41 EST From: Felix Gaertner Reply-To: LitProg@SHSU.edu, felix@informatik.th-darmstadt.de Subject: Re: prettyprinting question Date: 1 Jul 1998 17:03:56 GMT Message-ID: <6ndq5s$aqp$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Norman Ramsey wrote: > > In article <6n36i6$io4$1@news.interlog.com>, > Michael Norrish wrote: > >> Has anybody come up with a good TeX hack for prettyprinting the box > >> used in Dijkstra's calculus to mark arms of an if statement? > > > \newcommand\dbox{\mbox{\large$[\:\!\!]$}} > > This isn't bad, although it's a little skinnier than what I had in > mind. > > Thanks! I have used the slight variation \newcommand{\trenner}{\mbox{$[\!]$}} in all my documents containing guarded commands. In fact if you look at Dijkstra's original work (CACM 18 (8), pp. 453-457, 1975) on guarded commands, this is exactly how I think they typeset it. Felix -- =========="=================================================== Felix C. Gartner felix@informatik.tu-darmstadt.de Computer Science Department TU Darmstadt, Germany 3-Jul-1998 21:48:36-GMT,9242;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id PAA19896 for ; Fri, 3 Jul 1998 15:48:35 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Jul 1998 16:41:54 EST From: bfox@netscape.com (Barbara-Ann Fox) Reply-To: LitProg@SHSU.edu, bfox@netscape.com Subject: Re: Opportunity to spread the word about literate programming? Date: 2 Jul 1998 16:54:03 GMT Message-ID: <6ngdvb$oa2$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg=sha1; boundary="------------msEA5E84446F7B573A8A14BBD9" To: LitProg@SHSU.edu This is a cryptographically signed message in MIME format. --------------msEA5E84446F7B573A8A14BBD9 Content-Type: multipart/mixed; boundary="------------7FCCFFFC3FCCB67AE951DA52" This is a multi-part message in MIME format. --------------7FCCFFFC3FCCB67AE951DA52 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit I absolutely agree with Norman on this one. Having students write code for something they can hold in their hand will get these folks so excited about programming. Unfortunately, the program I went through (at the University of Albany) was sooo boring. We started off with a Pascal class (which repeated everything I learned in sophmore year of high school), then moved on to two semesters of COBOL. All of this was streamlined with courses like "Discrete Mathematics". I'm still in therapy! This is a very exciting time for software engineers. Part of what makes engineers thrive in the "corporate" world is the amount of freedom they are given. At Netscape, we have no set hours, no dress code, you can bring your pets to work, play sports mid-day, etc... Basically, put folks into a creative environment. Make them love what they do. Trust me, it works. Is there anyway I can help here? Barbara-Ann Lee Wittenberg wrote: > On 25 Jun 1998, Norman Ramsey wrote: > > > Some of you may have encountered the USRobotics/3Com `Palm Pilot' or > > `Palm III' handheld computer. This is a fun toy to have, and the > > specs are open, so lots of third parties write programs for it. > > The Unix crowd is way behind Windows here, so a lot of utilities and > > examples are still being cooked up. *Lots* of people are curious > > about how to write code for this thing, and I think this would be a > > great for literate programming if we as a community could get some > > example programs into the Pilot world. > > > > I was also thinking that turning the source code for somebody's > > existing program (e.g., HandyShopper) into a literate program would > > make a good class project, perhaps for a course like the one Lee > > Wittenberg is offering. > > Good idea. Steve Furlong and Aharon Robbins had already suggested > that I have students do some "maintenance" programming by retrofitting > LP onto an existing program. I've already planned on having them > tackle some of the smaller GNU/Linux utilities. The Palm Pilot stuff > would also be a good idea (if any of the students actually have one to > work with -- I don't). > > Where is the source for these programs available? > > > I really feel we as a community missed a chance to get our ideas into > > Linux when that took off. Well, maybe the Pilot is a second chance! > > A lovely thought, but I wish I could be optimistic. Structured > programming has never really taken hold (except as "a custom more > honour'd in the breach than the observance"), and it's been around > more than 35 years. The unfortunate fact is that anything requiring > the least self-discipline tends to fly out the window in the face of > deadlines, to the detriment of program maintenance (which, after all, > is LP's greatest strength). > > -- Lee > > ------------------------------------------------------------------------ > Lee Wittenberg | "Begin at the middle...then you're not so > Computer Science Department | far from either the beginning or the > Kean University | ending." > Union, NJ 07083 | > | -- Erle Stanley Gardner > leew@samson.kean.edu | "The Case of the Fugitive Nurse" (1954) > ------------------------------------------------------------------------ --------------7FCCFFFC3FCCB67AE951DA52 Content-Type: text/x-vcard; charset=us-ascii; name="vcard.vcf" Content-Transfer-Encoding: 7bit Content-Description: Card for Barbara-Ann Fox Content-Disposition: attachment; filename="vcard.vcf" begin: vcard fn: Barbara-Ann Fox n: Fox;Barbara-Ann org: Netscape Communications, Corporation email;internet: bfox@netscape.com title: Enterprise Support Account Manager x-mozilla-cpt: ;0 x-mozilla-html: TRUE version: 2.1 end: vcard --------------7FCCFFFC3FCCB67AE951DA52-- --------------msEA5E84446F7B573A8A14BBD9 Content-Type: application/x-pkcs7-signature; name="smime.p7s" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="smime.p7s" Content-Description: S/MIME Cryptographic Signature MIILAgYJKoZIhvcNAQcCoIIK8zCCCu8CAQExCzAJBgUrDgMCGgUAMAsGCSqGSIb3DQEHAaCC CS8wggR1MIID3qADAgECAhAOHxbMxzSLVyKqfQxoaBIWMA0GCSqGSIb3DQEBBAUAMGIxETAP BgNVBAcTCEludGVybmV0MRcwFQYDVQQKEw5WZXJpU2lnbiwgSW5jLjE0MDIGA1UECxMrVmVy aVNpZ24gQ2xhc3MgMSBDQSAtIEluZGl2aWR1YWwgU3Vic2NyaWJlcjAeFw05NzEyMjkwMDAw MDBaFw05ODEyMjkyMzU5NTlaMIIBDzERMA8GA1UEBxMISW50ZXJuZXQxFzAVBgNVBAoTDlZl cmlTaWduLCBJbmMuMTQwMgYDVQQLEytWZXJpU2lnbiBDbGFzcyAxIENBIC0gSW5kaXZpZHVh bCBTdWJzY3JpYmVyMUYwRAYDVQQLEz13d3cudmVyaXNpZ24uY29tL3JlcG9zaXRvcnkvQ1BT IEluY29ycC4gYnkgUmVmLixMSUFCLkxURChjKTk2MSYwJAYDVQQLEx1EaWdpdGFsIElEIENs YXNzIDEgLSBOZXRzY2FwZTEZMBcGA1UEAxMQQmFyYmFyYSBBbm4gIEZveDEgMB4GCSqGSIb3 DQEJARYRYmZveEBuZXRzY2FwZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKH7 pgdOGeWuXeUOcoOK9rESKWvfS+s6tDZbd/KsQaj22c35VncB9A43Y9mpLFyCWOUTlSA6DGwG 0/pNaMp6LudaDEjn19KeV/f+tD0CYplVikDW0XpNAji+rO7iChMD8Dqv6bOg0arbHTdh+4JR pU+u7gGiF7CLd706eOLBGu/3AgMBAAGjggF7MIIBdzAJBgNVHRMEAjAAMIGvBgNVHSAEgacw gDCABgtghkgBhvhFAQcBATCAMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy52ZXJpc2lnbi5j b20vQ1BTMGIGCCsGAQUFBwICMFYwFRYOVmVyaVNpZ24sIEluYy4wAwIBARo9VmVyaVNpZ24n cyBDUFMgaW5jb3JwLiBieSByZWZlcmVuY2UgbGlhYi4gbHRkLiAoYyk5NyBWZXJpU2lnbgAA AAAAADARBglghkgBhvhCAQEEBAMCB4AwgYYGCmCGSAGG+EUBBgMEeBZ2ZDQ2NTJiZDYzZjIw NDcwMjkyOTg3NjNjOWQyZjI3NTA2OWM3MzU5YmVkMWIwNTlkYTc1YmM0YmM5NzAxNzQ3ZGE1 ZDNmMjE0MWJlYWRiMmJkMmU4OTIwNmJkN2JlMWQ3MDY0MDk4YTNhYjQyZmRlMzk3NzUzYzAc BgpghkgBhvhFAQYGBA4WDDE3OTc3NDQ6SVN2MTANBgkqhkiG9w0BAQQFAAOBgQBaMOxerM/u 5kkDCJJjA/sV6VuqiNA7YPaIdQaokA4HWUblDr/WOc1qByUQpWjdp2TR2MC+4Th0zo2D2HNo 4Dc0U479ENO5O3js5LAELz5rk4Ql6kheh3qGFSDj06DJHm7ONXH0OtLZdO3zp+0whdS7hZ9v aKxlOw3NAgB+9QwXBTCCAn0wggHmoAMCAQICFHUTa1jzgGlXdaaiTVkQTZzqdkrxMA0GCSqG SIb3DQEBAgUAMF8xCzAJBgNVBAYTAlVTMRcwFQYDVQQKEw5WZXJpU2lnbiwgSW5jLjE3MDUG A1UECxMuQ2xhc3MgMSBQdWJsaWMgUHJpbWFyeSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAe Fw05NzA2MjQwNzAwMDBaFw05OTA2MjQwNzAwMDBaMGIxETAPBgNVBAcTCEludGVybmV0MRcw FQYDVQQKEw5WZXJpU2lnbiwgSW5jLjE0MDIGA1UECxMrVmVyaVNpZ24gQ2xhc3MgMSBDQSAt IEluZGl2aWR1YWwgU3Vic2NyaWJlcjCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAthSm z03QBQ3YyiPQb6q0KZJjjiz4b5bXLp12SxGxNo1XycP9HMa6/h4IujPKleq+41vNBqi3eR1E Ku1z8rFSg2gQcGSR1z5r+fddnRRDm26XRZiBR9Ety927ctdMP3Gq4kDyVDm8Fu7PfOy62z9s KrMWsYYSna6TNNW41dD3PqkCAwEAAaMzMDEwEQYJYIZIAYb4QgEBBAQDAgEGMA8GA1UdEwQI MAYBAf8CAQEwCwYDVR0PBAQDAgEGMA0GCSqGSIb3DQEBAgUAA4GBAJIMS+m6k83/2uZg/Z5k A2YVL1Y8OExoSkfF86uPJdlmQ3NDFXNEvhRIgVp3DMx66tmxvPKL/xGx3xRQSNxlHQuJ+aFe SFJv7bVr9LgITDjwuYlnKQ/g4Df3puvU9NVCqV39veeefBvnT4UtBKFgLoW46+L67xQFJhUY VW8ToR1xMIICMTCCAZoCBQKkAAABMA0GCSqGSIb3DQEBAgUAMF8xCzAJBgNVBAYTAlVTMRcw FQYDVQQKEw5WZXJpU2lnbiwgSW5jLjE3MDUGA1UECxMuQ2xhc3MgMSBQdWJsaWMgUHJpbWFy eSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw05NjAxMjkwMDAwMDBaFw05OTEyMzEyMzU5 NTlaMF8xCzAJBgNVBAYTAlVTMRcwFQYDVQQKEw5WZXJpU2lnbiwgSW5jLjE3MDUGA1UECxMu Q2xhc3MgMSBQdWJsaWMgUHJpbWFyeSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCBnzANBgkq hkiG9w0BAQEFAAOBjQAwgYkCgYEA5Rm/baNWYS2ZSHH2Z965jeu3noaACpEO+jglr0aIguVz qKCbJF0NH8xlbgyw0FaEGIeaBpsQoXPftFg5a27B9hXVqKg/qhIGjTGsf7A01480Z4gJzRQR 4k5FVmkfeAKA2txHkSm7NsljXMXg1y2He6G3MrB7MLoqLzGq7qNn2tsCAwEAATANBgkqhkiG 9w0BAQIFAAOBgQBSc7qaVdzcP4J9sJCYYiqCTHYAbiU91cIJcFcBDA93Hxih+xxgDqB1O0kh Qf6nXC1MQknT/yjYjOqd/skH4neCUyPeVfPORJP6+ky9yjbzW2aynsjyDF5e1KG0IQkzyjtZ /JLCOPyt2ZYk4C36oyn1M2h4TrS8n2k14qiYlHM7xDGCAZswggGXAgEBMHYwYjERMA8GA1UE BxMISW50ZXJuZXQxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTQwMgYDVQQLEytWZXJpU2ln biBDbGFzcyAxIENBIC0gSW5kaXZpZHVhbCBTdWJzY3JpYmVyAhAOHxbMxzSLVyKqfQxoaBIW MAkGBSsOAwIaBQCgfTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEP Fw05ODA2MjkyMzA0MzdaMB4GCSqGSIb3DQEJDzERMA8wDQYIKoZIhvcNAwICASgwIwYJKoZI hvcNAQkEMRYEFJBBmX/cvOnacp2zkY+ek1eS4U2JMA0GCSqGSIb3DQEBAQUABIGAaFm/iDE/ pmN/+OfFhnAUnhSAZNOxeHCo2ClKLlR+k2iab4iI8KR14SZfphJx11O0v+BN9CwdgQrxx7qX 6cTG1YLwUTFvhGPOyIDnxcPtdOxto9t2CBsB8DISD/E+31VGvhVPwca8fGEOdh60CexrAxrk 8odLDBNNnL4SwVdiy/c= --------------msEA5E84446F7B573A8A14BBD9-- 6-Jul-1998 1:48:59-GMT,3089;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id TAA11099 for ; Sun, 5 Jul 1998 19:48:58 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 05 Jul 1998 20:46:29 EST From: lippmann@cdc9.cdc.informatik.th-darmstadt.de (Jens Lippmann ) Reply-To: LitProg@SHSU.edu, lippmann@cdc9.cdc.informatik.th-darmstadt.de Subject: Re: Pre-Announce and RFC for LP tool Date: 5 Jul 1998 19:37:45 GMT Message-ID: <6nokm9$nv6$1@news.interlog.com> To: LitProg@SHSU.edu Hi there! John wrote: > I am developing a new literate programming tool > (currently called Interscript) that will blow the > socks of everything else. It's currently > programming itself. I need comments. What do YOU > want from a LP system? - must allow code chunking (as Lee said) - should be able to generate PS, PDF or HTML - based on TeX would be nice, but not a must (but: TeX's the best!) - an option to the weaver to enable/suppress pretty printing - allow cross references that are clickable: a) list of identifiers for this file, with crossrefs between def/use pairs b) list of refinements (chunks) c) ability to cite a chunk of this file (i.e. "Look at |@|...") d) ability to import chunk labels of different files and to cite them, i.e. the ability to link stand-alone files e) a 'global' list of identifiers, where the user may select from which files the list is to be generated, and what type of variables it should include (this can be achieved via a user-defined filter applied to the variable names/types) f) a mechanism to cite a web file or single chunks of a web file within a TeX, PDF or HTML document. g) a list of functions, for a single file and for a user-selected list of files h) a list of cited files, suited for a table of contents - the tangler should have an option to enable/suppress indentation - the tangler should have an option to enable/suppress insertion of #line, #file, or similar directives. The idea is to support Java, and to be able to deliver a tangled file as source code, i.e. the compiler should generate errors/warnings for the tangled file and not for the (non-available) web source. - What the hell is Python??? What about working with C ? - InterScript is perhaps not so well-chosen. It is difficult to put the name in association with Literate Programming. What about WebScript or InterWeb? Pooh. I thought of something more, maybe I'll recall it next time. In deed I got embarassed about insufficient LP capabilities so often that I could write a book about it. Good Luck... Jens. __ # Jens Lippmann lippmann@cdc.informatik.tu-darmstadt.de # http://www.informatik.tu-darmstadt.de/TI # # Technische Hochschule Darmstadt http://www.tu-darmstadt.de 6-Jul-1998 14:59:54-GMT,3054;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id IAA25343 for ; Mon, 6 Jul 1998 08:59:53 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 06 Jul 1998 09:55:20 EST From: Felix Gaertner Reply-To: LitProg@SHSU.edu, felix@informatik.th-darmstadt.de Subject: enabling #line for Java (and other languages) and noweb Date: 6 Jul 1998 13:57:01 GMT Message-ID: <6nql3d$pk9$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Hi folks, there have been a few postings recently concering the `#line problem' when working with Java and noweb. The problem is that the compiler references warnings and errors within the tangled code and not within the original noweb file. This is not a problem when working with C, because the -L option of notangle inserts special `#line' directives which the C compiler can use to calculate the correct references in the noweb file. I have a student here who is willing to work on a small tool to solve this problem for languages that don't support #line directives. Here's a first outline of the ``interface'' which an end user sees. I'd like to hear some comments or suggestions on this interface before actual coding takes place, because I want the tool to be useable not only by myself. Main Idea --------- The main idea of the tool (let's call it `noerr') is to pipe compiler output through a program which silently replaces line numbers and file references by the ``correct values'' (with respect to the noweb file). We assume that people use `make' on a Unix-ish system. Here's an example on how to write the Makefile for Java: ------------------------------------------------------------------ LINESPEC = -L"// in line %L %F %N" .nw.java: notangle $(LINESPEC) $*.nw > $*.java .java.class: javac $*.java | noerr $(LINESPEC) ------------------------------------------------------------------- Prerequisites for an environment in which the tool should work: --------------------------------------------------------------- - `make' is used - `piping' is possible - the programming language supports comments - the tool will probably be written in Perl, so we assume Perl is available - the user is willing to make small changes to the Makefiles So, I'd like to start a discussion on the feasibility of this interface before going into the intrinsics of the implementation. Comments are welcome (especially suggestions for an expressive name for the tool are very much appreciated). Cheers Felix -- =========="=================================================== Felix C. Gartner felix@informatik.tu-darmstadt.de Computer Science Department TU Darmstadt, Germany 6-Jul-1998 15:13:00-GMT,3051;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id JAA25858 for ; Mon, 6 Jul 1998 09:12:58 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 06 Jul 1998 10:08:51 EST From: Felix Gaertner Reply-To: LitProg@SHSU.edu, felix@informatik.th-darmstadt.de Subject: enabling #line for Java (and other languages) and noweb Date: 6 Jul 1998 13:52:38 GMT Message-ID: <6nqkr6$phc$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Hi folks, there have been a few postings recently concering the ``#line problem'' when working with Java and noweb. The problem is that the compiler references warnings and errors within the tangled code and not within the original noweb file. This is not a problem when working with C, because the -L option of notangle inserts special #line directives which the C compiler can use to calculate the correct references in the noweb file. I have a student here who is willing to work on a small tool to solve this problem for languages that don't support #line directives. Here's a first outline of the ``interface'' which an end user sees. I'd like to hear some comments or suggestions on this interface before actual coding takes place, because I want the tool to be useable not only by myself. Main Idea --------- The main idea of the tool (let's call it `noerr') is to pipe compiler output through a program which silently replaces line numbers and file references by the ``correct values'' (with respect to the noweb file). We assume that people use `make' on a Unix-ish system. Here's an example on how to write the Makefile for Java: ------------------------------------------------------------------ LINESPEC = -L"// in line %L %F %N" .nw.java: notangle $(LINESPEC) $*.nw > $*.java .java.class: javac $*.java | noerr $(LINESPEC) ------------------------------------------------------------------- Prerequisites for an environment in which the tool should work: --------------------------------------------------------------- - `make' is used - `piping' is possible - the programming language supports comments - the tool will probably be written in Perl, so we assume Perl is available - the user is willing to make small changes to the Makefiles So, I'd like to start a discussion on the feasibility of this interface before going into the intrinsics of the implementation. Comments are welcome (especially suggestions for an expressive name for the tool are very much appreciated). Cheers Felix -- =========="=================================================== Felix C. Gartner felix@informatik.tu-darmstadt.de Computer Science Department TU Darmstadt, Germany 6-Jul-1998 23:33:21-GMT,1266;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id RAA08621 for ; Mon, 6 Jul 1998 17:33:20 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 06 Jul 1998 18:31:06 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: enabling #line for Java (and other languages) and noweb Date: 6 Jul 1998 18:38:54 GMT Message-ID: <6nr5ju$4sd$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6nqkr6$phc$1@murdoch.acc.Virginia.EDU>, Felix Gaertner wrote: >The main idea of the tool (let's call it `noerr') is to pipe compiler >output through a program which silently replaces line numbers and file >references by the ``correct values'' (with respect to the noweb file). >.nw.java: > notangle $(LINESPEC) $*.nw > $*.java > >.java.class: > javac $*.java | noerr $(LINESPEC) I (predictably) think this is a great idea. Where do you specify the format of javac's error messages? Norman 7-Jul-1998 7:33:34-GMT,1868;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id BAA17639 for ; Tue, 7 Jul 1998 01:33:33 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Jul 1998 02:28:12 EST From: Felix Gaertner Reply-To: LitProg@SHSU.edu, felix@informatik.th-darmstadt.de Subject: Re: enabling #line for Java (and other languages) and noweb Date: 7 Jul 1998 07:00:41 GMT Message-ID: <6nsh2p$nb9$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Norman Ramsey wrote: > > In article <6nqkr6$phc$1@murdoch.acc.Virginia.EDU>, > Felix Gaertner wrote: > >The main idea of the tool (let's call it `noerr') is to pipe compiler > >output through a program which silently replaces line numbers and file > >references by the ``correct values'' (with respect to the noweb file). > > >.nw.java: > > notangle $(LINESPEC) $*.nw > $*.java > > > >.java.class: > > javac $*.java | noerr $(LINESPEC) > > I (predictably) think this is a great idea. Where do you specify the > format of javac's error messages? > > Norman We are thinking of taking the regular expressions from the compile mode of emacs to match compiler error messages. They seem to do a good job with most (C) compilers and we are giving it a try with others (java, etc.). Felix -- =========="=================================================== Felix C. Gartner felix@informatik.tu-darmstadt.de Computer Science Department TU Darmstadt, Germany 7-Jul-1998 12:13:15-GMT,64886;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id GAA22474 for ; Tue, 7 Jul 1998 06:13:13 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Jul 1998 06:46:14 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 6 Jul 1998 23:43:56 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.edu Archive-name: literate-programming-faq Last-modified: 1997/08/15 Version: 1.1.18 The Literate Programming FAQ David B. Thompson 15 August 1997 This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. ______________________________________________________________________ Table of Contents: 1. Welcome 1.1. Disclaimer 1.2. Copyright 1.3. What's New? 2. Introduction or 3. How do I get the FAQ? 3.1. Literate Programming FAQ 3.2. FWEB FAQ 4. Is there a newsgroup? 5. What internet nodes are of interest to literate programmers? 6. What is Literate Programming? 7. How do I begin literate programming? 8. What literate programming tools are available? 8.1. APLWEB 8.2. AWEB 8.3. CLiP 8.4. CWEB 8.5. CWEBx3.0 8.6. mCWEB 8.7. FunnelWeb 8.8. FunnelWeb 3.0AC 8.9. FWEB 8.10. IMPACT 8.11. lit2x 8.12. Literate Programmer's Workshop (LPW) 8.13. MapleWEB 8.14. MWEB (Schrod/Detig) 8.15. MWEB (Sewell) 8.16. noweb 8.17. nuweb 8.18. ProTeX 8.19. RWEB 8.20. SchemeWEB 8.21. SpideryWEB 8.22. WEB 8.23. WinWordWEB 9. Are there other tools I should know about? 9.1. C2LaTeX 9.2. c2cweb 9.3. c2man 9.4. cnoweb 9.5. Fold2Web 9.6. Funnelweb Mode 9.7. noweb.el 9.8. nuweb.el 9.9. TIE 9.10. Web mode 10. What other resources are available? 10.1. World Wide Web 10.2. TeX Resources 11. Are there any code examples? 12. Bibliographies 13. How to anonymously ftp 14. Acknowledgements 15. End notes ______________________________________________________________________ 1. Welcome Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 1.1. Disclaimer Disclaimer: ``This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk.'' 1.2. Copyright Copyright 1993-1997 by David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: 1.3. What's New? o My email address has changed (once again). o Newsgroup is moderated. o Updated fweb entry. o Updated noweb entry. o Added mCWEB entry. o Updated c2cweb entry. o Updated nuweb.el entry. o Updated cLiP entry. o Updated Lee W's examples (from bart). o Last, but not least, new formatting of the FAQ. Many thanks go to Andrew Johnson for helping make this happen. 2. Introduction or ``What's this all about?'' This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson Comments and constructive criticisms are welcome. Direct flames to /dev/null (or nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is not complete, and probably will never be complete. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. 3. How do I get the FAQ? 3.1. Literate Programming FAQ You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled ``Internet Nodes of Interest to Literate Programmers''.) 3.2. FWEB FAQ David Coker maintains the FWEB FAQ. The current version number is 1.30a. It can be retrieved in the same way as this FAQ. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de 131.169.10.115 in directory /pub/faq/web/fweb/. It is also available from the literate programming archive in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). 4. Is there a newsgroup? One of the most important resources is the literate programming newsgroup, comp.programming.literate. Because of the amount of spamming and unrelated the posts, the newsgroup is now moderated. Posts to the newsgroup are now routed through litprog- mod@cs.virginia.edu. If your news reader does not post through this address, then you will be unable to post messages to the newgroup. You can read this newsgroup using your standard reader. 5. What internet nodes are of interest to literate programmers? The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. Participating hosts in the Comprehensive TeX Archive Network are: ftp.dante.de (Deutschland) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node sun.dante.de -- e-mail via ftpmail@dante.de -- Administrator: ftp.tex.ac.uk (England) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node gopher.tex.ac.uk -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive -- World Wide Web access on www.tex.ac.uk -- Administrator: The site ftp.shsu.edu used to be the American CTAN site. Apparently, that site has fallen into disrepair and should not be considered a primary source for either TeX related or literate programming related material. For the record, the address is: ftp.shsu.edu (Texas, USA) -- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive) -- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive -- e-mail via ftpmail@ftp.SHSU.edu -- World Wide Web access on www.SHSU.edu -- Administrator: A list of CTAN archive sites and their mirrors can be found on: ftp.dante.de:/tex-archive/CTAN.sites I presume that the other CTAN sites mirror this file, but have not checked. As of my last check (September 1994), it contains: "In order to reduce network load, it is recommended that you use the Comprehensive TeX Archive Network (CTAN) host which is located in the closest network proximity to your site." Known partial mirrors of the CTAN reside on (alphabetically): dongpo.math.ncu.edu.tw (Taiwan) /tex-archive ftp.adfa.oz.au (Australia) /pub/tex/ctan ftp.muni.cz (The Czech Republic) /pub/tex/CTAN ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive ftp.uu.net (Virginia, USA) /pub/text-processing/TeX nic.switch.ch (Switzerland) /mirror/tex Known mirrors of the CTAN reside on (alphabetically): ftp.center.osaka-u.ac.jp (Japan) /CTAN ftp.ccu.edu.tw (Taiwan) /pub/tex ftp.cs.rmit.edu.au (Australia) /tex-archive ftp.duke.edu (North Carolina, USA) /tex-archive ftp.germany.eu.net (Deutschland) /pub/packages/TeX ftp.gwdg.de (Deutschland) /pub/dante ftp.jussieu.fr (France) /pub4/TeX/CTAN ftp.loria.fr (France) /pub/unix/tex/ctan ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de ftp.uni-bielefeld.de (Deutschland) /pub/tex ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex) ftpserver.nus.sg (Singapore) /pub/zi/TeX src.doc.ic.ac.uk (England) /packages/tex/uk-tex sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX wuarchive.wustl.edu (Missouri, USA) /packages/TeX Other nodes and directories of interest include: Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ 6. What is Literate Programming? Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system pro- grammer, who wants to provide the best possible documenta- tion of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To docu- ment such a program we want to explain each individual part of the web and how it relates to its neighbours. The typo- graphic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combin- ing the two, we can develop a style of programming that max- imizes our ability to perceive the structure of a complex piece of software, and at the same time the documented pro- grams can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why. Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM ref. 1 plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References 1 Paul W. Oman and Curtus Cook. ``Typographical style is more than cosmetic.'' CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called ``informal rigour'', i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 Another author (Norman Ramsey) wrote me and asked that his opinions be included in the FAQ. What follows are Norman's comments verbatim. I see it's time for the ``how is literate programming dif- ferent from verbose commenting'' question. Perhaps David Thompson will get this into the FAQ. Alert! What follows are my opinions. In no way do I claim to speak for the (fractious) literate-programming community. How is literate programming different from verbose commenting? There are three distinguishing characteristics. In order of importance, they are: o flexible order of elaboration o automatic support for browsing o typeset documentation, especially diagrams and mathematics Flexible order of elaboration means being able to divide your source program into chunks and write the chunks in any order, independent of the order required by the compiler. In principle, you can choose the order best suited to explaining what you are doing. More subtly, this discipline encourages the author of a literate program to take the time to consider each fragment of the program in its proper sphere, e.g., not to rush past the error checking to get to the ``good parts.'' In its time and season, each part of the program is a good part. (This is the party line; your mileage may vary.) I find the reordering most useful for encapsulating tasks like input validation, error checking, and printing output fit for humans --- all tasks that tend to obscure ``real work'' when left inline. Reordering is less important when using languages like Modula-3, which has exceptions and permits declarations in any order, than when using languages like C, which has no exceptions and requires declaration before use. Automatic support for browsing means getting a table of contents, index, and cross-reference of your program. Cross-reference might be printed, so that you could consult an index to look up the definition of an identifier `foo'. With good tools, you might get a printed mini-index on every page if you wanted. Or if you can use a hypertext technology, cross-reference might be as simple as clicking on an identifier to reach its definition. Indexing is typically done automatically or `semi- automatically', the latter meaning that identifier definitions are marked by hand. Diligently done semi- automatic indexes seem to be best, because the author can mark only the identifiers he or she considers important, but automatic indexing can be almost as good and requires no work. Some tools allow a mix of the two strategies. Some people have applied literate-programming tools to large batches of legacy code just to get the table of contents, index, and cross-reference. I don't use diagrams and mathematics very often, but I wouldn't want to have to live without them. I have worked on one or two projects where the ability to use mathematical formulae to document the program was indispensible. I also wouldn't like to explain some of my concurrent programs without diagrams. Actually I write almost all of my literate programs using only sections headers, lists, and the occasional table. >Wouldn't it be easier to do one's literate programming using >a wysiwyg word processor (e.g. Word for Windows) and >indicate what is source code by putting it in a different >font? The data formats used in wysiwyg products are proprietary, and they tend to be documented badly if at all. They are subject to change at the whim of the manufacturer. (I'll go out on a limb and say there are no significant wysiwyg tools in the public domain. I hope the Andrew people will forgive me.) These conditions make it nearly impossible to write tools, especially tools that provide automatic indexing and cross-reference support. The CLiP people have a partial solution that works for tools that can export text --- they plant tags and delimiters throughout the document that enable the reordering transformation (``tangling''). People use TeX, roff, and HTML because free implementations of these tools are widely available on a variety of platforms. TeX and HTML are well documented, and TeX and roff are stable. TeX is the most portable. I think I have just answered the FAQ ``how come all these tools use TeX, anyway?'' :-) Norman Ramsey 7. How do I begin literate programming? A recommended book is D.E. Knuth's collection of articles (1992) Literate Programming. Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) Weaving a Program: Literate Programming in WEB. Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. 8. What literate programming tools are available? A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) 8.1. APLWEB Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. 8.2. AWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. 8.3. CLiP Developer: E.W. van Ammers and M.R. Kramer Versions: 2.0 and 2.4b (DOS only) Platform: Vax/VMS, Unix, DOS Languages: Any programming language Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, WinWord, Ami Pro, Word Pro, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos DOS sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b) sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS sun01.info.wau.nl:/CLIP/unix Unix CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicit commands to perform the extraction process. Rather it recognizes pseudostatements written as comments in the programming language in question. CLiP distinguishes pseudostatements from ordinary comments because the former comply with a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well. Some hypertext examples are at ftp://sun01.info.wau.nl/clip/html/queens.htm ftp://sun01.info.wau.nl/clip/html/pal1.htm Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentation my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segments. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail to Eric.vanAmmers@user.info.wau.nl 8.4. CWEB Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu 8.5. CWEBx3.0 Developer: Marc van Leeuwen Version: Unknown Hardware: Any system using ASCII code Languages: ANSI C Formatter: Plain TeX Availability: Anonymous ftp from: ftp.cwi.nl/pub/cweb Readme: Bundled with above Brief description: A modified implementation of CWEB, with some extensions. Provides a mode for full compatibility with Levy/Knuth CWEB. The most significant extras are: - Typedef declarations affect formatting througout source file - Include files are scanned for typedef definitions - Flexible selection of layout style - Possibility to refer to sections using symbolic labels - CTANGLE detects unbalanced braces and parentheses - CWEAVE can be made to report syntax errors more easily - Some additional mechanisms to avoid formatting problems - New and modular set of grammar rules, based on ANSI C syntax - Possibility to suppress #line directives - A new manual Support: bugs and remarks to M.van.Leeuwen@cwi.nl 8.6. mCWEB Developer: Markus Oellinger Version: 1.0 Hardware: Unix Languages: C/C++ Formatter: plainTeX Availability: anonymous ftp from ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz Readme: at same location Description: This is mCWEB 1.0, a descendant of the CWEB system of structured documentation by Donald E. Knuth and Silvio Levy. It adds some features that are indispensable when working in a team. mCWEB regards a project of a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface documentation is now also part of mCWEB. It is extracted into a second TeX file. This makes it possible to define well known interfaces between the individual parts of a project that will be implemented by different persons. In addition, mCWEB parses C header files to find out about all the datatypes defined there. mCWEB comes with a full completely rewritten user manual and is compatible with CWEB. Support: Institute of Software Technology moell@ist.tu-graz.ac.at 8.7. FunnelWeb Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. 8.8. FunnelWeb 3.0AC Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au) from FunnelWeb v3.0 by Ross N. Williams (ross@guest.adelaide.edu.au) Version: 3.0AC Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2. Languages: No restrictions. Formatter: Tex, LaTeX, or HTML. Availability: Anonymous ftp from ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz Readme: With bundle above; for FunnelWeb manual see WWW page http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html Description: FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry for FunnelWeb). FunnelWeb is designed to be typesetter independent, though FunnelWeb v3.0 only supports (La)TeX as the typesetter. FunnelWeb 3.0AC also supports HTML, and creates appropriate hypertext links within the document among the code sections. FunnelWeb 3.0AC also supports automatic and manual insertion of line directives, so that compiler errors can be flagged back to the original FunnelWeb source file. FunnelWeb 3.0AC is completely compatible with FunnelWeb v3.0 sources (with one minor exception; see the file README.ABC which comes with the FunnelWeb 3.0AC distribution). Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject to the time constraints imposed by his thesis. 8.9. FWEB Developer: John A. Krommes Version: 1.53 (1.60-beta for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: LaTeX. Plain TeX may work, but is no longer supported. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu 8.10. IMPACT Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. 8.11. lit2x Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown 8.12. Literate Programmer's Workshop (LPW) Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. 8.13. MapleWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown 8.14. MWEB (Schrod/Detig) Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.15. MWEB (Sewell) Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.16. noweb Developer: Norman Ramsey Version: 2.8 Hardware: Unix and DOS platforms (DOS binaries available for v2.7). Languages: All programming languages, singly or in combination. Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc Formatter: Plain TeX, LaTeX, and HTML formatters. Will convert LaTeX to HTML automatically. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent Last recourse, use ftp.cs.virginia.edu:pub/nr Readme: With bundle above, or see the noweb home page: http://www.cs.virginia.edu/~nr/noweb Those without ftp access can consult ``Literate Programming Simplified,'' IEEE Software, September 1994, pp97-105. Description: noweb is designed to meet the needs of literate programmers while retaining the simplest possible input format. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 3 pages; an additional page explains how to customize its LaTeX output. noweb works ``out of the box'' with any programming language, and supports TeX, latex, and HTML back ends. A back end to support full hypertext or indexing takes about 250 lines; a simpler one can be written in 40 lines of awk. The primary sacrifice relative to WEB is that code is not prettyprinted. noweb supports indexing and identifier cross-reference, including hypertext ``hot links.'' noweb includes a simple, efficient LaTeX-to-HTML converter, so you can use hypertext browsers on your legacy documents. noweb can also process nuweb programs, so you can use noweb to convert a standard nuweb program to HTML with one command. Support: email to the author 8.17. nuweb Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu 8.18. ProTeX Developer: Eitan Gurari Version: ProTeX 1.1, AlProTeX 1.4 Hardware: Any platform with (La)TeX Languages: Any language Formatter: TeX or LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: With bundle above Description: + Easy to use + Extensible + Language independent + Multiple output files + Fast (single compilation provides output and dvi files) + No installation is needed besides copying the files (written in TeX) Introduction of main features and examples in pub/tex/osu/gurari/LitProg Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and Literate Programming", McGraw-Hill, 1994 Support: gurari@cis.ohio-state.edu 8.19. RWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown 8.20. SchemeWEB Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. 8.21. SpideryWEB Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. 8.22. WEB Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. 8.23. WinWordWEB Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. 9. Are there other tools I should know about? First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. 9.1. C2LaTeX Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. 9.2. c2cweb Developer: Werner Lemberg Version: 1.5 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg 9.3. c2man language: C, nroff, texinfo, latex, html package: c2man version: 2.0 patchlevel 33 parts: documentation generator (C -> nroff -man, -> texinfo, ->latex, -> html) author: Graham Stoney location: ftp from any comp.sources.misc archive, in volume42 (the version in the comp.sources.reviewed archive is obsolete) ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from archie.au N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from ftp.wustl.edu Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* from ftp.irisa.fr Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* from ftp.iij.ad.jp Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se description: c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. conformance: supports both K&R and ISO/ANSI C coding styles features: + generates output in nroff -man, TeXinfo, LaTeX or HTML format + handles comments as part of the language grammar + automagically documents enum parameter & return values + handles C (/* */) and C++ (//) style comments - doesn't handle C++ grammar (yet) requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX. ports: Unix, OS/2, MSDOS, VMS. portability: very high for unix, via Configure status: actively developed; contributions by users are encouraged. discussion: via a mailing list: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au help: from the author and other users on the mailing list: c2man@research.canon.oz.au announcements: patches appear first in comp.sources.bugs, and then in comp.sources.misc. updated: 1994/10/07 9.4. cnoweb Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. 9.5. Fold2Web Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de 9.6. Funnelweb Mode Developer: Daniel Simmons Version: Unknown Availability: http://www.miscrit.be/~ddw Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown 9.7. noweb.el Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk 9.8. nuweb.el Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@acm.org 9.9. TIE Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown 9.10. Web mode Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown 10. What other resources are available? 10.1. World Wide Web An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html or use a WWW browser and access the URL ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to rtfm.mit.edu and retrieve the official Usenet resource file /pub/usenet/news.answers/www/resources/literate-programming 10.2. TeX Resources Another resource of interest to literate programmers is the comp.text.tex newsgroup. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this resource. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. 11. Are there any code examples? Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au 129.127.40.3 as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: ftp://samson.kean.edu/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is writ- ten in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb 12. Bibliographies Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu 128.110.198.2 in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says sev- eral times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. 13. How to anonymously ftp Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu 18.181.0.24, under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. 14. Acknowledgements This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. 15. End notes This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. 8-Jul-1998 3:37:29-GMT,7206;000000000001 Received: from relay.urz.uni-heidelberg.de (relay.urz.uni-heidelberg.de [129.206.119.201]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with ESMTP id VAA13353 for ; Tue, 7 Jul 1998 21:37:27 -0600 (MDT) Received: from relay (relay.urz.uni-heidelberg.de [129.206.119.201]) by relay.urz.uni-heidelberg.de (8.8.8/8.8.8) with SMTP id FAA29185; Wed, 8 Jul 1998 05:19:41 +0200 (MET DST) Received: from RELAY.URZ.UNI-HEIDELBERG.DE by RELAY.URZ.UNI-HEIDELBERG.DE (LISTSERV-TCP/IP release 1.8b) with spool id 381976 for LATEX-L@RELAY.URZ.UNI-HEIDELBERG.DE; Wed, 8 Jul 1998 05:19:20 +0200 Received: from ricetub.anu.edu.au (richard@ricetub.anu.edu.au [150.203.166.61]) by relay.urz.uni-heidelberg.de (8.8.8/8.8.8) with ESMTP id FAA29168 for ; Wed, 8 Jul 1998 05:19:15 +0200 (MET DST) Received: (from richard@localhost) by ricetub.anu.edu.au (8.8.2/8.8.8) id NAA27504; Wed, 8 Jul 1998 13:19:07 +1000 (EST) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit References: <199807020724.RAA19706@ricetub.anu.edu.au> <199807021940.VAA01123@frank.zdv.uni-mainz.de> <199807060810.SAA24960@ricetub.anu.edu.au> <199807062020.WAA19898@frank.zdv.uni-mainz.de> <199807070755.RAA26108@ricetub.anu.edu.au> <199807072051.WAA04726@frank.zdv.uni-mainz.de> X-Mailer: VM 6.29 under Emacs 19.34.1 Message-ID: <199807080319.NAA27504@ricetub.anu.edu.au> Date: Wed, 8 Jul 1998 13:19:07 +1000 Reply-To: Mailing list for the LaTeX3 project Sender: Mailing list for the LaTeX3 project From: Richard Walker Subject: Re: First experience with xr under L3PL To: Multiple recipients of list LATEX-L In-Reply-To: <199807072051.WAA04726@frank.zdv.uni-mainz.de> Frank Mittelbach writes: > > I'd like to suggest that the `check' option used in > > the dtx files be changed into a package option, say `checkdef' (you > > can think of a better name). > > good idea, anybody willing to do this? Hooray - you like one of my ideas :-) OK, unless someone else is realy keen on getting some experience, I'll have a go. > . . . actually i could have also produced > essentially the same algorithm by not using the stack commands but > instead using those other sequence commands. True enough, I just wasn't sure whether you chose to implement it differently or whether it just turned out that way. > > . . . it might well serve as a deterrent to those who > > come to LaTeX3 as beginners. > > i think i disagree here. what i meant is that you do need to learn > some layer whether it'll be current latex internal commands (by looking > at the latex source or other packages) or be something like the L3PL > language is not much different (except for those who already mastered > most of the mess of the current latex) The difference will be that it's `official' and documented. Let's hope the difference counts! > > If you are happy to release out-of-date and inconsistent documentation > > for incomplete packages then in fairness to us - your guinea pigs - > > _everything_ must be up for grabs. > > i already said that this was a remark concerning latex2e --- and if > people are willing to help updating the documentation of the .dtx > files for 2e we are too willing to accept such help!!! just drop us a > note and we provide you with the file of your choice (latest version > -- sometimes fixes for the next release are already in) lock it in rcs > and put the updated documentation with your name on back in. certainly > we can make these sources better and it is still worth doing even > though we are talking about a sort of paradigm change here. A part of me really wants to do this. Another part of me says `why bother?', when, for example, my energy would be better spent adding the functionality of \@for and \@tfor to l3seq than to documenting ltcntrl. I think from what you have said so far that this is your perspective too! > we don't have the intention of closing doors at this stage. but at the > other hand we believe that there is not much gained if X suggests to > change the syntax slightly in this direction, then we have a long > discussion on whether or not this is how other people see this, then Y > suggest some other twist, ... and all of this gets implemented > straight away (by us) and changed over and over again instead of > providing new functionality within the framework as is and change it > completely on the surface later. I accept this completely. I agree that the onus is on me (and others) to `prove' me (us) `right', and that any change in the syntax has to be done by me (us). > i also have nothing whatsoever against the idea that somebody sits > down and takes apart all the packages we have put together and does > some global replace and produces a version more to his or her liking. > we can certainly put such a version on CTAN as well. That is a very positive statement - thank you. As I said, I don't want to change things on a whim, but I appreciate your openness in allowing me (and others) to put forward other ideas for consideration. > but what i'm not going to do (me personally) is to do that type of > work just because some people think that _ are bad or the colon should > be a . or Modula2 type of syntax is better. that would drag on forever > without anything gained because there are probably as many opinions on > this subject as we had emails on it. if somebody wants to, please do > so, but don't ask us to do it for you now. Well, I wasn't asking you to do that. I will indeed do it myself. I can use Emacs's regular expression search and replace as well as the next person . . . . > let me also say that i *DON'T* like the language as it is on many > special points (not the last are the many _) but just like here on the > list with perhaps 4-6 people commenting on the look of it we had > internally also very different opinions what looks best or works > best. and at one point we decided to stop and just pick one to > actually get functionality provided. If you have records of the internal discussions I'd like to see them (if you don't mind). I'm sure some of your frustrations are because you have to repeat arguments that have already been settled. > you also need a higher-level interface (or set of interfaces) which > are also official to avoid all the situations that people because of > nothing being put into such a status hooked into any layer with > disastrous effects when something was reprogrammed (or just fixed or > optimized :-) I think we all know this from experience! The hard problem will be deciding what is important enough to become `official'. An interesting comparison is with MacOS X and `Carbon'. The plan is to cut the Mac's programming interface from about 8000 calls down to a core of about 2000 calls. `Less is more', so they say. 8-Jul-1998 6:49:31-GMT,1318;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id AAA16866 for ; Wed, 8 Jul 1998 00:49:30 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Jul 1998 01:35:47 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Literate Programming web ring? Date: 8 Jul 1998 02:17:29 GMT Message-ID: <6nukrp$oqc$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I did a search today and discovered that there is no `web ring' devoted to literate programming. This is in omission that would be worth correcting---there are lots of web pages out there, and we could get some good visibility, especially by linking the FAQ and some popular tools. Anybody can start a new web ring, but the catch is that there is an administrative burden that is not trivial. Anyway, if somebody feels like serving the community in this way, that would be super! You can find instructions at www.webring.org, or I'll be happy to help anyone get started... Norman -- Norman Ramsey http://www.cs.virginia.edu/~nr 14-Jul-1998 1:31:27-GMT,2731;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id TAA05442 for ; Mon, 13 Jul 1998 19:31:26 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 13 Jul 1998 20:27:39 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Description of LP for a legal case Date: 12 Jul 1998 23:21:53 GMT Message-ID: <6obgeh$i44$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 9 Jul 1998, Steve Furlong wrote: > Fair warning to international readers: this post applies mainly to > an American audience. Though in a worst-case scenario I suppose it > may work its way into international law. > > And another fair warning: this post will work up the 'fire in the > belly' mainly to supporters of strong encryption. But it does have > the potential to increase LP's visibility. > > > Some of you may have heard about the result of Junger v. Daley, a > legal case involving the treatment of source code for cryptographic > software as a munition subject to export restriction. In ruling that > source code is not protected by the First Amendment, Judge Gwin of the > US District Court of the Northern District of Ohio found that source > code is ``inherently functional'' and therefore isn't speech. He seems > to be confusing source and object code, but this is what he wrote. At > least I think that's an accurate summary; wading through his tortured > reasoning is more than my poor little engineer's brain can handle. I've heard about this case, but I was under the impression that it had been reversed on appeal (or is this the next level appeal?). I've been mistaken before (and will be again), but I agree with Steve about the uninformed court opinions, particularly where encryption is involved. I also agree that LP, where the source is unquestionably in a form protected by the First Amendment, is an interesting way to finesse the problem. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | "Begin at the middle...then you're not so Computer Science Department | far from either the beginning or the Kean University | ending." Union, NJ 07083 | | -- Erle Stanley Gardner leew@samson.kean.edu | "The Case of the Fugitive Nurse" (1954) ------------------------------------------------------------------------ 14-Jul-1998 14:49:33-GMT,3312;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id IAA20276 for ; Tue, 14 Jul 1998 08:49:31 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from mailgate2.boeing.com by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 14 Jul 1998 09:40:24 EST Received: from mercury.boeing.com ([130.42.138.11]) by mailgate2.boeing.com (8.8.5/8.8.5) with SMTP id HAA19295 for ; Tue, 14 Jul 1998 07:40:19 -0700 (PDT) Received: from hsvaic.hv.boeing.com by mercury.boeing.com; Tue, 14 Jul 98 07:40:19 -0700 Received: by hsvaic.hv.boeing.com (5.x/SMI-SVR4.hsvaic95.2) id AA02323; Tue, 14 Jul 1998 09:40:11 -0500 Date: Tue, 14 Jul 1998 09:40:10 -0500 (CDT) From: Sarah Green Reply-To: LitProg@SHSU.edu, greens@hsvaic.hv.boeing.com To: LitProg@SHSU.edu, leew@SAMSON.KEAN.EDU Subject: Re: Description of LP for a legal case Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On 12 Jul 1998, Lee Wittenberg wrote: > On 9 Jul 1998, Steve Furlong wrote: > > > Fair warning to international readers: this post applies mainly to > > an American audience. Though in a worst-case scenario I suppose it > > may work its way into international law. > > > > And another fair warning: this post will work up the 'fire in the > > belly' mainly to supporters of strong encryption. But it does have > > the potential to increase LP's visibility. > > > > > > Some of you may have heard about the result of Junger v. Daley, a > > legal case involving the treatment of source code for cryptographic > > software as a munition subject to export restriction. In ruling that > > source code is not protected by the First Amendment, Judge Gwin of the > > US District Court of the Northern District of Ohio found that source > > code is ``inherently functional'' and therefore isn't speech. He seems > > to be confusing source and object code, but this is what he wrote. At > > least I think that's an accurate summary; wading through his tortured > > reasoning is more than my poor little engineer's brain can handle. > > I've heard about this case, but I was under the impression that it had > been reversed on appeal (or is this the next level appeal?). I've been > mistaken before (and will be again), but I agree with Steve about the > uninformed court opinions, particularly where encryption is involved. > I also agree that LP, where the source is unquestionably in a form > protected by the First Amendment, is an interesting way to finesse the > problem. > There are a total of three cases challenging this issue- crypto. One in favor, this one against & I haven't heard the results of the third. There is a website that discusses/tracks all three: http://www.eff.org/goldkey.html about 2/3 thru file. YMMV Sarah. ----- +----------Sarah L. Green----------+ | Boeing Space Transportation Div | | Information Systems - Hsv, AL | +-----sarah.l.green@boeing.com-----+ 15-Jul-1998 2:46:03-GMT,998;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id UAA07696 for ; Tue, 14 Jul 1998 20:46:01 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 14 Jul 1998 21:42:34 EST From: ptjm@interlog.com (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@interlog.com Subject: Re: Web for Perl? Date: 15 Jul 1998 02:22:53 GMT Message-ID: <6oh3pt$mvf$1@news.interlog.com> To: LitProg@SHSU.edu In article , Baxter C wrote: % Is there a Web implimentation for Perl? Look at noweb or nuweb. You could also check for other answers from comp.programming.literate, where I've sent follow-ups. -- Patrick TJ McPhee East York Canada ptjm@interlog.com 16-Jul-1998 15:10:38-GMT,6327;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id JAA24232 for ; Thu, 16 Jul 1998 09:10:31 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 16 Jul 1998 10:01:32 EST From: my_public_email@yahoo.com Reply-To: LitProg@SHSU.edu, my_public_email@yahoo.com Subject: Re: Description of LP for a legal case Date: 14 Jul 1998 18:50:28 GMT Message-ID: <6og99k$q4g$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Lee Wittenberg wrote: > On 9 Jul 1998, Steve Furlong wrote: > > > Fair warning to international readers: this post applies mainly to > > an American audience. Though in a worst-case scenario I suppose it > > may work its way into international law. > > > > And another fair warning: this post will work up the 'fire in the > > belly' mainly to supporters of strong encryption. But it does have > > the potential to increase LP's visibility. > > > > > > Some of you may have heard about the result of Junger v. Daley, a > > legal case involving the treatment of source code for cryptographic > > software as a munition subject to export restriction. In ruling that > > source code is not protected by the First Amendment, Judge Gwin of the > > US District Court of the Northern District of Ohio found that source > > code is ``inherently functional'' and therefore isn't speech. He seems > > to be confusing source and object code, but this is what he wrote. At > > least I think that's an accurate summary; wading through his tortured > > reasoning is more than my poor little engineer's brain can handle. > > I've heard about this case, but I was under the impression that it had > been reversed on appeal (or is this the next level appeal?). I've been > mistaken before (and will be again), but I agree with Steve about the > uninformed court opinions, particularly where encryption is involved. > I also agree that LP, where the source is unquestionably in a form > protected by the First Amendment, is an interesting way to finesse the > problem. > Caveats: I am neither a legal expert or a LP expert. However, I did read the judgement, because I was curious. What I found was that the distinction between object and source code is, indeed, addressed. However, it is not considered important. Therefore, I'm not sure that the LP spin would have any legal import. All the indented stuff are direct quotes from the document (whose URL I've lost, unfortunately). Basically, this judgement makes the following arguable assertions about the distinction between object and source code: Source code is a series of instructions to a computer in programming languages such as BASIC, PERL, or FORTRAN. Object code is the same set of instructions translated into binary digits (1's and 0's). Thus, source code and object code are essentially interchangeable. Encryption software posted on the Internet or on computer diskette can be converted from source code into workable object code with a single keystroke. When in electronic form, encryption source code is a functional device that directs a computer to perform specified tasks. Given this stand, does the concept of LP add anything new? They've already collapsed the distinction between the two. *** (That was the extent of the LP-related content of this post.) *** Although these statements are literally false, they aren't the complete basis for why publishing source code on the internet does not carry first amendment protection. For instance, you can publish the source code on paper without the restrictions. The restrictions only apply to internet publication, because they consider internet publication of encryption source code to be identical with exporting an encryption machine. Literally, of course, this is ridiculous, but isn't it also ridiculous to assert that there isn't any difference between internet publication and regular publication? To make an analogy with controlled substances, the government schedules precursors for controlled substances, just becuase there are so few steps to take in order to convert the precursors to the actual substances. Anyway, here are the key arguments about why the distribution of souce code does not carry first amendment weight. Certain software is inherently expressive. Such expressive software contains an "exposition of ideas," Chaplinsky v. State of New Hampshire, 315 U.S. 568, 572 (1942). Nevertheless, merely because conduct is occasionally expressive, does not necessarily extend First Amendment protection to it. As the Supreme Court has observed, "[i]t is possible to find some kernel of expression in almost every activity--for example, walking down the street or meeting one's friends at the shopping mall--but such a kernel is not sufficient to bring the activity within the protection of the First Amendment." City of Dallas v. Stanglin, 490 U.S. 19, 25 (1989). Applying this standard, it is evident that exporting encryption source code is not sufficiently communicative. ... Because the expressive elements of encryption source code are neither "unmistakable" nor "overwhelmingly apparent," its export is not protected conduct under the First Amendment. There are other facets to the case, such as whether the restrictions are content based. The Export Regulations are not content based, however, because the regulations burden encryption software without reference to any views it may express. The regulatory distinction between encryption software and other types of software does not turn on the content of ideas. Instead, it turns on the ability of encryption software to actually do the function of encrypting data. David Alt bird@alum.mit.edu -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -----== Posted via Deja News, The Leader in Internet Discussion ==----- http://www.dejanews.com/rg_mkgrp.xp Create Your Own Free Member Forum 19-Jul-1998 1:39:41-GMT,748;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id TAA02931 for ; Sat, 18 Jul 1998 19:39:40 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 18 Jul 1998 20:25:48 EST From: "Howie" Reply-To: LitProg@SHSU.edu, howie@4howiev.com Subject: Codenaked Programming Resources Date: Sat, 18 Jul 1998 19:19:53 -0600 Message-ID: <#EO4NOrs9GA.113@upnetnews05> To: LitProg@SHSU.edu http://www.codenaked.com has links to lots of programming resources... 20-Jul-1998 8:14:34-GMT,6645;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id CAA02825 for ; Mon, 20 Jul 1998 02:14:33 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Jul 1998 03:11:26 EST From: skaller@maxtal.com.au (John (Max) Skaller) Subject: ANN: pre-release Interscript 1.0a1 Date: 20 Jul 1998 07:54:14 GMT Message-ID: <6out36$8ae$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, skaller@maxtal.com.au To: LitProg@SHSU.edu 1. Maxtal Software Resource --------------------------- I'm pleased to announce my 'birthday present' to the programming community, the first release of Maxtal Interscript, test version 1.0a1, and some other related software. Maxtal Interscript is a programming environment with a strong emphasis on documentation and scripting. Whereas traditional literate programming tools embed code in documentation, and provide a limited, static, command language, Maxtal Interscript supports a third kind of text: it uses executable script as a command language. 2. Maxtal Interscript [iscr.pak] -------------------------------- 2.1. Command Languages ---------------------- The current release supports two command languages, python, and tcl. Python support is complete, Interscript 1.0a1 itself is written in Python. Support for Tcl is not complete, but is enough to provide basic documentation constructions. Support for Perl as a command language is under consideration. 2.2. Weavers ------------ Interscript 1.0a1 has four built in weavers: plain text, latex2e, single page html, and stacked html. A Postscript weaver is planned. Weavers for other typesetting systems are under consideration. Users can 'plug in' third party weavers, write their own, or derive new weavers from the standard ones. 2.3. Tanglers ------------- Interscript 1.0a1 comes with several built in tanglers. There is a tangler for plain data, and specialised tanglers for python, C, C++, perl and interscript. The perl tangler supports perl's POD. 2.4. Requirements ----------------- You will require Python 1.5 or better. To support the Tcl command option, you will need PyTcl (see below) To support the GUI interface, you will require the tcl command option and Tk 8.0. 3. Compiler package [compiler.pak] ---------------------------------- Interscript has a standard interface to C and C++ which permits run-time generation, compilation, dynamic loading, and execution of C or C++ code configured either as a Python module or stand-alone application. The current sources contain a sample compiler package which should operate correctly on a RedHat Linux 5 box. Adaption to local site requirements on other Unix sites should be trivial. I'm trying to build a Windows compiler module, but help is required (where's Python.lib??) 4. Diff/Patch module [diff.pak] ------------------------------- An experimental diff/patch module is available which should work out of the box under Unix or other systems supporting diff and patch commands. This module will be used to support version control and differential file updates. (Help required for Windows version) 5. Protocol module [protocol.pak] --------------------------------- An attempt to standardise the notion of python protocols. 6. PyTcl [_pytcl.pak] --------------------- A low level dynamically loadable Python compatible C API _pytcl allows access to the Tcl 8.0 C API. Designed to replace _tkinter. Includes fully object oriented object system supporting dynamic multi-methods and delegation. Compatibility module _tkinter.py to allow Tkinter use with _pytcl. You will require Tcl 8.0 and a C++ compiler, or a prebuilt binary of the _pytcl dynamic load library. You will also require the Tcl/Tk manual pages in HTML format prepared by Entropy Liberation Front, www.elf.org. You need tcl8.0-tk8.0-man-html.tar.gz installed as the directory tcl8.0-tk8.0-man-html to generate the reference manual and to allow hypertext links to it to point to the right place. 7. More Information ------------------- More information, demos, documentation, plans, and download instructions can be found at http://www.triode.net.au/~skaller/interscript The 'I dont read instructions' download instructions are: create an image of: ftp://ftp.triode.net.au/skaller/interscript on your system. (Use ascii ftp under Windows). Run ../boot1/iscr.py against iscr.pak in the boot2 directory. Run (the generated) iscr.py against iscr.pak. cd boot2 python ../boot1/iscr.py iscr.pak python iscr.py iscr.pak Run iscr.py --help for help with options. Read the generated documentation! (All four weavers are invoked automatically) For other packages, such as 'dm.pak': python iscr.py --weaver=web dm.pak The subdirectory boot1 contains the bootstrap version of interscript, iscr.py. It will (currently) run off the shelf without support. The subdirectory boot2 contains all the Maxtal Interscript sources for all the other packages. [There is no 'documentation': you have to generate it.] PyTcl also needs the tcl/tk manual (see above). Email me at mailto:skaller@maxtal.com.au for futher information, help, comments, or contributions. WARNING: the web site is under contstruction. The software is under construction. Experimental! (But isn't all software :-) WARNING: the sources come to about 650K at present. The FTP site has a 5 user limit and is probably slow. If things go well, ftp.python.org will mirror selected snapshots. 7.1. Licence ------------ All Maxtal software is copyright and released for any use. Some third party software is included and subject to the original licence of that software. Consult the sources for precise details on each such package. I have tried to ensure original authors are credit in all cases. Daniel Robbins dm module is free for any non-spam use. The Grammar module was adapted from PyLR by scott@chronis@icgroup.com The list of the whole Perl module library was taken from the sources on my RedHat Linux 5 box, and is free for any non-commercial use. See www.perl.com for more information. Modified versions of Python library components are free for any use provided the copyright notices are retained. John Skaller skaller@maxtal.com.au Maxtal P/L, Australia 19th July, 1998. John Max Skaller ph:61-2-96600850 mailto:skaller@maxtal.com.au 10/1 Toxteth Rd http://www.maxtal.com.au/~skaller Glebe 2037 NSW AUSTRALIA 21-Jul-1998 7:21:12-GMT,1444;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id BAA02949 for ; Tue, 21 Jul 1998 01:21:11 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 21 Jul 1998 02:17:12 EST From: Matti Picus Subject: Why NOT docxx? Date: 21 Jul 1998 02:51:07 GMT Message-ID: <6p0vmr$ovc$1@news.interlog.com> Reply-To: LitProg@SHSU.edu, matti@techunix.technion.ac.il MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu OK, it isn't strictly literate programming as such, but I am looking for a tool to document Matlab code. I would like to still be able to run my m-files quickly, with no extra "tangle" step, but would like to document them with LaTeX. noweb looks good, but I can't get it to run under win95 or NT. Yes, I read all the info I could. Unfortunately, Linux at work is not an option (yet). So here are my questions: 1. Has anyone got noweb running under windows with perl5 build 317? 2. Has anyone changed docxx to other syntaxes, like Matlab? 3. Does anyone use clip? I could not get it working either. thanks, Matti Picus I don't THINK I am stupid, therefore I am. 21-Jul-1998 11:21:20-GMT,1672;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id FAA07103 for ; Tue, 21 Jul 1998 05:21:19 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 21 Jul 1998 06:08:22 EST From: "Andrew Hogue" Reply-To: LitProg@SHSU.edu, syberspaz@yahoo.com Subject: !!!!!!!!!!! BINARY TREE PROBLEM......PLEASE HELP ASAP!!!!!!!!!!! Date: Tue, 21 Jul 1998 05:13:25 -0500 Message-ID: <6p1mfs$mvm$1@sunburst.ccs.yorku.ca> To: LitProg@SHSU.edu Hi there, I have this problem with binary trees, if anyone here can help me, please email me your solution at: syberspaz@yahoo.com Thanks Here it is: Suppose you were given a bunch of numbers in a given order .... for example.... 2 4 3 8 10 9 6 I have to figure out whether this is a legal POST-ORDER TRAVERSAL of a BINARY TREE...... therefore, by just looking at this the tree looks like 6 3 9 2 4 8 10 But, my problem lies in how do I create a function to have as input a series of numbers as above....in an array lets say.... and this function must output whether the given series is a valid post-order traversal of a binary tree.... so the function should return true or false.... basically, the coding should be simple....it's the algorithm that I have a problem with.... p.s. I know C/C++, Pascal, Thank you very much for answering this problem..... Andrew syberspaz@yahoo.com 21-Jul-1998 13:43:52-GMT,2750;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id HAA09563 for ; Tue, 21 Jul 1998 07:43:51 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from turbo.kean.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 21 Jul 1998 08:36:58 EST Received: from samson.kean.edu (SAMSON.KEAN.EDU [131.125.4.200]) by turbo.kean.edu (8.8.7/8.8.7) with SMTP id JAA10970; Tue, 21 Jul 1998 09:35:08 -0400 (EDT) Received: from localhost by samson.kean.edu (5.x/SMI-SVR4) id AA04786; Tue, 21 Jul 1998 09:35:47 -0400 Date: Tue, 21 Jul 1998 09:35:46 -0400 (EDT) From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu To: LitProg@SHSU.edu, matti@techunix.technion.ac.il Subject: Re: Why NOT docxx? Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On 21 Jul 1998, Matti Picus wrote: > noweb looks good, but I can't get it to run under win95 or NT. Yes, I > read all the info I could. Unfortunately, Linux at work is not an option > (yet). > > So here are my questions: > 1. Has anyone got noweb running under windows with perl5 build 317? I have a (somewhat) experimental binary port of noweb 2.7d for Win95 that does not require Perl (it *should* also run under NT). You can find it at ftp://samson.kean.edu/pub/leew/noweb/noweb-2.7d-win32-alpha.zip (there is also a NT-NOWEB28A.ZIP file in the same directory, but I can't remember where I got it from, so I don't know whether it works or not). I say the port is experimental, because I never really tested it too thoroughly, but Carl Gregory has been using it for more than 2 years now, and hasn't complained yet (although he may just be being polite -- I'll cc him a copy of this message, just in case). The port uses the Cygnus port of the GNU utilities, and is a straightforward compilation of the original noweb source (and includes Icon binaries). It uses a 2 year old version of the Cygnus stuff, and I really need to update it, but it seems to work. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | "Begin at the middle...then you're not so Computer Science Department | far from either the beginning or the Kean University | ending." Union, NJ 07083 | | -- Erle Stanley Gardner leew@samson.kean.edu | "The Case of the Fugitive Nurse" (1954) ------------------------------------------------------------------------ 21-Jul-1998 23:37:15-GMT,1405;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id RAA29039 for ; Tue, 21 Jul 1998 17:37:14 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 21 Jul 1998 18:34:51 EST From: skaller@maxtal.com.au (John (Max) Skaller) Subject: Re: ANN: pre-release Interscript 1.0a1 Date: 20 Jul 1998 19:36:34 GMT Message-ID: <6p0682$qtc$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, skaller@maxtal.com.au To: LitProg@SHSU.edu On 20 Jul 1998 07:54:14 GMT, skaller@maxtal.com.au (John (Max) Skaller) wrote: > >7. More Information >------------------- > >More information, demos, documentation, plans, and >download instructions can be found at >http://www.triode.net.au/~skaller/interscript Should be: http://www.triode.net.au/~skaller/interscript/iscrhome.html Sorry. >John Max Skaller ph:61-2-96600850 >mailto:skaller@maxtal.com.au 10/1 Toxteth Rd >http://www.maxtal.com.au/~skaller Glebe 2037 NSW AUSTRALIA John Max Skaller ph:61-2-96600850 mailto:skaller@maxtal.com.au 10/1 Toxteth Rd http://www.maxtal.com.au/~skaller Glebe 2037 NSW AUSTRALIA 22-Jul-1998 5:36:31-GMT,2404;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id XAA04532 for ; Tue, 21 Jul 1998 23:36:30 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 22 Jul 1998 00:34:06 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Why NOT docxx? Date: 21 Jul 1998 14:26:02 GMT Message-ID: <6p28dq$ogh$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 21 Jul 1998, Matti Picus wrote: > noweb looks good, but I can't get it to run under win95 or NT. Yes, I > read all the info I could. Unfortunately, Linux at work is not an option > (yet). > > So here are my questions: > 1. Has anyone got noweb running under windows with perl5 build 317? I have a (somewhat) experimental binary port of noweb 2.7d for Win95 that does not require Perl (it *should* also run under NT). You can find it at ftp://samson.kean.edu/pub/leew/noweb/noweb-2.7d-win32-alpha.zip (there is also a NT-NOWEB28A.ZIP file in the same directory, but I can't remember where I got it from, so I don't know whether it works or not). I say the port is experimental, because I never really tested it too thoroughly, but Carl Gregory has been using it for more than 2 years now, and hasn't complained yet (although he may just be being polite -- I'll cc him a copy of this message, just in case). The port uses the Cygnus port of the GNU utilities, and is a straightforward compilation of the original noweb source (and includes Icon binaries). It uses a 2 year old version of the Cygnus stuff, and I really need to update it, but it seems to work. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | "Begin at the middle...then you're not so Computer Science Department | far from either the beginning or the Kean University | ending." Union, NJ 07083 | | -- Erle Stanley Gardner leew@samson.kean.edu | "The Case of the Fugitive Nurse" (1954) ------------------------------------------------------------------------ 22-Jul-1998 14:05:10-GMT,64888;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id IAA11814 for ; Wed, 22 Jul 1998 08:05:07 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 22 Jul 1998 08:49:46 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 22 Jul 1998 11:26:20 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.edu Archive-name: literate-programming-faq Last-modified: 1997/08/15 Version: 1.1.18 The Literate Programming FAQ David B. Thompson 15 August 1997 This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. ______________________________________________________________________ Table of Contents: 1. Welcome 1.1. Disclaimer 1.2. Copyright 1.3. What's New? 2. Introduction or 3. How do I get the FAQ? 3.1. Literate Programming FAQ 3.2. FWEB FAQ 4. Is there a newsgroup? 5. What internet nodes are of interest to literate programmers? 6. What is Literate Programming? 7. How do I begin literate programming? 8. What literate programming tools are available? 8.1. APLWEB 8.2. AWEB 8.3. CLiP 8.4. CWEB 8.5. CWEBx3.0 8.6. mCWEB 8.7. FunnelWeb 8.8. FunnelWeb 3.0AC 8.9. FWEB 8.10. IMPACT 8.11. lit2x 8.12. Literate Programmer's Workshop (LPW) 8.13. MapleWEB 8.14. MWEB (Schrod/Detig) 8.15. MWEB (Sewell) 8.16. noweb 8.17. nuweb 8.18. ProTeX 8.19. RWEB 8.20. SchemeWEB 8.21. SpideryWEB 8.22. WEB 8.23. WinWordWEB 9. Are there other tools I should know about? 9.1. C2LaTeX 9.2. c2cweb 9.3. c2man 9.4. cnoweb 9.5. Fold2Web 9.6. Funnelweb Mode 9.7. noweb.el 9.8. nuweb.el 9.9. TIE 9.10. Web mode 10. What other resources are available? 10.1. World Wide Web 10.2. TeX Resources 11. Are there any code examples? 12. Bibliographies 13. How to anonymously ftp 14. Acknowledgements 15. End notes ______________________________________________________________________ 1. Welcome Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 1.1. Disclaimer Disclaimer: ``This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk.'' 1.2. Copyright Copyright 1993-1997 by David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: 1.3. What's New? o My email address has changed (once again). o Newsgroup is moderated. o Updated fweb entry. o Updated noweb entry. o Added mCWEB entry. o Updated c2cweb entry. o Updated nuweb.el entry. o Updated cLiP entry. o Updated Lee W's examples (from bart). o Last, but not least, new formatting of the FAQ. Many thanks go to Andrew Johnson for helping make this happen. 2. Introduction or ``What's this all about?'' This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson Comments and constructive criticisms are welcome. Direct flames to /dev/null (or nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is not complete, and probably will never be complete. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. 3. How do I get the FAQ? 3.1. Literate Programming FAQ You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled ``Internet Nodes of Interest to Literate Programmers''.) 3.2. FWEB FAQ David Coker maintains the FWEB FAQ. The current version number is 1.30a. It can be retrieved in the same way as this FAQ. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de 131.169.10.115 in directory /pub/faq/web/fweb/. It is also available from the literate programming archive in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). 4. Is there a newsgroup? One of the most important resources is the literate programming newsgroup, comp.programming.literate. Because of the amount of spamming and unrelated the posts, the newsgroup is now moderated. Posts to the newsgroup are now routed through litprog- mod@cs.virginia.edu. If your news reader does not post through this address, then you will be unable to post messages to the newgroup. You can read this newsgroup using your standard reader. 5. What internet nodes are of interest to literate programmers? The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. Participating hosts in the Comprehensive TeX Archive Network are: ftp.dante.de (Deutschland) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node sun.dante.de -- e-mail via ftpmail@dante.de -- Administrator: ftp.tex.ac.uk (England) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node gopher.tex.ac.uk -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive -- World Wide Web access on www.tex.ac.uk -- Administrator: The site ftp.shsu.edu used to be the American CTAN site. Apparently, that site has fallen into disrepair and should not be considered a primary source for either TeX related or literate programming related material. For the record, the address is: ftp.shsu.edu (Texas, USA) -- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive) -- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive -- e-mail via ftpmail@ftp.SHSU.edu -- World Wide Web access on www.SHSU.edu -- Administrator: A list of CTAN archive sites and their mirrors can be found on: ftp.dante.de:/tex-archive/CTAN.sites I presume that the other CTAN sites mirror this file, but have not checked. As of my last check (September 1994), it contains: "In order to reduce network load, it is recommended that you use the Comprehensive TeX Archive Network (CTAN) host which is located in the closest network proximity to your site." Known partial mirrors of the CTAN reside on (alphabetically): dongpo.math.ncu.edu.tw (Taiwan) /tex-archive ftp.adfa.oz.au (Australia) /pub/tex/ctan ftp.muni.cz (The Czech Republic) /pub/tex/CTAN ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive ftp.uu.net (Virginia, USA) /pub/text-processing/TeX nic.switch.ch (Switzerland) /mirror/tex Known mirrors of the CTAN reside on (alphabetically): ftp.center.osaka-u.ac.jp (Japan) /CTAN ftp.ccu.edu.tw (Taiwan) /pub/tex ftp.cs.rmit.edu.au (Australia) /tex-archive ftp.duke.edu (North Carolina, USA) /tex-archive ftp.germany.eu.net (Deutschland) /pub/packages/TeX ftp.gwdg.de (Deutschland) /pub/dante ftp.jussieu.fr (France) /pub4/TeX/CTAN ftp.loria.fr (France) /pub/unix/tex/ctan ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de ftp.uni-bielefeld.de (Deutschland) /pub/tex ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex) ftpserver.nus.sg (Singapore) /pub/zi/TeX src.doc.ic.ac.uk (England) /packages/tex/uk-tex sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX wuarchive.wustl.edu (Missouri, USA) /packages/TeX Other nodes and directories of interest include: Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ 6. What is Literate Programming? Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system pro- grammer, who wants to provide the best possible documenta- tion of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To docu- ment such a program we want to explain each individual part of the web and how it relates to its neighbours. The typo- graphic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combin- ing the two, we can develop a style of programming that max- imizes our ability to perceive the structure of a complex piece of software, and at the same time the documented pro- grams can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why. Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM ref. 1 plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References 1 Paul W. Oman and Curtus Cook. ``Typographical style is more than cosmetic.'' CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called ``informal rigour'', i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 Another author (Norman Ramsey) wrote me and asked that his opinions be included in the FAQ. What follows are Norman's comments verbatim. I see it's time for the ``how is literate programming dif- ferent from verbose commenting'' question. Perhaps David Thompson will get this into the FAQ. Alert! What follows are my opinions. In no way do I claim to speak for the (fractious) literate-programming community. How is literate programming different from verbose commenting? There are three distinguishing characteristics. In order of importance, they are: o flexible order of elaboration o automatic support for browsing o typeset documentation, especially diagrams and mathematics Flexible order of elaboration means being able to divide your source program into chunks and write the chunks in any order, independent of the order required by the compiler. In principle, you can choose the order best suited to explaining what you are doing. More subtly, this discipline encourages the author of a literate program to take the time to consider each fragment of the program in its proper sphere, e.g., not to rush past the error checking to get to the ``good parts.'' In its time and season, each part of the program is a good part. (This is the party line; your mileage may vary.) I find the reordering most useful for encapsulating tasks like input validation, error checking, and printing output fit for humans --- all tasks that tend to obscure ``real work'' when left inline. Reordering is less important when using languages like Modula-3, which has exceptions and permits declarations in any order, than when using languages like C, which has no exceptions and requires declaration before use. Automatic support for browsing means getting a table of contents, index, and cross-reference of your program. Cross-reference might be printed, so that you could consult an index to look up the definition of an identifier `foo'. With good tools, you might get a printed mini-index on every page if you wanted. Or if you can use a hypertext technology, cross-reference might be as simple as clicking on an identifier to reach its definition. Indexing is typically done automatically or `semi- automatically', the latter meaning that identifier definitions are marked by hand. Diligently done semi- automatic indexes seem to be best, because the author can mark only the identifiers he or she considers important, but automatic indexing can be almost as good and requires no work. Some tools allow a mix of the two strategies. Some people have applied literate-programming tools to large batches of legacy code just to get the table of contents, index, and cross-reference. I don't use diagrams and mathematics very often, but I wouldn't want to have to live without them. I have worked on one or two projects where the ability to use mathematical formulae to document the program was indispensible. I also wouldn't like to explain some of my concurrent programs without diagrams. Actually I write almost all of my literate programs using only sections headers, lists, and the occasional table. >Wouldn't it be easier to do one's literate programming using >a wysiwyg word processor (e.g. Word for Windows) and >indicate what is source code by putting it in a different >font? The data formats used in wysiwyg products are proprietary, and they tend to be documented badly if at all. They are subject to change at the whim of the manufacturer. (I'll go out on a limb and say there are no significant wysiwyg tools in the public domain. I hope the Andrew people will forgive me.) These conditions make it nearly impossible to write tools, especially tools that provide automatic indexing and cross-reference support. The CLiP people have a partial solution that works for tools that can export text --- they plant tags and delimiters throughout the document that enable the reordering transformation (``tangling''). People use TeX, roff, and HTML because free implementations of these tools are widely available on a variety of platforms. TeX and HTML are well documented, and TeX and roff are stable. TeX is the most portable. I think I have just answered the FAQ ``how come all these tools use TeX, anyway?'' :-) Norman Ramsey 7. How do I begin literate programming? A recommended book is D.E. Knuth's collection of articles (1992) Literate Programming. Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) Weaving a Program: Literate Programming in WEB. Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. 8. What literate programming tools are available? A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) 8.1. APLWEB Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. 8.2. AWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. 8.3. CLiP Developer: E.W. van Ammers and M.R. Kramer Versions: 2.0 and 2.4b (DOS only) Platform: Vax/VMS, Unix, DOS Languages: Any programming language Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, WinWord, Ami Pro, Word Pro, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos DOS sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b) sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS sun01.info.wau.nl:/CLIP/unix Unix CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicit commands to perform the extraction process. Rather it recognizes pseudostatements written as comments in the programming language in question. CLiP distinguishes pseudostatements from ordinary comments because the former comply with a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well. Some hypertext examples are at ftp://sun01.info.wau.nl/clip/html/queens.htm ftp://sun01.info.wau.nl/clip/html/pal1.htm Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentation my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segments. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail to Eric.vanAmmers@user.info.wau.nl 8.4. CWEB Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu 8.5. CWEBx3.0 Developer: Marc van Leeuwen Version: Unknown Hardware: Any system using ASCII code Languages: ANSI C Formatter: Plain TeX Availability: Anonymous ftp from: ftp.cwi.nl/pub/cweb Readme: Bundled with above Brief description: A modified implementation of CWEB, with some extensions. Provides a mode for full compatibility with Levy/Knuth CWEB. The most significant extras are: - Typedef declarations affect formatting througout source file - Include files are scanned for typedef definitions - Flexible selection of layout style - Possibility to refer to sections using symbolic labels - CTANGLE detects unbalanced braces and parentheses - CWEAVE can be made to report syntax errors more easily - Some additional mechanisms to avoid formatting problems - New and modular set of grammar rules, based on ANSI C syntax - Possibility to suppress #line directives - A new manual Support: bugs and remarks to M.van.Leeuwen@cwi.nl 8.6. mCWEB Developer: Markus Oellinger Version: 1.0 Hardware: Unix Languages: C/C++ Formatter: plainTeX Availability: anonymous ftp from ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz Readme: at same location Description: This is mCWEB 1.0, a descendant of the CWEB system of structured documentation by Donald E. Knuth and Silvio Levy. It adds some features that are indispensable when working in a team. mCWEB regards a project of a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface documentation is now also part of mCWEB. It is extracted into a second TeX file. This makes it possible to define well known interfaces between the individual parts of a project that will be implemented by different persons. In addition, mCWEB parses C header files to find out about all the datatypes defined there. mCWEB comes with a full completely rewritten user manual and is compatible with CWEB. Support: Institute of Software Technology moell@ist.tu-graz.ac.at 8.7. FunnelWeb Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. 8.8. FunnelWeb 3.0AC Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au) from FunnelWeb v3.0 by Ross N. Williams (ross@guest.adelaide.edu.au) Version: 3.0AC Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2. Languages: No restrictions. Formatter: Tex, LaTeX, or HTML. Availability: Anonymous ftp from ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz Readme: With bundle above; for FunnelWeb manual see WWW page http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html Description: FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry for FunnelWeb). FunnelWeb is designed to be typesetter independent, though FunnelWeb v3.0 only supports (La)TeX as the typesetter. FunnelWeb 3.0AC also supports HTML, and creates appropriate hypertext links within the document among the code sections. FunnelWeb 3.0AC also supports automatic and manual insertion of line directives, so that compiler errors can be flagged back to the original FunnelWeb source file. FunnelWeb 3.0AC is completely compatible with FunnelWeb v3.0 sources (with one minor exception; see the file README.ABC which comes with the FunnelWeb 3.0AC distribution). Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject to the time constraints imposed by his thesis. 8.9. FWEB Developer: John A. Krommes Version: 1.53 (1.60-beta for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: LaTeX. Plain TeX may work, but is no longer supported. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu 8.10. IMPACT Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. 8.11. lit2x Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown 8.12. Literate Programmer's Workshop (LPW) Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. 8.13. MapleWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown 8.14. MWEB (Schrod/Detig) Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.15. MWEB (Sewell) Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.16. noweb Developer: Norman Ramsey Version: 2.8 Hardware: Unix and DOS platforms (DOS binaries available for v2.7). Languages: All programming languages, singly or in combination. Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc Formatter: Plain TeX, LaTeX, and HTML formatters. Will convert LaTeX to HTML automatically. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent Last recourse, use ftp.cs.virginia.edu:pub/nr Readme: With bundle above, or see the noweb home page: http://www.cs.virginia.edu/~nr/noweb Those without ftp access can consult ``Literate Programming Simplified,'' IEEE Software, September 1994, pp97-105. Description: noweb is designed to meet the needs of literate programmers while retaining the simplest possible input format. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 3 pages; an additional page explains how to customize its LaTeX output. noweb works ``out of the box'' with any programming language, and supports TeX, latex, and HTML back ends. A back end to support full hypertext or indexing takes about 250 lines; a simpler one can be written in 40 lines of awk. The primary sacrifice relative to WEB is that code is not prettyprinted. noweb supports indexing and identifier cross-reference, including hypertext ``hot links.'' noweb includes a simple, efficient LaTeX-to-HTML converter, so you can use hypertext browsers on your legacy documents. noweb can also process nuweb programs, so you can use noweb to convert a standard nuweb program to HTML with one command. Support: email to the author 8.17. nuweb Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu 8.18. ProTeX Developer: Eitan Gurari Version: ProTeX 1.1, AlProTeX 1.4 Hardware: Any platform with (La)TeX Languages: Any language Formatter: TeX or LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: With bundle above Description: + Easy to use + Extensible + Language independent + Multiple output files + Fast (single compilation provides output and dvi files) + No installation is needed besides copying the files (written in TeX) Introduction of main features and examples in pub/tex/osu/gurari/LitProg Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and Literate Programming", McGraw-Hill, 1994 Support: gurari@cis.ohio-state.edu 8.19. RWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown 8.20. SchemeWEB Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. 8.21. SpideryWEB Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. 8.22. WEB Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. 8.23. WinWordWEB Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. 9. Are there other tools I should know about? First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. 9.1. C2LaTeX Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. 9.2. c2cweb Developer: Werner Lemberg Version: 1.5 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg 9.3. c2man language: C, nroff, texinfo, latex, html package: c2man version: 2.0 patchlevel 33 parts: documentation generator (C -> nroff -man, -> texinfo, ->latex, -> html) author: Graham Stoney location: ftp from any comp.sources.misc archive, in volume42 (the version in the comp.sources.reviewed archive is obsolete) ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from archie.au N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from ftp.wustl.edu Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* from ftp.irisa.fr Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* from ftp.iij.ad.jp Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se description: c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. conformance: supports both K&R and ISO/ANSI C coding styles features: + generates output in nroff -man, TeXinfo, LaTeX or HTML format + handles comments as part of the language grammar + automagically documents enum parameter & return values + handles C (/* */) and C++ (//) style comments - doesn't handle C++ grammar (yet) requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX. ports: Unix, OS/2, MSDOS, VMS. portability: very high for unix, via Configure status: actively developed; contributions by users are encouraged. discussion: via a mailing list: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au help: from the author and other users on the mailing list: c2man@research.canon.oz.au announcements: patches appear first in comp.sources.bugs, and then in comp.sources.misc. updated: 1994/10/07 9.4. cnoweb Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. 9.5. Fold2Web Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de 9.6. Funnelweb Mode Developer: Daniel Simmons Version: Unknown Availability: http://www.miscrit.be/~ddw Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown 9.7. noweb.el Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk 9.8. nuweb.el Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@acm.org 9.9. TIE Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown 9.10. Web mode Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown 10. What other resources are available? 10.1. World Wide Web An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html or use a WWW browser and access the URL ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to rtfm.mit.edu and retrieve the official Usenet resource file /pub/usenet/news.answers/www/resources/literate-programming 10.2. TeX Resources Another resource of interest to literate programmers is the comp.text.tex newsgroup. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this resource. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. 11. Are there any code examples? Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au 129.127.40.3 as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: ftp://samson.kean.edu/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is writ- ten in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb 12. Bibliographies Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu 128.110.198.2 in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says sev- eral times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. 13. How to anonymously ftp Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu 18.181.0.24, under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. 14. Acknowledgements This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. 15. End notes This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. 22-Jul-1998 19:46:42-GMT,1155;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id NAA19120 for ; Wed, 22 Jul 1998 13:46:35 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 22 Jul 1998 14:33:32 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Why NOT docxx? Date: 22 Jul 1998 19:00:52 GMT Message-ID: <6p5ct4$d1n$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6p0vmr$ovc$1@news.interlog.com>, Matti Picus wrote: >noweb looks good, but I can't get it to run under win95 or NT. The alpha version of noweb 3 is designed to be easily ported to Win95 or WNT. If I had documentation I would do it myself. As it is, I will be happy to work with anyone who wants to try the port. I have just posted a new version of noweb 3. This one fixes a number of show-stopping bugs in no weave -index. Norman 24-Jul-1998 7:33:41-GMT,1370;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id BAA02898 for ; Fri, 24 Jul 1998 01:33:40 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 24 Jul 1998 02:30:00 EST From: Martin Harvey Reply-To: LitProg@SHSU.edu, mch24@harvey27.demon.co.uk Subject: XML for literate programming? Date: 24 Jul 1998 07:06:21 GMT Message-ID: <6p9bpd$aao$1@elna.ethz.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Hi folks, Okay, I'm new to the group, but I've at least browsed the FAQ :-) In my last programming project (University final year thingy, which you can see on my web pages), I didn't have access to any LP tools, and thus slaved away with Borland (oops Inprise) Delphi on one half of the screen, and M$ word on the other... and I found this NG as a result of the pain experienced in the process. Has anyone thought about using XML (and a suitably defined set of tags) for use in LP. Would this have any advantages over current LP systems (about which I confess I know very little)? MH. 30-Jul-1998 19:42:34-GMT,1173;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id NAA00787 for ; Thu, 30 Jul 1998 13:42:26 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 30 Jul 1998 14:27:20 EST From: ptjm@interlog.com (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@interlog.com Subject: interesting quotation Date: 30 Jul 1998 03:21:58 GMT Message-ID: <6poosm$amc$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I just wanted to pass along a quotation from an obituary in today's Globe and Mail. The deceased is talking about writing in English, but I think it goes to the heart of Literate Programming. I sometimes think that if I didn't write I'd be dummb as a post, because I nearly always discover what I think in the course of writing about it. This leaves me wondering if I'd be capable of thought if I didn't write. -- Lawrence Jackson -- Patrick TJ McPhee East York Canada ptjm@interlog.com 31-Jul-1998 17:12:06-GMT,1050;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id LAA26717 for ; Fri, 31 Jul 1998 11:12:05 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 31 Jul 1998 12:01:55 EST From: jamz@my-dejanews.com Reply-To: LitProg@SHSU.edu, jamz@my-dejanews.com Subject: folding documentation into source in noweb? Date: 31 Jul 1998 16:34:35 GMT Message-ID: <6psrmr$8be$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I've been using noweb on a project that I'm going to deliver as regular source. I was wondering if anybody has a filter that incorporates the documentation chunks into the source inside a /* */ comment? Thanks, Monty -----== Posted via Deja News, The Leader in Internet Discussion ==----- http://www.dejanews.com/rg_mkgrp.xp Create Your Own Free Member Forum 31-Jul-1998 17:24:30-GMT,981;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id LAA26998 for ; Fri, 31 Jul 1998 11:24:30 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 31 Jul 1998 12:18:53 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: folding documentation into source in noweb? Date: 31 Jul 1998 16:53:57 GMT Message-ID: <6pssr5$8s3$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu >I've been using noweb on a project that I'm going to deliver as regular >source. I was wondering if anybody has a filter that incorporates the >documentation chunks into the source inside a /* */ comment? Such a program is distributed with noweb and is called `nountangle'. N 2-Aug-1998 10:55:40-GMT,1022;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id EAA11105 for ; Sun, 2 Aug 1998 04:55:39 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 02 Aug 1998 05:52:01 EST From: ptjm@interlog.com (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@interlog.com Subject: Another web page Date: 1 Aug 1998 15:11:49 GMT Message-ID: <6pvb7l$9h2$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I just unexpectedly came across an introduction to noweb in a Sun Developer support newsletter (from 1995). In case anyone's interested in looking at it, or adding a link to it to a home page, or whatever, it's at http://www.sun.ca/newsletter/SunOpsisVol4.No3/SunOpsisVol4.No3.html#12256 -- Patrick TJ McPhee East York Canada ptjm@interlog.com 4-Aug-1998 20:38:09-GMT,942;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id OAA16802 for ; Tue, 4 Aug 1998 14:38:03 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 04 Aug 1998 15:27:07 EST From: "Stephen Johnston" Reply-To: LitProg@SHSU.edu, stephenj@javanet.com Subject: Adding right Click Functionality to Windows Date: Tue, 4 Aug 1998 16:14:49 -0400 Message-ID: <6q7q4m$b0q$1@as4100c.javanet.com> To: LitProg@SHSU.edu Hello All- I would like to have my program started from a right click in windows, probably contextually. Does anyone know of a resource that discusses how to add right click functionality to Windows? Thanks- Stephen Johnston 6-Aug-1998 13:37:04-GMT,64886;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id HAA04056 for ; Thu, 6 Aug 1998 07:37:01 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 06 Aug 1998 08:24:21 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 6 Aug 1998 11:33:25 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.edu Archive-name: literate-programming-faq Last-modified: 1997/08/15 Version: 1.1.18 The Literate Programming FAQ David B. Thompson 15 August 1997 This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. ______________________________________________________________________ Table of Contents: 1. Welcome 1.1. Disclaimer 1.2. Copyright 1.3. What's New? 2. Introduction or 3. How do I get the FAQ? 3.1. Literate Programming FAQ 3.2. FWEB FAQ 4. Is there a newsgroup? 5. What internet nodes are of interest to literate programmers? 6. What is Literate Programming? 7. How do I begin literate programming? 8. What literate programming tools are available? 8.1. APLWEB 8.2. AWEB 8.3. CLiP 8.4. CWEB 8.5. CWEBx3.0 8.6. mCWEB 8.7. FunnelWeb 8.8. FunnelWeb 3.0AC 8.9. FWEB 8.10. IMPACT 8.11. lit2x 8.12. Literate Programmer's Workshop (LPW) 8.13. MapleWEB 8.14. MWEB (Schrod/Detig) 8.15. MWEB (Sewell) 8.16. noweb 8.17. nuweb 8.18. ProTeX 8.19. RWEB 8.20. SchemeWEB 8.21. SpideryWEB 8.22. WEB 8.23. WinWordWEB 9. Are there other tools I should know about? 9.1. C2LaTeX 9.2. c2cweb 9.3. c2man 9.4. cnoweb 9.5. Fold2Web 9.6. Funnelweb Mode 9.7. noweb.el 9.8. nuweb.el 9.9. TIE 9.10. Web mode 10. What other resources are available? 10.1. World Wide Web 10.2. TeX Resources 11. Are there any code examples? 12. Bibliographies 13. How to anonymously ftp 14. Acknowledgements 15. End notes ______________________________________________________________________ 1. Welcome Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 1.1. Disclaimer Disclaimer: ``This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk.'' 1.2. Copyright Copyright 1993-1997 by David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: 1.3. What's New? o My email address has changed (once again). o Newsgroup is moderated. o Updated fweb entry. o Updated noweb entry. o Added mCWEB entry. o Updated c2cweb entry. o Updated nuweb.el entry. o Updated cLiP entry. o Updated Lee W's examples (from bart). o Last, but not least, new formatting of the FAQ. Many thanks go to Andrew Johnson for helping make this happen. 2. Introduction or ``What's this all about?'' This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson Comments and constructive criticisms are welcome. Direct flames to /dev/null (or nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is not complete, and probably will never be complete. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. 3. How do I get the FAQ? 3.1. Literate Programming FAQ You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled ``Internet Nodes of Interest to Literate Programmers''.) 3.2. FWEB FAQ David Coker maintains the FWEB FAQ. The current version number is 1.30a. It can be retrieved in the same way as this FAQ. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de 131.169.10.115 in directory /pub/faq/web/fweb/. It is also available from the literate programming archive in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). 4. Is there a newsgroup? One of the most important resources is the literate programming newsgroup, comp.programming.literate. Because of the amount of spamming and unrelated the posts, the newsgroup is now moderated. Posts to the newsgroup are now routed through litprog- mod@cs.virginia.edu. If your news reader does not post through this address, then you will be unable to post messages to the newgroup. You can read this newsgroup using your standard reader. 5. What internet nodes are of interest to literate programmers? The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. Participating hosts in the Comprehensive TeX Archive Network are: ftp.dante.de (Deutschland) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node sun.dante.de -- e-mail via ftpmail@dante.de -- Administrator: ftp.tex.ac.uk (England) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node gopher.tex.ac.uk -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive -- World Wide Web access on www.tex.ac.uk -- Administrator: The site ftp.shsu.edu used to be the American CTAN site. Apparently, that site has fallen into disrepair and should not be considered a primary source for either TeX related or literate programming related material. For the record, the address is: ftp.shsu.edu (Texas, USA) -- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive) -- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive -- e-mail via ftpmail@ftp.SHSU.edu -- World Wide Web access on www.SHSU.edu -- Administrator: A list of CTAN archive sites and their mirrors can be found on: ftp.dante.de:/tex-archive/CTAN.sites I presume that the other CTAN sites mirror this file, but have not checked. As of my last check (September 1994), it contains: "In order to reduce network load, it is recommended that you use the Comprehensive TeX Archive Network (CTAN) host which is located in the closest network proximity to your site." Known partial mirrors of the CTAN reside on (alphabetically): dongpo.math.ncu.edu.tw (Taiwan) /tex-archive ftp.adfa.oz.au (Australia) /pub/tex/ctan ftp.muni.cz (The Czech Republic) /pub/tex/CTAN ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive ftp.uu.net (Virginia, USA) /pub/text-processing/TeX nic.switch.ch (Switzerland) /mirror/tex Known mirrors of the CTAN reside on (alphabetically): ftp.center.osaka-u.ac.jp (Japan) /CTAN ftp.ccu.edu.tw (Taiwan) /pub/tex ftp.cs.rmit.edu.au (Australia) /tex-archive ftp.duke.edu (North Carolina, USA) /tex-archive ftp.germany.eu.net (Deutschland) /pub/packages/TeX ftp.gwdg.de (Deutschland) /pub/dante ftp.jussieu.fr (France) /pub4/TeX/CTAN ftp.loria.fr (France) /pub/unix/tex/ctan ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de ftp.uni-bielefeld.de (Deutschland) /pub/tex ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex) ftpserver.nus.sg (Singapore) /pub/zi/TeX src.doc.ic.ac.uk (England) /packages/tex/uk-tex sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX wuarchive.wustl.edu (Missouri, USA) /packages/TeX Other nodes and directories of interest include: Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ 6. What is Literate Programming? Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system pro- grammer, who wants to provide the best possible documenta- tion of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To docu- ment such a program we want to explain each individual part of the web and how it relates to its neighbours. The typo- graphic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combin- ing the two, we can develop a style of programming that max- imizes our ability to perceive the structure of a complex piece of software, and at the same time the documented pro- grams can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why. Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM ref. 1 plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References 1 Paul W. Oman and Curtus Cook. ``Typographical style is more than cosmetic.'' CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called ``informal rigour'', i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 Another author (Norman Ramsey) wrote me and asked that his opinions be included in the FAQ. What follows are Norman's comments verbatim. I see it's time for the ``how is literate programming dif- ferent from verbose commenting'' question. Perhaps David Thompson will get this into the FAQ. Alert! What follows are my opinions. In no way do I claim to speak for the (fractious) literate-programming community. How is literate programming different from verbose commenting? There are three distinguishing characteristics. In order of importance, they are: o flexible order of elaboration o automatic support for browsing o typeset documentation, especially diagrams and mathematics Flexible order of elaboration means being able to divide your source program into chunks and write the chunks in any order, independent of the order required by the compiler. In principle, you can choose the order best suited to explaining what you are doing. More subtly, this discipline encourages the author of a literate program to take the time to consider each fragment of the program in its proper sphere, e.g., not to rush past the error checking to get to the ``good parts.'' In its time and season, each part of the program is a good part. (This is the party line; your mileage may vary.) I find the reordering most useful for encapsulating tasks like input validation, error checking, and printing output fit for humans --- all tasks that tend to obscure ``real work'' when left inline. Reordering is less important when using languages like Modula-3, which has exceptions and permits declarations in any order, than when using languages like C, which has no exceptions and requires declaration before use. Automatic support for browsing means getting a table of contents, index, and cross-reference of your program. Cross-reference might be printed, so that you could consult an index to look up the definition of an identifier `foo'. With good tools, you might get a printed mini-index on every page if you wanted. Or if you can use a hypertext technology, cross-reference might be as simple as clicking on an identifier to reach its definition. Indexing is typically done automatically or `semi- automatically', the latter meaning that identifier definitions are marked by hand. Diligently done semi- automatic indexes seem to be best, because the author can mark only the identifiers he or she considers important, but automatic indexing can be almost as good and requires no work. Some tools allow a mix of the two strategies. Some people have applied literate-programming tools to large batches of legacy code just to get the table of contents, index, and cross-reference. I don't use diagrams and mathematics very often, but I wouldn't want to have to live without them. I have worked on one or two projects where the ability to use mathematical formulae to document the program was indispensible. I also wouldn't like to explain some of my concurrent programs without diagrams. Actually I write almost all of my literate programs using only sections headers, lists, and the occasional table. >Wouldn't it be easier to do one's literate programming using >a wysiwyg word processor (e.g. Word for Windows) and >indicate what is source code by putting it in a different >font? The data formats used in wysiwyg products are proprietary, and they tend to be documented badly if at all. They are subject to change at the whim of the manufacturer. (I'll go out on a limb and say there are no significant wysiwyg tools in the public domain. I hope the Andrew people will forgive me.) These conditions make it nearly impossible to write tools, especially tools that provide automatic indexing and cross-reference support. The CLiP people have a partial solution that works for tools that can export text --- they plant tags and delimiters throughout the document that enable the reordering transformation (``tangling''). People use TeX, roff, and HTML because free implementations of these tools are widely available on a variety of platforms. TeX and HTML are well documented, and TeX and roff are stable. TeX is the most portable. I think I have just answered the FAQ ``how come all these tools use TeX, anyway?'' :-) Norman Ramsey 7. How do I begin literate programming? A recommended book is D.E. Knuth's collection of articles (1992) Literate Programming. Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) Weaving a Program: Literate Programming in WEB. Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. 8. What literate programming tools are available? A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) 8.1. APLWEB Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. 8.2. AWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. 8.3. CLiP Developer: E.W. van Ammers and M.R. Kramer Versions: 2.0 and 2.4b (DOS only) Platform: Vax/VMS, Unix, DOS Languages: Any programming language Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, WinWord, Ami Pro, Word Pro, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos DOS sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b) sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS sun01.info.wau.nl:/CLIP/unix Unix CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicit commands to perform the extraction process. Rather it recognizes pseudostatements written as comments in the programming language in question. CLiP distinguishes pseudostatements from ordinary comments because the former comply with a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well. Some hypertext examples are at ftp://sun01.info.wau.nl/clip/html/queens.htm ftp://sun01.info.wau.nl/clip/html/pal1.htm Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentation my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segments. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail to Eric.vanAmmers@user.info.wau.nl 8.4. CWEB Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu 8.5. CWEBx3.0 Developer: Marc van Leeuwen Version: Unknown Hardware: Any system using ASCII code Languages: ANSI C Formatter: Plain TeX Availability: Anonymous ftp from: ftp.cwi.nl/pub/cweb Readme: Bundled with above Brief description: A modified implementation of CWEB, with some extensions. Provides a mode for full compatibility with Levy/Knuth CWEB. The most significant extras are: - Typedef declarations affect formatting througout source file - Include files are scanned for typedef definitions - Flexible selection of layout style - Possibility to refer to sections using symbolic labels - CTANGLE detects unbalanced braces and parentheses - CWEAVE can be made to report syntax errors more easily - Some additional mechanisms to avoid formatting problems - New and modular set of grammar rules, based on ANSI C syntax - Possibility to suppress #line directives - A new manual Support: bugs and remarks to M.van.Leeuwen@cwi.nl 8.6. mCWEB Developer: Markus Oellinger Version: 1.0 Hardware: Unix Languages: C/C++ Formatter: plainTeX Availability: anonymous ftp from ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz Readme: at same location Description: This is mCWEB 1.0, a descendant of the CWEB system of structured documentation by Donald E. Knuth and Silvio Levy. It adds some features that are indispensable when working in a team. mCWEB regards a project of a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface documentation is now also part of mCWEB. It is extracted into a second TeX file. This makes it possible to define well known interfaces between the individual parts of a project that will be implemented by different persons. In addition, mCWEB parses C header files to find out about all the datatypes defined there. mCWEB comes with a full completely rewritten user manual and is compatible with CWEB. Support: Institute of Software Technology moell@ist.tu-graz.ac.at 8.7. FunnelWeb Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. 8.8. FunnelWeb 3.0AC Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au) from FunnelWeb v3.0 by Ross N. Williams (ross@guest.adelaide.edu.au) Version: 3.0AC Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2. Languages: No restrictions. Formatter: Tex, LaTeX, or HTML. Availability: Anonymous ftp from ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz Readme: With bundle above; for FunnelWeb manual see WWW page http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html Description: FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry for FunnelWeb). FunnelWeb is designed to be typesetter independent, though FunnelWeb v3.0 only supports (La)TeX as the typesetter. FunnelWeb 3.0AC also supports HTML, and creates appropriate hypertext links within the document among the code sections. FunnelWeb 3.0AC also supports automatic and manual insertion of line directives, so that compiler errors can be flagged back to the original FunnelWeb source file. FunnelWeb 3.0AC is completely compatible with FunnelWeb v3.0 sources (with one minor exception; see the file README.ABC which comes with the FunnelWeb 3.0AC distribution). Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject to the time constraints imposed by his thesis. 8.9. FWEB Developer: John A. Krommes Version: 1.53 (1.60-beta for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: LaTeX. Plain TeX may work, but is no longer supported. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu 8.10. IMPACT Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. 8.11. lit2x Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown 8.12. Literate Programmer's Workshop (LPW) Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. 8.13. MapleWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown 8.14. MWEB (Schrod/Detig) Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.15. MWEB (Sewell) Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.16. noweb Developer: Norman Ramsey Version: 2.8 Hardware: Unix and DOS platforms (DOS binaries available for v2.7). Languages: All programming languages, singly or in combination. Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc Formatter: Plain TeX, LaTeX, and HTML formatters. Will convert LaTeX to HTML automatically. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent Last recourse, use ftp.cs.virginia.edu:pub/nr Readme: With bundle above, or see the noweb home page: http://www.cs.virginia.edu/~nr/noweb Those without ftp access can consult ``Literate Programming Simplified,'' IEEE Software, September 1994, pp97-105. Description: noweb is designed to meet the needs of literate programmers while retaining the simplest possible input format. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 3 pages; an additional page explains how to customize its LaTeX output. noweb works ``out of the box'' with any programming language, and supports TeX, latex, and HTML back ends. A back end to support full hypertext or indexing takes about 250 lines; a simpler one can be written in 40 lines of awk. The primary sacrifice relative to WEB is that code is not prettyprinted. noweb supports indexing and identifier cross-reference, including hypertext ``hot links.'' noweb includes a simple, efficient LaTeX-to-HTML converter, so you can use hypertext browsers on your legacy documents. noweb can also process nuweb programs, so you can use noweb to convert a standard nuweb program to HTML with one command. Support: email to the author 8.17. nuweb Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu 8.18. ProTeX Developer: Eitan Gurari Version: ProTeX 1.1, AlProTeX 1.4 Hardware: Any platform with (La)TeX Languages: Any language Formatter: TeX or LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: With bundle above Description: + Easy to use + Extensible + Language independent + Multiple output files + Fast (single compilation provides output and dvi files) + No installation is needed besides copying the files (written in TeX) Introduction of main features and examples in pub/tex/osu/gurari/LitProg Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and Literate Programming", McGraw-Hill, 1994 Support: gurari@cis.ohio-state.edu 8.19. RWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown 8.20. SchemeWEB Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. 8.21. SpideryWEB Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. 8.22. WEB Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. 8.23. WinWordWEB Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. 9. Are there other tools I should know about? First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. 9.1. C2LaTeX Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. 9.2. c2cweb Developer: Werner Lemberg Version: 1.5 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg 9.3. c2man language: C, nroff, texinfo, latex, html package: c2man version: 2.0 patchlevel 33 parts: documentation generator (C -> nroff -man, -> texinfo, ->latex, -> html) author: Graham Stoney location: ftp from any comp.sources.misc archive, in volume42 (the version in the comp.sources.reviewed archive is obsolete) ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from archie.au N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from ftp.wustl.edu Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* from ftp.irisa.fr Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* from ftp.iij.ad.jp Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se description: c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. conformance: supports both K&R and ISO/ANSI C coding styles features: + generates output in nroff -man, TeXinfo, LaTeX or HTML format + handles comments as part of the language grammar + automagically documents enum parameter & return values + handles C (/* */) and C++ (//) style comments - doesn't handle C++ grammar (yet) requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX. ports: Unix, OS/2, MSDOS, VMS. portability: very high for unix, via Configure status: actively developed; contributions by users are encouraged. discussion: via a mailing list: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au help: from the author and other users on the mailing list: c2man@research.canon.oz.au announcements: patches appear first in comp.sources.bugs, and then in comp.sources.misc. updated: 1994/10/07 9.4. cnoweb Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. 9.5. Fold2Web Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de 9.6. Funnelweb Mode Developer: Daniel Simmons Version: Unknown Availability: http://www.miscrit.be/~ddw Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown 9.7. noweb.el Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk 9.8. nuweb.el Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@acm.org 9.9. TIE Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown 9.10. Web mode Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown 10. What other resources are available? 10.1. World Wide Web An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html or use a WWW browser and access the URL ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to rtfm.mit.edu and retrieve the official Usenet resource file /pub/usenet/news.answers/www/resources/literate-programming 10.2. TeX Resources Another resource of interest to literate programmers is the comp.text.tex newsgroup. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this resource. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. 11. Are there any code examples? Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au 129.127.40.3 as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: ftp://samson.kean.edu/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is writ- ten in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb 12. Bibliographies Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu 128.110.198.2 in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says sev- eral times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. 13. How to anonymously ftp Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu 18.181.0.24, under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. 14. Acknowledgements This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. 15. End notes This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. 7-Aug-1998 2:32:03-GMT,2501;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id UAA21798 for ; Thu, 6 Aug 1998 20:32:03 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 06 Aug 1998 21:24:02 EST From: C M Sperberg-McQueen Reply-To: LitProg@SHSU.edu, cmsmcq@uic.edu Subject: Re: XML for literate programming? Date: 7 Aug 1998 02:09:17 GMT Message-ID: <6qdnkd$bq8$1@news.interlog.com> To: LitProg@SHSU.edu ghauber@cch.com.au writes: > In article <6p9bpd$aao$1@elna.ethz.ch>, > Martin Harvey wrote: > > > Has anyone thought about using XML (and a suitably defined set of tags) > > for use in LP. Would this have any advantages over current LP systems > > (about which I confess I know very little)? > > I, too, am interested in this (and have read the FAQ). Our documentation > here at work is woefully inadequate, and after thinking about it for a while > I decided that using XML and a related set of tools would be quite worthwile, > however I have not found anything yet out there that does this. > > Being very new to the area, I'm reluctant to just jump into implementing my > own system, so any discussion and/or information on this would be muchly > appreciated. Well, yes and no. There have a been a number of proposals for SGML-based literate programming, and I have been using one such system for several years; the short summary of the experience is yes, structured markup and literate programming are an obvious match, and the combination works very well. There is no reason it would not work equally well in an XML environment. Robin Cover's SGML/XML Web Page has an article on the topic at http://www.sil.org/sgml/xmlLitProg.html which has references. To see the definitions of the tag set and the processor I have been using, follow the links for Sweb. On the other hand, I don't think there are any existing SGML-based systems that are as fully implemented, provide as many convenience features, or have as many cooperating helper tools as some of the other more mature LP systems. -- -C. M. Sperberg-McQueen Senior Research Programmer, University of Illinois at Chicago Editor, ACH/ACL/ALLC Text Encoding Initiative Co-coordinator, Model Editions Partnership 8-Aug-1998 6:26:52-GMT,2822;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id AAA28885 for ; Sat, 8 Aug 1998 00:26:51 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 08 Aug 1998 01:18:46 EST From: "Anthony B. Coates" Subject: Re: XML for literate programming? Date: 7 Aug 1998 02:07:09 GMT Message-ID: <6qdngd$npq$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, "Anthony B. Coates" To: LitProg@SHSU.edu > > Has anyone thought about using XML (and a suitably defined set of tags) > > for use in LP. Would this have any advantages over current LP systems > > (about which I confess I know very little)? > > > > MH. > > > > I, too, am interested in this (and have read the FAQ). Our documentation here > at work is woefully inadequate, and after thinking about it for a while I > decided that using XML and a related set of tools would be quite worthwile, > however I have not found anything yet out there that does this. I am working (albeit rather slowly) on developing a framework that will allow you use an existing XML parser (there are so many now that you would be crazy to write your own without a very specific reason). Shortly, I hope to release some code with parsing and output, but waiting for a LitProg engine core to be plugged in. It is being done using a JavaBeans approach that allows each component to be replaced. In the meantime, have a look at which documents my thoughts to date. There is also a mailing list, albeit an enormously low traffic one (makes "comp.literate.programming" look busy ...). While I'm at it, note that the Web site hosting these pages may have to change in a month or two, but I provide details of that later as I know more myself. Cheers, Tony. -- Educational Multimedia Services = reduced workloads for lecturers, teachers, and tutors = better results for students. (contact "info@ems.uq.edu.au" for details) -- Another 100% Pure Java e-mail. Is yours? -- Anthony B. Coates. Multimedia Developer (Software Design) Educational Multimedia Services TEDI, The University of Queensland. AJUG-QLD Steering Committee Member (Australian Java Users' Group ). QMUG Committee Member (Queensland Macromedia Users' Group ). E-mail: tony@ems.uq.edu.au WWW: http://www.ems.uq.edu.au/People/Tony/ UIN: 5191015 -- All opinions are mine, and may not represent those of The University of Queensland. -- Posted Using: J Street Mailer (build 98.6.3) 8-Aug-1998 20:00:07-GMT,1577;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id OAA11632 for ; Sat, 8 Aug 1998 14:00:06 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 08 Aug 1998 14:44:14 EST From: ghauber@cch.com.au Reply-To: LitProg@SHSU.edu, ghauber@cch.com.au Subject: Re: XML for literate programming? Date: 6 Aug 1998 15:50:12 GMT Message-ID: <6qcjbk$6sp$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6p9bpd$aao$1@elna.ethz.ch>, Martin Harvey wrote: > > Has anyone thought about using XML (and a suitably defined set of tags) > for use in LP. Would this have any advantages over current LP systems > (about which I confess I know very little)? > > MH. > I, too, am interested in this (and have read the FAQ). Our documentation here at work is woefully inadequate, and after thinking about it for a while I decided that using XML and a related set of tools would be quite worthwile, however I have not found anything yet out there that does this. Being very new to the area, I'm reluctant to just jump into implementing my own system, so any discussion and/or information on this would be muchly appreciated. Gabriel -----== Posted via Deja News, The Leader in Internet Discussion ==----- http://www.dejanews.com/rg_mkgrp.xp Create Your Own Free Member Forum 8-Aug-1998 23:39:12-GMT,1215;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id RAA15388 for ; Sat, 8 Aug 1998 17:39:11 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 08 Aug 1998 18:36:00 EST From: stuart1@inyokohama.com (Stuart Woodward) Reply-To: LitProg@SHSU.edu, stuart1@inyokohama.com Subject: [Win32] Visual C++ IDE Date: 8 Aug 1998 01:20:57 GMT Message-ID: <6qg95p$sf1$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Like many others, I find that I spend most of my days sitting in front of the Visual C++ Development Studio. What I'd really love is a Visual Literate Programming Tool that would integrate with the Development Studio and let me write and see my code in a literate way and then also be able to debug the raw C++. I guess the literate view would be like an outliner. I wonder if my dream programming environment will ever come true... 10-Aug-1998 0:42:22-GMT,8276;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id SAA10644 for ; Sun, 9 Aug 1998 18:42:21 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 09 Aug 1998 19:36:59 EST From: Greg McFarlane Reply-To: LitProg@SHSU.edu, gregm@nms.otc.com.au Subject: Interscript: a first look Date: 10 Aug 1998 00:32:14 GMT Message-ID: <6qlf2f$nnb$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu I have just had a first look at John Skaller's interscript system and I would like to pass on my impressions. In summary, it is definitely worth having a look at if you are interested in the production of quality software. First, check out the Interscript tutorial: http://www.triode.net.au/~skaller/interscript/iscru.html and the Interscript design and source documentation: http://www.triode.net.au/~skaller/interscript/iscrs.html Then download the tar file ftp://ftp.triode.net.au/skaller/interscript.tar.gz and build interscript. You can also have a look at a proposal for a new way of downloading, building, installing and updating software: http://www.triode.net.au/~skaller/interscript/iscrdown.html All the documentation on the www site is also generated when you build interscript from the tar file, so it may be easier to download first then read the generated copy of the documentation. The Interscript home page is: http://www.triode.net.au/~skaller/interscript/ Interscript tries to be many things, but mainly it is Literate Programming system. What is Literate Programming? ----------------------------- To put it in a nutshell, Literate Programming is a method of creating and maintaining source (C, C++, python, data, etc) and documentation. It is much more than putting in comments and doc strings in your modules and functions. It enables the programmer/author to write code as if she is explaining the code to someone else. The logic of the explanation determines the ordering of the code and documentation, not the rules of the language. I first met Literate Programming several years ago when I was given the job of adding Japanese language capability to the Metafont program, written by Donald Knuth. The Metafont "source" comes like a book, with chapters and sections, etc. All I had to do was find the bit in the book that dealt with character representation, modify the code that was contained in that section, then run the source through a "tangler" to produce the compilable source code (Pascal if I remember correctly). I was very impressed with it. The first part of the book gave an overview of the program and then, using the index, it was relatively easy to jump to relevant parts of the book. Whenever the explanation introduced a new idea, the concept was described and then the relevant code fragments were presented. The code fragments may have been taken from different parts of the finished program. For example, the declaration of a variable may be given along with the code where it is used. So the question now might be, "Why haven't I seen Literate Programming used much in the 10 years since then?" Why hasn't it taken off and become more popular? One reason perhaps might be that Literate Programming was originally written for Pascal. Two of the problems with early versions of Pascal were that programs had to be written as one file and you had to define everything before you used it. These resulted in huge programs where the variable declaration and low level functions were at the top of the file and the main program and other high level functions were at the bottom. If you wanted to explain to someone how the program worked, you would generally scroll to the bottom of the file and begin by discussing the high level parts of the program. As necessary you would look at other, more detailed, parts of the program as they became relevant to the discussion. What Literate Programming did was to allow you to write the source in the same order that you would use to explain the program and also include the discussion with it. However, programming languages are now quite different to Pascal - the ordering within a file is more flexible and often the program is divided into self-contained modules, in separate files. Here, two kinds of documentation become important - documenting the interface to, and behaviour of, a module, and documenting the implementation of the module. Literate Programming is really only relevant to the documentation of the implementation. A second reason may be the initial effort involved in writing literate programs. Without Literate Programming, you can "get away with" writing minimal implementation documentation (as most of us do). The initial construction of a literate program will probably take longer. One of the main points of Literate Programming is that literate programs are written to be read by a human, not by a machine. But in much of my experience, the great majority of code is only ever read by the (human) writer and the compiler. Often, if a program works, it is left "as is" for years. So you have to weigh up whether the investment in time now to properly document the code will be returned in the future when the documentation is read. One strength of Literate Programming is that, since the documentation is right next to the code, the documentation "should" be always up to date. However, it does not force programmers to keep the documentation up to date and in this sense, the more documentation you have the more likely it is to be out of date. For more information about Literate Programming, see the comp.programming.literate newsgroup. Interscript as a Literate Programming tool ------------------------------------------ One of the interesting points about Interscript as a Literate Programming tool is that its control language is python. This means that an Interscript source script can not only produce (say) HTML documentation of (say) a C program, but the source can contain python code which "writes" the C code. This is useful when the C output code needs to contain repetitive text - the Interscript source only needs to contain one copy of the text and the scripting capabilities of python can be used to generate the duplicated output. Also, code can be conditionally generated in a more powerful way than by using C's #ifdef control structures. One criticism I have of the Interscript documentation is that it mixes up user documentation with the source code documentation. In most cases, the target audiences for these two types of document are very different - the user is not interested in the inner workings of the program. This lack of distinction makes being able to use Interscript more difficult. There is a lot of documentation, but it is sometimes hard for end users to find the bits they need. For example, the full list of Interscript commands available to the user is not described until section 4.9.1 of the Interscript source code document and even there they are not described in full. The system also needs some regression tests which are applied before a release. The version I had did not work on the supplied examples until I had made a few fixes. The source code description could also do with a simple high level diagram describing the relationship between the input files, input sources, the parser, the weavers (including multiplex weavers and markup filtering weavers), the stack of tanglers and the sinks. The high level relationships are fairly straightforward, but a diagram would make the descriptions clearer. Interscript will be good for authors who want to publish their code not just to be compiled and executed, but also to be read. Interscript is worth looking at. The design is clean and easy to understand after reading the documented version of the program. For more information about the Python language, see the comp.lang.python newsgroup. 10-Aug-1998 9:21:05-GMT,2687;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id DAA20148 for ; Mon, 10 Aug 1998 03:21:05 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 10 Aug 1998 04:11:59 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: [Win32] Visual C++ IDE Date: 9 Aug 1998 13:33:00 GMT Message-ID: <6qk8ec$dcu$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 8 Aug 1998, Stuart Woodward wrote: > Like many others, I find that I spend most of my days sitting in front > of the Visual C++ Development Studio. > > What I'd really love is a Visual Literate Programming Tool that would > integrate with the Development Studio and let me write and see my code > in a literate way and then also be able to debug the raw C++. This would be at least somewhat possible if the Development Studio allowed one to add preprocessor rules for the project file. I understand that it is *supposed* to be possible, but I was never able to figure out how in the Microsoft environment. On the other hand, I *was* able to do the same thing with the Borland C++ IDE. I created rules that transformed .w and .nw files into .c (and .cpp) files, and was able to (pretty much) integrate CWEB and noweb into the environment. The #lines generated by the LP tools meant that all error messages and debugging was in the .w and .nw files. If you wanted to be able to view the woven source, you could run LaTeX as well, and keep a dvi viewer running (or, in the case of noweb, generate html instead and use your web browser). > I guess the literate view would be like an outliner. > > I wonder if my dream programming environment will ever come true... I believe we discussed the issue of "belling the cat" some time ago in this forum. The one who has the idea should be willing to (at least try to) make it reality. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | "There's plenty of stories that need Computer Science Department | telling what never get told, just because Kean University | people can't bear the listening." Union, NJ 07083 | | -- Caleb Carr leew@samson.kean.edu | "The Angel of Darkness" (1997) ------------------------------------------------------------------------ 10-Aug-1998 23:32:38-GMT,4777;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id RAA08737 for ; Mon, 10 Aug 1998 17:32:37 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 10 Aug 1998 18:12:11 EST From: postmaster@127.0.0.1 (Benoit Goudreault-Emond) Subject: Re: [Win32] Visual C++ IDE Date: 10 Aug 1998 01:58:16 GMT Message-ID: <6qlk3o$t3h$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, postmaster@127.0.0.1 To: LitProg@SHSU.edu In article <6qldee$qor$1@murdoch.acc.Virginia.EDU>, Anthony B. Coates wrote: > ** Reply to note from Lee Wittenberg on 1998/08/09 > > > On the other hand, I *was* able to do the same thing with the Borland > > C++ IDE. I created rules that transformed .w and .nw files into .c > > (and .cpp) files, and was able to (pretty much) integrate CWEB and > > noweb into the environment. The #lines generated by the LP tools > > meant that all error messages and debugging was in the .w and .nw > > files. If you wanted to be able to view the woven source, you could > > run LaTeX as well, and keep a dvi viewer running (or, in the case of > > noweb, generate html instead and use your web browser). > > Note though that there may still be the problem that if you use a debugger, you > may find that it chokes on the out-of-order #line directives in the tangled > sources. At least, that was my previous experience with gdb. I'm not sure if > debuggers have improved their #line support since then, since I'm not sure that > anything else besides LitProg tools pushes #line usage to such limits. Never had a problem with gdb, nor with the VC++ debugger. Don't know about the BC++ debugger. I don't know if gdb got better since you tried it, but I've used it under Linux and Win32 (using the Mingw32 compiler/tools, within emacs for NT). In addition, LP makes the debugger relatively unused (well, not completely, but I don't really rely on it anymore when I use LP). To answer a question from Lee Wittenberg, regarding how to use the literate programming tools in the VC++ environment, I've sort of managed it with a copy of noweb. Basically, the idea is to include the .nw (or .w, or whatever) file in your project. Then, in the FileView tab, right-click on the file and choose Settings. Here, you can select a "custom build step" which will call your LP tools. Unfortunately, you must also list *all* the files that are being generated from the web file so dependencies work properly (you must specify at least one file in the dialog box, anyhow, or it doesn't let you do anything). Unfortunately, the thing recompiles *all* the .c files, even if I use noweb's cpif to make sure some things are not refreshed. You can get it not to do this by selecting an incremental link, but sometimes, that's not an option. I personally don't understand how they figure dependencies out, or how they "know" they need a recompile in that compiler, and I'd really like to know that. The program I'm using this with uses C++ templates heavily and that hits compile time quite dramatically, I'm afraid. :{( As for the HTML docs, you can just add a new tool to the Tools menu that calls you weaver. That works OK. You could also include that in the custom build step, but the current system is slow enough as is due to the fact that my noweb build is quite a bit bastardized (parts are Win32 executables, and the icon parts are DOS 386 executables because I can't get the native executables to read pipes. Groan.) The moral of this story: stick with makefiles if you can. If you can't, it can work, but it'll be merely satisfactory. That, plus the fact that the VC++ editor isn't suited for LP editing at all (it's possible to rebind keys, but I miss the context sensitive highlighting of emacs's noweb mode which switches between the major mode for docs and the one for code as you move around), plus the fact that my co-workers are not necessarily too happy to have to wade through the documentation as well as the code, does not encourage me to use this process for future projects, except when clarity and correctness of design is critical. I hope this helps someone out there. -- Benoit Goudreault-Emond CoFounder, KMS Group ; Student, B. Comp. Eng, Concordia University ``Being too close to a fireball can worry a man --- to death.'' -- Zeb Carter in "The Number of the Beast" by Robert A. Heinlein Note: the "From:" address is not correct to protect myself against spam. My actual e-mail address is: ``bgoudem AT axess DOT com'' 11-Aug-1998 3:45:08-GMT,1968;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id VAA13675 for ; Mon, 10 Aug 1998 21:45:07 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 10 Aug 1998 22:40:27 EST From: Devon Prichard Reply-To: LitProg@SHSU.edu, d.s.prichard@larc.nasa.gov Subject: Re: Interscript: a first look Date: 11 Aug 1998 01:33:55 GMT Message-ID: <6qo723$cfu$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Greg McFarlane wrote: > > One criticism I have of the Interscript documentation is that > it mixes up user documentation with the source code > documentation. In most cases, the target audiences for these > two types of document are very different - the user is not > interested in the inner workings of the program. This lack of > distinction makes being able to use Interscript more > difficult. There is a lot of documentation, but it is > sometimes hard for end users to find the bits they need. For > example, the full list of Interscript commands available to > the user is not described until section 4.9.1 of the > Interscript source code document and even there they are not > described in full. is it possible to create some sort of automatic index generator that would find all user-doc sections and create some sort of hyperlinked TOC or index? --------------------------------------------------------------------------- Dr. Devon Prichard, Lockheed Martin d.s.prichard@larc.nasa.gov Applying computer technology is simply finding the right wrench to pound in the correct screw. --------------------------------------------------------------------------- 11-Aug-1998 14:50:02-GMT,2489;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id IAA17490 for ; Tue, 11 Aug 1998 08:50:01 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 11 Aug 1998 09:43:02 EST From: "Anthony B. Coates" Subject: Re: [Win32] Visual C++ IDE Date: 10 Aug 1998 00:04:30 GMT Message-ID: <6qldee$qor$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, "Anthony B. Coates" To: LitProg@SHSU.edu ** Reply to note from Lee Wittenberg on 1998/08/09 > On the other hand, I *was* able to do the same thing with the Borland > C++ IDE. I created rules that transformed .w and .nw files into .c > (and .cpp) files, and was able to (pretty much) integrate CWEB and > noweb into the environment. The #lines generated by the LP tools > meant that all error messages and debugging was in the .w and .nw > files. If you wanted to be able to view the woven source, you could > run LaTeX as well, and keep a dvi viewer running (or, in the case of > noweb, generate html instead and use your web browser). Note though that there may still be the problem that if you use a debugger, you may find that it chokes on the out-of-order #line directives in the tangled sources. At least, that was my previous experience with gdb. I'm not sure if debuggers have improved their #line support since then, since I'm not sure that anything else besides LitProg tools pushes #line usage to such limits. Cheers, Tony. -- Educational Multimedia Services = reduced workloads for lecturers, teachers, and tutors = better results for students. (contact "info@ems.uq.edu.au" for details) -- Another 100% Pure Java e-mail. Is yours? -- Anthony B. Coates. Multimedia Developer (Software Design) Educational Multimedia Services TEDI, The University of Queensland. AJUG-QLD Steering Committee Member (Australian Java Users' Group ). QMUG Committee Member (Queensland Macromedia Users' Group ). E-mail: tony@ems.uq.edu.au WWW: http://www.ems.uq.edu.au/People/Tony/ UIN: 5191015 -- All opinions are mine, and may not represent those of The University of Queensland. -- Posted Using: J Street Mailer (build 98.6.3) 13-Aug-1998 18:01:26-GMT,1997;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id MAA16423 for ; Thu, 13 Aug 1998 12:01:25 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from brussel.planetinternet.be by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 13 Aug 1998 12:41:13 EST Received: from ubnd-28.pop-gent.planetinternet.be (ubnd-28.pop-gent.planetinternet.be [194.119.236.28]) by brussel.planetinternet.be (8.9.1a/8.9.1) with SMTP id TAA10776; Thu, 13 Aug 1998 19:40:26 +0200 (MET DST) Message-ID: <199808131740.TAA10776@brussel.planetinternet.be> From: "=?iso-8859-0?q?J=81rgen_Defurne?=" To: "Anthony B. Coates" , "LitProg@SHSU.edu" Date: Thu, 13 Aug 98 19:32:59 Reply-To: LitProg@SHSU.edu, "=?iso-8859-0?q?J=81rgen_Defurne?=" MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Subject: Re: [Win32] Visual C++ IDE Content-Transfer-Encoding: 7bit On 10 Aug 1998 00:04:30 GMT, Anthony B. Coates wrote: >Note though that there may still be the problem that if you use a debugger, you >may find that it chokes on the out-of-order #line directives in the tangled >sources. At least, that was my previous experience with gdb. I'm not sure if >debuggers have improved their #line support since then, since I'm not sure that >anything else besides LitProg tools pushes #line usage to such limits. > I must depend on the debugger. I use fweb under OS/2 for WATCOM C++. Their debugger doesn't have any problems using literate listings. One thing that may be taken in account : do not optimize code when debugging. All manuals that I've come across on debuggers emphasize this. Jurgen Defurne jurgen.defurne@scc.be 14-Aug-1998 14:43:26-GMT,1056;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id IAA02310 for ; Fri, 14 Aug 1998 08:43:25 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from mstr.rh.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 14 Aug 1998 09:37:08 EST Received: from rh.edu (rli04-p.hgc.edu [129.5.64.89]) by mstr.rh.edu (8.8.8/8.8.8/RHGC-1.8) with ESMTP id KAA02853 for ; Fri, 14 Aug 1998 10:37:05 -0400 (EDT) Message-ID: <35D44BC7.BF69C80E@rh.edu> Date: Fri, 14 Aug 1998 10:37:59 -0400 From: C Custer Reply-To: LitProg@SHSU.edu, custer@rh.edu MIME-Version: 1.0 To: LitProg@SHSU.edu Subject: (no subject) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Did you find any info on this subject ? I am looking for exactly the same information. Thank you! Cynthia custer@rh.edu 16-Aug-1998 8:39:49-GMT,7265;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id CAA09179 for ; Sun, 16 Aug 1998 02:39:48 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from relay1.UU.NET by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 16 Aug 1998 03:34:39 EST Received: from x by relay1.UU.NET with SMTP (peer crosschecked as: 1Cust2.tnt13.nyc3.da.uu.net [153.37.139.2]) id QQfcqs09806; Sun, 16 Aug 1998 04:33:22 -0400 (EDT) Date: Sun, 16 Aug 1998 04:33:22 -0400 (EDT) From: learnwhere@hotmail.com Reply-To: LitProg@SHSU.edu, learnwhere@hotmail.com Message-ID: Subject: They Can Even Steal Your Identity! ARE YOU BEING INVESTIGATED? Has your personal and credit information been stolen? Has someone assumed your identity? Would you like to locate an old friend, relative, military buddy or sweetheart? Do you want to find a person's assets to collect a debt or judgement? Would you like to check a person's criminal record before renting them space or giving them employment? Would you like to fix up your credit bureau report, create a new identity or even disappear? Are you going to have surgery? Would you like to know how many malpractice suits have been filed against your doctor? Now you can learn all this plus much, much more with our brand new 45 page report "INTERNET SLEUTH"! Learn the Internet tools and resources that are used to investigate you, your relatives, friends, neighbors, enemies, employees or anyone else! We will give you thousands of Internet locations to look up people, credit, social security, current or past employment, driving records, criminal records, medical information, military records, addresses, phone numbers, immigration, divorce, labor and criminal laws! We will also give you sources to find missing children and parents, hazardous waste sites, how to do Freedom of Information Act information searches, how to do skip tracing and backround checks on prospective dates, brides or grooms, employees, renters, vendors, new clients and competitors! You will also learn about and where to get surveillance and spy devices, private mail forwarding and annonymous email forwarding sites, search for copyrights, patents and court cases and how to make your assets untraceable! We will show you how to get copies of credit reports, adoption databases, information on drugs, poisons and how to get your share of government programs and benefits! Can you find this information by using the Internet Search Engines? The answer is MAYBE if you get lucky and if you want to spend many hours going through 25,000 plus hits per subject! We and our staff have spent hundreds of hours and many thousands of dollars compiling this information for you! Now you can have it on a silver platter for LESS THAN TWENTY BUCKS during this special email promotion! You frequently hear over the media, television, radio, the newspapers, how personal information is being used, traded and sold over the Internet...usually without your permission or knowledge. Our report will show you HOW IT IS DONE!!! Would you like to find that old romantic flame...find telephone, address or email information on almost anyone...even unlisted phone numbers? How about your family "tree"? We will teach you how to turn years of work into hours of fun! Military? Check Army, Navy, Air Force and Marine records. extensive Vietnamese war records, MIA info, much more! Looking for a job? Find the job you are seeking...even in another state or another country! We will teach you how! Looking for a new love interest or spouse or even sex partner? We will show you where to look for fast results! Want up-to-the-minute health and medical information? Learn how to cure fears and phoebias, the latest drugs and treatments for almost any ailment or desease from the drug companies themselves as well as from universities and the Center for Desease Control. Want to learn the most effective way to loose weight? It's all here in our report! If you believe that the information compiled about you should be as available to you as to the people that compile it about you without your knowledge or permission than you must order "THE INTERNET SLEUTH REPORT" immediately! Our "INTERNET SLEUTH REPORT" is normally sold by direct mail for $39.95 and will soon be in book stores for $29.95. However, to generate publicity and "get the word out" we are making this 10 day Email Special Offer of our Complete 45 Page Report for only $19.95 plus $3 for shipping and handling [total $22.95]. Sold with our 10 Day Money Back Guarantee! This is the biggest bargain on the Internet and the information it will give to you will give you great power! It can really change your life in a positive way. Order Now! The Complete 45 page "INTERNET SLEUTH REPORT" only $19.95 plus $3 shipping and handling - total $22.95. Shipped in plain wrapper by First Class Mail. Add $5 for priority mail delivery. Add $20 for overnight Express! We accept Visa, MasterCard, American Express or Discover. We can also accept your check by phone or Fax. You may order by phone 9 am to 10 pm [NY Time] by phoning [718] 287-3800 You may order by fax 24 hours per day by phoning our fax line at [718] 462-5920. You can fax your credit card information or your check To Email your order - DO NOT HIT REPLY ON YOUR KEYBOARD Send email to our special email address below: moreinfo26@juno.com [Note: If you order by email and do not receive an email confirmation within 24 hours, please phone our office at 718-287-3800] You can also order by mail by sending $22.95 cash, check, money order or major credit card [Visa, MasterCard, American Express or Discover] to TCPS, INC. 4718 18th Ave. Suite 135 Brooklyn, NY 11204 Make Checks & Money Orders Payable to TCPS, Inc. New York State Residents Please Add $1.70 for Sales Tax The Following Order Form is for Your Convenience! Use it by Mail, Fax or Email! ............................................................................................................. Please ship me ________copies of the INTERNET SLEUTH Report at $19.95 each plus $3.00 for shipping and handling [$22.95] Signature______________________________________________ Credit Card #____________________________Exp date______ Ship to: Name_________________________________________ Address________________________________________________ City________________________State___________Zip________ Area Code and Home Phone [ ]___________________________ Fax # [ ]______________________________________________ Email Address___________________________________________ To remove your name from our mailing list, send us an email with remove in the subject line. This is a one time offer and you should not hear from us again! TCPS,Inc., 4718 18th Ave., Suite 135, Brooklyn, NY 11204 Office [718] 287-3800 Fax [718] 462-5920 24 hours [9am to 10pm NY Time] [c] Copyright 1998 TCPS, Inc. All Rights Reserved. 17-Aug-1998 7:31:21-GMT,7264;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id BAA24530 for ; Mon, 17 Aug 1998 01:31:19 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from relay3.UU.NET by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 17 Aug 1998 02:25:33 EST Received: from a by relay3.UU.NET with SMTP (peer crosschecked as: 1Cust2.tnt16.nyc3.da.uu.net [153.37.147.2]) id QQfcuf29845; Mon, 17 Aug 1998 03:25:04 -0400 (EDT) Date: Mon, 17 Aug 1998 03:25:04 -0400 (EDT) From: learnfast@hotmail.com Reply-To: LitProg@SHSU.edu, learnfast@hotmail.com Message-ID: Subject: Are They Investigating You? ARE YOU BEING INVESTIGATED? Has your personal and credit information been stolen? Has someone assumed your identity? Would you like to locate an old friend, relative, military buddy or sweetheart? Do you want to find a person's assets to collect a debt or judgement? Would you like to check a person's criminal record before renting them space or giving them employment? Would you like to fix up your credit bureau report, create a new identity or even disappear? Are you going to have surgery? Would you like to know how many malpractice suits have been filed against your doctor? Now you can learn all this plus much, much more with our brand new 45 page report "INTERNET SLEUTH"! Learn the Internet tools and resources that are used to investigate you, your relatives, friends, neighbors, enemies, employees or anyone else! We will give you thousands of Internet locations to look up people, credit, social security, current or past employment, driving records, criminal records, medical information, military records, addresses, phone numbers, immigration, divorce, labor and criminal laws! We will also give you sources to find missing children and parents, hazardous waste sites, how to do Freedom of Information Act information searches, how to do skip tracing and backround checks on prospective dates, brides or grooms, employees, renters, vendors, new clients and competitors! You will also learn about and where to get surveillance and spy devices, private mail forwarding and annonymous email forwarding sites, search for copyrights, patents and court cases and how to make your assets untraceable! We will show you how to get copies of credit reports, adoption databases, information on drugs, poisons and how to get your share of government programs and benefits! Can you find this information by using the Internet Search Engines? The answer is MAYBE if you get lucky and if you want to spend many hours going through 25,000 plus hits per subject! We and our staff have spent hundreds of hours and many thousands of dollars compiling this information for you! Now you can have it on a silver platter for LESS THAN TWENTY BUCKS during this special email promotion! You frequently hear over the media, television, radio, the newspapers, how personal information is being used, traded and sold over the Internet...usually without your permission or knowledge. Our report will show you HOW IT IS DONE!!! Would you like to find that old romantic flame...find telephone, address or email information on almost anyone...even unlisted phone numbers? How about your family "tree"? We will teach you how to turn years of work into hours of fun! Military? Check Army, Navy, Air Force and Marine records. extensive Vietnamese war records, MIA info, much more! Looking for a job? Find the job you are seeking...even in another state or another country! We will teach you how! Looking for a new love interest or spouse or even sex partner? We will show you where to look for fast results! Want up-to-the-minute health and medical information? Learn how to cure fears and phoebias, the latest drugs and treatments for almost any ailment or desease from the drug companies themselves as well as from universities and the Center for Desease Control. Want to learn the most effective way to loose weight? It's all here in our report! If you believe that the information compiled about you should be as available to you as to the people that compile it about you without your knowledge or permission than you must order "THE INTERNET SLEUTH REPORT" immediately! Our "INTERNET SLEUTH REPORT" is normally sold by direct mail for $39.95 and will soon be in book stores for $29.95. However, to generate publicity and "get the word out" we are making this 10 day Email Special Offer of our Complete 45 Page Report for only $19.95 plus $3 for shipping and handling [total $22.95]. Sold with our 10 Day Money Back Guarantee! This is the biggest bargain on the Internet and the information it will give to you will give you great power! It can really change your life in a positive way. Order Now! The Complete 45 page "INTERNET SLEUTH REPORT" only $19.95 plus $3 shipping and handling - total $22.95. Shipped in plain wrapper by First Class Mail. Add $5 for priority mail delivery. Add $20 for overnight Express! We accept Visa, MasterCard, American Express or Discover. We can also accept your check by phone or Fax. You may order by phone 9 am to 10 pm [NY Time] by phoning [718] 287-3800 You may order by fax 24 hours per day by phoning our fax line at [718] 462-5920. You can fax your credit card information or your check To Email your order - DO NOT HIT REPLY ON YOUR KEYBOARD Send email to our special email address below: moreinfo26@juno.com [Note: If you order by email and do not receive an email confirmation within 24 hours, please phone our office at 718-287-3800] You can also order by mail by sending $22.95 cash, check, money order or major credit card [Visa, MasterCard, American Express or Discover] to TCPS, INC. 4718 18th Ave. Suite 135 Brooklyn, NY 11204 Make Checks & Money Orders Payable to TCPS, Inc. New York State Residents Please Add $1.70 for Sales Tax The Following Order Form is for Your Convenience! Use it by Mail, Fax or Email! ............................................................................................................. Please ship me ________copies of the INTERNET SLEUTH Report at $19.95 each plus $3.00 for shipping and handling [$22.95] Signature______________________________________________ Credit Card #____________________________Exp date______ Ship to: Name_________________________________________ Address________________________________________________ City________________________State___________Zip________ Area Code and Home Phone [ ]___________________________ Fax # [ ]______________________________________________ Email Address___________________________________________ To remove your name from our mailing list, send us an email with remove in the subject line. This is a one time offer and you should not hear from us again! TCPS,Inc., 4718 18th Ave., Suite 135, Brooklyn, NY 11204 Office [718] 287-3800 Fax [718] 462-5920 24 hours [9am to 10pm NY Time] [c] Copyright 1998 TCPS, Inc. All Rights Reserved. 19-Aug-1998 4:45:04-GMT,969;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id WAA16051 for ; Tue, 18 Aug 1998 22:45:03 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 18 Aug 1998 23:41:27 EST From: axel@omp.de (Axel Bodemer) Reply-To: LitProg@SHSU.edu, axel@omp.de Subject: S: folding.el Date: 19 Aug 1998 03:15:40 GMT Message-ID: <6rdg0s$m1j$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii To: LitProg@SHSU.edu Hi, I search a folding mode for noweb. The file folding.el crash the text. Exist a noweb version ? Axel --- Axel Bodemer omp computer GmbH, Paderborn +49 5251 axel@omp-paderborn.de XLink-PoP Ostwestfalen/Lippe 15098-110 20-Aug-1998 17:29:41-GMT,1113;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id LAA16230 for ; Thu, 20 Aug 1998 11:29:40 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 20 Aug 1998 01:38:43 EST From: John Doe Reply-To: LitProg@SHSU.edu, doe#m#_john@MMAC.IS.LMSC.LOCKHEED.COM Subject: LP and design patterns Date: 19 Aug 1998 16:01:05 GMT Message-ID: <6ress1$jcm$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Some of the literature on Design Patterns claims to have had it's origin in Literate Programming, but I can not find anything to support this claim. Does anyone know if this is true? -Thanx chuck.meyers@lmco.com 20-Aug-1998 17:48:29-GMT,1632;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id LAA16686 for ; Thu, 20 Aug 1998 11:48:28 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 20 Aug 1998 12:29:54 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: Re: LP and design patterns Date: 20 Aug 1998 16:21:59 GMT Message-ID: <6rhif7$q93$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu On 19 Aug 1998 16:01:05 GMT, John Doe wrote: > Some of the literature on Design Patterns claims to have had it's > origin in Literate Programming, but I can not find anything to support > this claim. Does anyone know if this is true? In Richard Gabriel's book "Patterns of Software - Tales from the Software Community" (Oxford University Press, 1996) I found a sentence that reminds in some way the goals of literate programming (page 11): "Habitability is the characteristic of source code that enables programmers, coders, bug-fixers, and people coming to the code later in its life to understand its construction and intentions and to change it comfortably and confidently. Either there is more to habitability than clarity or the two characteristics are different." Paolo -- Paolo Amoroso 21-Aug-1998 18:26:07-GMT,64888;000000000001 Received: from Niord.shsu.edu (niord.shsu.edu [192.92.115.8]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id MAA09897 for ; Fri, 21 Aug 1998 12:26:04 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 21 Aug 1998 12:59:56 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 21 Aug 1998 11:38:29 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.edu Archive-name: literate-programming-faq Last-modified: 1997/08/15 Version: 1.1.18 The Literate Programming FAQ David B. Thompson 15 August 1997 This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. ______________________________________________________________________ Table of Contents: 1. Welcome 1.1. Disclaimer 1.2. Copyright 1.3. What's New? 2. Introduction or 3. How do I get the FAQ? 3.1. Literate Programming FAQ 3.2. FWEB FAQ 4. Is there a newsgroup? 5. What internet nodes are of interest to literate programmers? 6. What is Literate Programming? 7. How do I begin literate programming? 8. What literate programming tools are available? 8.1. APLWEB 8.2. AWEB 8.3. CLiP 8.4. CWEB 8.5. CWEBx3.0 8.6. mCWEB 8.7. FunnelWeb 8.8. FunnelWeb 3.0AC 8.9. FWEB 8.10. IMPACT 8.11. lit2x 8.12. Literate Programmer's Workshop (LPW) 8.13. MapleWEB 8.14. MWEB (Schrod/Detig) 8.15. MWEB (Sewell) 8.16. noweb 8.17. nuweb 8.18. ProTeX 8.19. RWEB 8.20. SchemeWEB 8.21. SpideryWEB 8.22. WEB 8.23. WinWordWEB 9. Are there other tools I should know about? 9.1. C2LaTeX 9.2. c2cweb 9.3. c2man 9.4. cnoweb 9.5. Fold2Web 9.6. Funnelweb Mode 9.7. noweb.el 9.8. nuweb.el 9.9. TIE 9.10. Web mode 10. What other resources are available? 10.1. World Wide Web 10.2. TeX Resources 11. Are there any code examples? 12. Bibliographies 13. How to anonymously ftp 14. Acknowledgements 15. End notes ______________________________________________________________________ 1. Welcome Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 1.1. Disclaimer Disclaimer: ``This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk.'' 1.2. Copyright Copyright 1993-1997 by David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: 1.3. What's New? o My email address has changed (once again). o Newsgroup is moderated. o Updated fweb entry. o Updated noweb entry. o Added mCWEB entry. o Updated c2cweb entry. o Updated nuweb.el entry. o Updated cLiP entry. o Updated Lee W's examples (from bart). o Last, but not least, new formatting of the FAQ. Many thanks go to Andrew Johnson for helping make this happen. 2. Introduction or ``What's this all about?'' This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson Comments and constructive criticisms are welcome. Direct flames to /dev/null (or nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is not complete, and probably will never be complete. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. 3. How do I get the FAQ? 3.1. Literate Programming FAQ You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled ``Internet Nodes of Interest to Literate Programmers''.) 3.2. FWEB FAQ David Coker maintains the FWEB FAQ. The current version number is 1.30a. It can be retrieved in the same way as this FAQ. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de 131.169.10.115 in directory /pub/faq/web/fweb/. It is also available from the literate programming archive in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). 4. Is there a newsgroup? One of the most important resources is the literate programming newsgroup, comp.programming.literate. Because of the amount of spamming and unrelated the posts, the newsgroup is now moderated. Posts to the newsgroup are now routed through litprog- mod@cs.virginia.edu. If your news reader does not post through this address, then you will be unable to post messages to the newgroup. You can read this newsgroup using your standard reader. 5. What internet nodes are of interest to literate programmers? The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. Participating hosts in the Comprehensive TeX Archive Network are: ftp.dante.de (Deutschland) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node sun.dante.de -- e-mail via ftpmail@dante.de -- Administrator: ftp.tex.ac.uk (England) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node gopher.tex.ac.uk -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive -- World Wide Web access on www.tex.ac.uk -- Administrator: The site ftp.shsu.edu used to be the American CTAN site. Apparently, that site has fallen into disrepair and should not be considered a primary source for either TeX related or literate programming related material. For the record, the address is: ftp.shsu.edu (Texas, USA) -- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive) -- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive -- e-mail via ftpmail@ftp.SHSU.edu -- World Wide Web access on www.SHSU.edu -- Administrator: A list of CTAN archive sites and their mirrors can be found on: ftp.dante.de:/tex-archive/CTAN.sites I presume that the other CTAN sites mirror this file, but have not checked. As of my last check (September 1994), it contains: "In order to reduce network load, it is recommended that you use the Comprehensive TeX Archive Network (CTAN) host which is located in the closest network proximity to your site." Known partial mirrors of the CTAN reside on (alphabetically): dongpo.math.ncu.edu.tw (Taiwan) /tex-archive ftp.adfa.oz.au (Australia) /pub/tex/ctan ftp.muni.cz (The Czech Republic) /pub/tex/CTAN ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive ftp.uu.net (Virginia, USA) /pub/text-processing/TeX nic.switch.ch (Switzerland) /mirror/tex Known mirrors of the CTAN reside on (alphabetically): ftp.center.osaka-u.ac.jp (Japan) /CTAN ftp.ccu.edu.tw (Taiwan) /pub/tex ftp.cs.rmit.edu.au (Australia) /tex-archive ftp.duke.edu (North Carolina, USA) /tex-archive ftp.germany.eu.net (Deutschland) /pub/packages/TeX ftp.gwdg.de (Deutschland) /pub/dante ftp.jussieu.fr (France) /pub4/TeX/CTAN ftp.loria.fr (France) /pub/unix/tex/ctan ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de ftp.uni-bielefeld.de (Deutschland) /pub/tex ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex) ftpserver.nus.sg (Singapore) /pub/zi/TeX src.doc.ic.ac.uk (England) /packages/tex/uk-tex sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX wuarchive.wustl.edu (Missouri, USA) /packages/TeX Other nodes and directories of interest include: Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ 6. What is Literate Programming? Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system pro- grammer, who wants to provide the best possible documenta- tion of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To docu- ment such a program we want to explain each individual part of the web and how it relates to its neighbours. The typo- graphic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combin- ing the two, we can develop a style of programming that max- imizes our ability to perceive the structure of a complex piece of software, and at the same time the documented pro- grams can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why. Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM ref. 1 plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References 1 Paul W. Oman and Curtus Cook. ``Typographical style is more than cosmetic.'' CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called ``informal rigour'', i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 Another author (Norman Ramsey) wrote me and asked that his opinions be included in the FAQ. What follows are Norman's comments verbatim. I see it's time for the ``how is literate programming dif- ferent from verbose commenting'' question. Perhaps David Thompson will get this into the FAQ. Alert! What follows are my opinions. In no way do I claim to speak for the (fractious) literate-programming community. How is literate programming different from verbose commenting? There are three distinguishing characteristics. In order of importance, they are: o flexible order of elaboration o automatic support for browsing o typeset documentation, especially diagrams and mathematics Flexible order of elaboration means being able to divide your source program into chunks and write the chunks in any order, independent of the order required by the compiler. In principle, you can choose the order best suited to explaining what you are doing. More subtly, this discipline encourages the author of a literate program to take the time to consider each fragment of the program in its proper sphere, e.g., not to rush past the error checking to get to the ``good parts.'' In its time and season, each part of the program is a good part. (This is the party line; your mileage may vary.) I find the reordering most useful for encapsulating tasks like input validation, error checking, and printing output fit for humans --- all tasks that tend to obscure ``real work'' when left inline. Reordering is less important when using languages like Modula-3, which has exceptions and permits declarations in any order, than when using languages like C, which has no exceptions and requires declaration before use. Automatic support for browsing means getting a table of contents, index, and cross-reference of your program. Cross-reference might be printed, so that you could consult an index to look up the definition of an identifier `foo'. With good tools, you might get a printed mini-index on every page if you wanted. Or if you can use a hypertext technology, cross-reference might be as simple as clicking on an identifier to reach its definition. Indexing is typically done automatically or `semi- automatically', the latter meaning that identifier definitions are marked by hand. Diligently done semi- automatic indexes seem to be best, because the author can mark only the identifiers he or she considers important, but automatic indexing can be almost as good and requires no work. Some tools allow a mix of the two strategies. Some people have applied literate-programming tools to large batches of legacy code just to get the table of contents, index, and cross-reference. I don't use diagrams and mathematics very often, but I wouldn't want to have to live without them. I have worked on one or two projects where the ability to use mathematical formulae to document the program was indispensible. I also wouldn't like to explain some of my concurrent programs without diagrams. Actually I write almost all of my literate programs using only sections headers, lists, and the occasional table. >Wouldn't it be easier to do one's literate programming using >a wysiwyg word processor (e.g. Word for Windows) and >indicate what is source code by putting it in a different >font? The data formats used in wysiwyg products are proprietary, and they tend to be documented badly if at all. They are subject to change at the whim of the manufacturer. (I'll go out on a limb and say there are no significant wysiwyg tools in the public domain. I hope the Andrew people will forgive me.) These conditions make it nearly impossible to write tools, especially tools that provide automatic indexing and cross-reference support. The CLiP people have a partial solution that works for tools that can export text --- they plant tags and delimiters throughout the document that enable the reordering transformation (``tangling''). People use TeX, roff, and HTML because free implementations of these tools are widely available on a variety of platforms. TeX and HTML are well documented, and TeX and roff are stable. TeX is the most portable. I think I have just answered the FAQ ``how come all these tools use TeX, anyway?'' :-) Norman Ramsey 7. How do I begin literate programming? A recommended book is D.E. Knuth's collection of articles (1992) Literate Programming. Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) Weaving a Program: Literate Programming in WEB. Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. 8. What literate programming tools are available? A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) 8.1. APLWEB Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. 8.2. AWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. 8.3. CLiP Developer: E.W. van Ammers and M.R. Kramer Versions: 2.0 and 2.4b (DOS only) Platform: Vax/VMS, Unix, DOS Languages: Any programming language Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, WinWord, Ami Pro, Word Pro, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos DOS sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b) sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS sun01.info.wau.nl:/CLIP/unix Unix CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicit commands to perform the extraction process. Rather it recognizes pseudostatements written as comments in the programming language in question. CLiP distinguishes pseudostatements from ordinary comments because the former comply with a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well. Some hypertext examples are at ftp://sun01.info.wau.nl/clip/html/queens.htm ftp://sun01.info.wau.nl/clip/html/pal1.htm Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentation my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segments. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail to Eric.vanAmmers@user.info.wau.nl 8.4. CWEB Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu 8.5. CWEBx3.0 Developer: Marc van Leeuwen Version: Unknown Hardware: Any system using ASCII code Languages: ANSI C Formatter: Plain TeX Availability: Anonymous ftp from: ftp.cwi.nl/pub/cweb Readme: Bundled with above Brief description: A modified implementation of CWEB, with some extensions. Provides a mode for full compatibility with Levy/Knuth CWEB. The most significant extras are: - Typedef declarations affect formatting througout source file - Include files are scanned for typedef definitions - Flexible selection of layout style - Possibility to refer to sections using symbolic labels - CTANGLE detects unbalanced braces and parentheses - CWEAVE can be made to report syntax errors more easily - Some additional mechanisms to avoid formatting problems - New and modular set of grammar rules, based on ANSI C syntax - Possibility to suppress #line directives - A new manual Support: bugs and remarks to M.van.Leeuwen@cwi.nl 8.6. mCWEB Developer: Markus Oellinger Version: 1.0 Hardware: Unix Languages: C/C++ Formatter: plainTeX Availability: anonymous ftp from ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz Readme: at same location Description: This is mCWEB 1.0, a descendant of the CWEB system of structured documentation by Donald E. Knuth and Silvio Levy. It adds some features that are indispensable when working in a team. mCWEB regards a project of a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface documentation is now also part of mCWEB. It is extracted into a second TeX file. This makes it possible to define well known interfaces between the individual parts of a project that will be implemented by different persons. In addition, mCWEB parses C header files to find out about all the datatypes defined there. mCWEB comes with a full completely rewritten user manual and is compatible with CWEB. Support: Institute of Software Technology moell@ist.tu-graz.ac.at 8.7. FunnelWeb Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. 8.8. FunnelWeb 3.0AC Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au) from FunnelWeb v3.0 by Ross N. Williams (ross@guest.adelaide.edu.au) Version: 3.0AC Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2. Languages: No restrictions. Formatter: Tex, LaTeX, or HTML. Availability: Anonymous ftp from ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz Readme: With bundle above; for FunnelWeb manual see WWW page http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html Description: FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry for FunnelWeb). FunnelWeb is designed to be typesetter independent, though FunnelWeb v3.0 only supports (La)TeX as the typesetter. FunnelWeb 3.0AC also supports HTML, and creates appropriate hypertext links within the document among the code sections. FunnelWeb 3.0AC also supports automatic and manual insertion of line directives, so that compiler errors can be flagged back to the original FunnelWeb source file. FunnelWeb 3.0AC is completely compatible with FunnelWeb v3.0 sources (with one minor exception; see the file README.ABC which comes with the FunnelWeb 3.0AC distribution). Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject to the time constraints imposed by his thesis. 8.9. FWEB Developer: John A. Krommes Version: 1.53 (1.60-beta for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: LaTeX. Plain TeX may work, but is no longer supported. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu 8.10. IMPACT Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. 8.11. lit2x Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown 8.12. Literate Programmer's Workshop (LPW) Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. 8.13. MapleWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown 8.14. MWEB (Schrod/Detig) Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.15. MWEB (Sewell) Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.16. noweb Developer: Norman Ramsey Version: 2.8 Hardware: Unix and DOS platforms (DOS binaries available for v2.7). Languages: All programming languages, singly or in combination. Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc Formatter: Plain TeX, LaTeX, and HTML formatters. Will convert LaTeX to HTML automatically. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent Last recourse, use ftp.cs.virginia.edu:pub/nr Readme: With bundle above, or see the noweb home page: http://www.cs.virginia.edu/~nr/noweb Those without ftp access can consult ``Literate Programming Simplified,'' IEEE Software, September 1994, pp97-105. Description: noweb is designed to meet the needs of literate programmers while retaining the simplest possible input format. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 3 pages; an additional page explains how to customize its LaTeX output. noweb works ``out of the box'' with any programming language, and supports TeX, latex, and HTML back ends. A back end to support full hypertext or indexing takes about 250 lines; a simpler one can be written in 40 lines of awk. The primary sacrifice relative to WEB is that code is not prettyprinted. noweb supports indexing and identifier cross-reference, including hypertext ``hot links.'' noweb includes a simple, efficient LaTeX-to-HTML converter, so you can use hypertext browsers on your legacy documents. noweb can also process nuweb programs, so you can use noweb to convert a standard nuweb program to HTML with one command. Support: email to the author 8.17. nuweb Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu 8.18. ProTeX Developer: Eitan Gurari Version: ProTeX 1.1, AlProTeX 1.4 Hardware: Any platform with (La)TeX Languages: Any language Formatter: TeX or LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: With bundle above Description: + Easy to use + Extensible + Language independent + Multiple output files + Fast (single compilation provides output and dvi files) + No installation is needed besides copying the files (written in TeX) Introduction of main features and examples in pub/tex/osu/gurari/LitProg Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and Literate Programming", McGraw-Hill, 1994 Support: gurari@cis.ohio-state.edu 8.19. RWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown 8.20. SchemeWEB Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. 8.21. SpideryWEB Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. 8.22. WEB Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. 8.23. WinWordWEB Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. 9. Are there other tools I should know about? First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. 9.1. C2LaTeX Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. 9.2. c2cweb Developer: Werner Lemberg Version: 1.5 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg 9.3. c2man language: C, nroff, texinfo, latex, html package: c2man version: 2.0 patchlevel 33 parts: documentation generator (C -> nroff -man, -> texinfo, ->latex, -> html) author: Graham Stoney location: ftp from any comp.sources.misc archive, in volume42 (the version in the comp.sources.reviewed archive is obsolete) ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from archie.au N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from ftp.wustl.edu Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* from ftp.irisa.fr Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* from ftp.iij.ad.jp Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se description: c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. conformance: supports both K&R and ISO/ANSI C coding styles features: + generates output in nroff -man, TeXinfo, LaTeX or HTML format + handles comments as part of the language grammar + automagically documents enum parameter & return values + handles C (/* */) and C++ (//) style comments - doesn't handle C++ grammar (yet) requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX. ports: Unix, OS/2, MSDOS, VMS. portability: very high for unix, via Configure status: actively developed; contributions by users are encouraged. discussion: via a mailing list: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au help: from the author and other users on the mailing list: c2man@research.canon.oz.au announcements: patches appear first in comp.sources.bugs, and then in comp.sources.misc. updated: 1994/10/07 9.4. cnoweb Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. 9.5. Fold2Web Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de 9.6. Funnelweb Mode Developer: Daniel Simmons Version: Unknown Availability: http://www.miscrit.be/~ddw Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown 9.7. noweb.el Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk 9.8. nuweb.el Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@acm.org 9.9. TIE Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown 9.10. Web mode Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown 10. What other resources are available? 10.1. World Wide Web An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html or use a WWW browser and access the URL ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to rtfm.mit.edu and retrieve the official Usenet resource file /pub/usenet/news.answers/www/resources/literate-programming 10.2. TeX Resources Another resource of interest to literate programmers is the comp.text.tex newsgroup. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this resource. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. 11. Are there any code examples? Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au 129.127.40.3 as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: ftp://samson.kean.edu/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is writ- ten in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb 12. Bibliographies Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu 128.110.198.2 in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says sev- eral times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. 13. How to anonymously ftp Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu 18.181.0.24, under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. 14. Acknowledgements This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. 15. End notes This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part.