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 <beebe@MATH.UTAH.EDU>; Wed, 1 Jul 1998 04:53:13 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu>
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 <beebe@MATH.UTAH.EDU>; Wed, 1 Jul 1998 17:55:49 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <beebe@MATH.UTAH.EDU>; Thu, 2 Jul 1998 00:41:36 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <beebe@MATH.UTAH.EDU>; Thu, 2 Jul 1998 00:56:35 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu> 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 <amoroso@mclink.it>
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 <beebe@MATH.UTAH.EDU>; Thu, 2 Jul 1998 01:29:23 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <skaller@maxtal.com.au> 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 <beebe@MATH.UTAH.EDU>; Thu, 2 Jul 1998 04:30:01 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu>
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 <mn200@cl.cam.ac.uk> 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 <beebe@MATH.UTAH.EDU>; Thu, 2 Jul 1998 11:50:24 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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
<LitProg@SHSU.edu>; 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?=" <jurgen.defurne@scc.be>
To: "Literate Programming Newslist" <LitProg@SHSU.edu>
Date: Thu, 02 Jul 98 19:36:14
Reply-To: LitProg@SHSU.edu,
"=?iso-8859-0?q?J=81rgen_Defurne?="
<jurgen.defurne@scc.be>
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 <beebe@MATH.UTAH.EDU>; Thu, 2 Jul 1998 16:28:02 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <felix@informatik.th-darmstadt.de>
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 <mn200@cl.cam.ac.uk> 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 <beebe@MATH.UTAH.EDU>; Fri, 3 Jul 1998 15:48:35 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Sun, 5 Jul 1998 19:48:58 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 |@<Chunk@>|...")
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 <beebe@MATH.UTAH.EDU>; Mon, 6 Jul 1998 08:59:53 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <felix@informatik.th-darmstadt.de>
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 <beebe@MATH.UTAH.EDU>; Mon, 6 Jul 1998 09:12:58 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <felix@informatik.th-darmstadt.de>
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 <beebe@MATH.UTAH.EDU>; Mon, 6 Jul 1998 17:33:20 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <felix@informatik.th-darmstadt.de> 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 <beebe@MATH.UTAH.EDU>; Tue, 7 Jul 1998 01:33:33 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <felix@informatik.th-darmstadt.de>
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 <felix@informatik.th-darmstadt.de> 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 <beebe@MATH.UTAH.EDU>; Tue, 7 Jul 1998 06:13:13 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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: <literate-programming-faq_899768623@rtfm.mit.edu>
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 <thompson@shelob.ce.ttu.edu>
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:
<thompson@shelob.ce.ttu.edu>
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 <ajohnson@gpu.srv.ualberta.ca> 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 <thompson@shelob.ce.ttu.edu>
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 <coker@astro.sunyit.edu> 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: <ftpmaint@dante.de>
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: <ctan-uk@tex.ac.uk>
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: <CTAN-Mgr@SHSU.edu>
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 <CvB@erasmus.hrz.uni-bielefeld.de>
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 <krommes@princeton.edu>
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 <nr@cs.virginia.edu>
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 <gurari@cis.ohio-state.edu>
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 <norman@bellcore.com>
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 <leew@pilot.njin.net>
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 <a7971428@unet.univie.ac.at>
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 <greyham@research.canon.oz.au>
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 <Your Name>" (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 <lang@tu-harburg.d400.de>
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 <simmdan@kenya.isu.edu>
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 <bruce@liverpool.ac.uk>
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 <ddw@acm.org>
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 <bart@cs.tamu.edu>
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 <http_address>,
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 */
> <your email address> /* 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. <your_sys-
tem_type> 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 <beebe@MATH.UTAH.EDU>; 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 <LATEX-L@RELAY.URZ.UNI-HEIDELBERG.DE>; 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
<LATEX-L@RELAY.URZ.UNI-HEIDELBERG.DE>
Sender: Mailing list for the LaTeX3 project
<LATEX-L@RELAY.URZ.UNI-HEIDELBERG.DE>
From: Richard Walker <Richard.Walker@CS.ANU.EDU.AU>
Subject: Re: First experience with xr under L3PL
To: Multiple recipients of list LATEX-L
<LATEX-L@RELAY.URZ.UNI-HEIDELBERG.DE>
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 <beebe@MATH.UTAH.EDU>; Wed, 8 Jul 1998 00:49:30 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <beebe@MATH.UTAH.EDU>; Mon, 13 Jul 1998 19:31:26 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu>
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 <beebe@MATH.UTAH.EDU>; Tue, 14 Jul 1998 08:49:31 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <LitProg@SHSU.edu>; 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 <greens@hsvaic.hv.boeing.com>
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: <Pine.SOL.3.91.980714083556.2046A-100000@hsvaic.hv.boeing.com>
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 <beebe@MATH.UTAH.EDU>; Tue, 14 Jul 1998 20:46:01 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <Pine.OSF.3.91.980712194400.29256A-100000@seralph15>,
Baxter C <colinb@essex.ac.uk> 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 <beebe@MATH.UTAH.EDU>; Thu, 16 Jul 1998 09:10:31 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu> 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 <beebe@MATH.UTAH.EDU>; Sat, 18 Jul 1998 19:39:40 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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" <howie@4howiev.com>
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 <beebe@MATH.UTAH.EDU>; Mon, 20 Jul 1998 02:14:33 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Tue, 21 Jul 1998 01:21:11 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <matti@techunix.technion.ac.il>
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 <beebe@MATH.UTAH.EDU>; Tue, 21 Jul 1998 05:21:19 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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" <syberspaz@yahoo.com>
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 <beebe@MATH.UTAH.EDU>; Tue, 21 Jul 1998 07:43:51 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu>
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: <Pine.GSO.3.96.980721091615.4766B-100000@samson>
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 <beebe@MATH.UTAH.EDU>; Tue, 21 Jul 1998 17:37:14 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Tue, 21 Jul 1998 23:36:30 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu>
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 <beebe@MATH.UTAH.EDU>; Wed, 22 Jul 1998 08:05:07 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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: <literate-programming-faq_901106764@rtfm.mit.edu>
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 <thompson@shelob.ce.ttu.edu>
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:
<thompson@shelob.ce.ttu.edu>
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 <ajohnson@gpu.srv.ualberta.ca> 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 <thompson@shelob.ce.ttu.edu>
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 <coker@astro.sunyit.edu> 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: <ftpmaint@dante.de>
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: <ctan-uk@tex.ac.uk>
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: <CTAN-Mgr@SHSU.edu>
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 <CvB@erasmus.hrz.uni-bielefeld.de>
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 <krommes@princeton.edu>
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 <nr@cs.virginia.edu>
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 <gurari@cis.ohio-state.edu>
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 <norman@bellcore.com>
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 <leew@pilot.njin.net>
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 <a7971428@unet.univie.ac.at>
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 <greyham@research.canon.oz.au>
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 <Your Name>" (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 <lang@tu-harburg.d400.de>
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 <simmdan@kenya.isu.edu>
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 <bruce@liverpool.ac.uk>
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 <ddw@acm.org>
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 <bart@cs.tamu.edu>
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 <http_address>,
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 */
> <your email address> /* 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. <your_sys-
tem_type> 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 <beebe@MATH.UTAH.EDU>; Wed, 22 Jul 1998 13:46:35 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <matti@techunix.technion.ac.il> 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 <beebe@MATH.UTAH.EDU>; Fri, 24 Jul 1998 01:33:40 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <mch24@harvey27.demon.co.uk>
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 <beebe@MATH.UTAH.EDU>; Thu, 30 Jul 1998 13:42:26 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Fri, 31 Jul 1998 11:12:05 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Fri, 31 Jul 1998 11:24:30 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <nr@cs.virginia.edu>
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 <beebe@MATH.UTAH.EDU>; Sun, 2 Aug 1998 04:55:39 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Tue, 4 Aug 1998 14:38:03 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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" <stephenj@javanet.com>
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 <beebe@MATH.UTAH.EDU>; Thu, 6 Aug 1998 07:37:01 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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: <literate-programming-faq_902403198@rtfm.mit.edu>
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 <thompson@shelob.ce.ttu.edu>
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:
<thompson@shelob.ce.ttu.edu>
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 <ajohnson@gpu.srv.ualberta.ca> 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 <thompson@shelob.ce.ttu.edu>
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 <coker@astro.sunyit.edu> 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: <ftpmaint@dante.de>
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: <ctan-uk@tex.ac.uk>
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: <CTAN-Mgr@SHSU.edu>
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 <CvB@erasmus.hrz.uni-bielefeld.de>
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 <krommes@princeton.edu>
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 <nr@cs.virginia.edu>
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 <gurari@cis.ohio-state.edu>
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 <norman@bellcore.com>
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 <leew@pilot.njin.net>
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 <a7971428@unet.univie.ac.at>
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 <greyham@research.canon.oz.au>
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 <Your Name>" (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 <lang@tu-harburg.d400.de>
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 <simmdan@kenya.isu.edu>
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 <bruce@liverpool.ac.uk>
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 <ddw@acm.org>
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 <bart@cs.tamu.edu>
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 <http_address>,
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 */
> <your email address> /* 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. <your_sys-
tem_type> 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 <beebe@MATH.UTAH.EDU>; Thu, 6 Aug 1998 20:32:03 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <cmsmcq@uic.edu>
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 <mch24@harvey27.demon.co.uk> 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 <beebe@MATH.UTAH.EDU>; Sat, 8 Aug 1998 00:26:51 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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" <tony@ems.uq.edu.au>
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" <tony@ems.uq.edu.au>
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
<http://www.ems.uq.edu.au/Public/Lists/xml-litprog-l/>
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 <http://www.ajug.org.au/>).
QMUG Committee Member
(Queensland Macromedia Users' Group <http://www.outlook.com.au/qmug/>).
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 <beebe@MATH.UTAH.EDU>; Sat, 8 Aug 1998 14:00:06 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <mch24@harvey27.demon.co.uk> 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 <beebe@MATH.UTAH.EDU>; Sat, 8 Aug 1998 17:39:11 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Sun, 9 Aug 1998 18:42:21 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <gregm@nms.otc.com.au>
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 <beebe@MATH.UTAH.EDU>; Mon, 10 Aug 1998 03:21:05 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu>
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 <beebe@MATH.UTAH.EDU>; Mon, 10 Aug 1998 17:32:37 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <leew@samson.kean.edu> 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 <beebe@MATH.UTAH.EDU>; Mon, 10 Aug 1998 21:45:07 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <d.s.prichard@larc.nasa.gov>
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 <beebe@MATH.UTAH.EDU>; Tue, 11 Aug 1998 08:50:01 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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" <tony@ems.uq.edu.au>
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" <tony@ems.uq.edu.au>
To: LitProg@SHSU.edu
** Reply to note from Lee Wittenberg <leew@samson.kean.edu> 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 <http://www.ajug.org.au/>).
QMUG Committee Member
(Queensland Macromedia Users' Group <http://www.outlook.com.au/qmug/>).
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 <beebe@MATH.UTAH.EDU>; Thu, 13 Aug 1998 12:01:25 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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?=" <jurgen.defurne@scc.be>
To: "Anthony B. Coates" <tony@ems.uq.edu.au>,
"LitProg@SHSU.edu"
<LitProg@SHSU.edu>
Date: Thu, 13 Aug 98 19:32:59
Reply-To: LitProg@SHSU.edu,
"=?iso-8859-0?q?J=81rgen_Defurne?="
<jurgen.defurne@scc.be>
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 <beebe@MATH.UTAH.EDU>; Fri, 14 Aug 1998 08:43:25 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <LitProg@SHSU.edu>;
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 <custer@rh.edu>
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 <beebe@MATH.UTAH.EDU>; Sun, 16 Aug 1998 02:39:48 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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: <QQfcqs09806.199808160833@relay1.UU.NET>
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 <beebe@MATH.UTAH.EDU>; Mon, 17 Aug 1998 01:31:19 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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: <QQfcuf29845.199808170725@relay3.UU.NET>
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 <beebe@MATH.UTAH.EDU>; Tue, 18 Aug 1998 22:45:03 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <beebe@MATH.UTAH.EDU>; Thu, 20 Aug 1998 11:29:40 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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 <doe#m#_john@mmac.is.lmsc.lockheed.com>
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 <beebe@MATH.UTAH.EDU>; Thu, 20 Aug 1998 11:48:28 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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
<doe#m#_john@mmac.is.lmsc.lockheed.com> 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 <amoroso@mclink.it>
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 <beebe@MATH.UTAH.EDU>; Fri, 21 Aug 1998 12:26:04 -0600 (MDT)
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
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: <literate-programming-faq_903699507@rtfm.mit.edu>
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 <thompson@shelob.ce.ttu.edu>
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:
<thompson@shelob.ce.ttu.edu>
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 <ajohnson@gpu.srv.ualberta.ca> 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 <thompson@shelob.ce.ttu.edu>
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 <coker@astro.sunyit.edu> 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: <ftpmaint@dante.de>
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: <ctan-uk@tex.ac.uk>
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: <CTAN-Mgr@SHSU.edu>
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 <CvB@erasmus.hrz.uni-bielefeld.de>
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 <krommes@princeton.edu>
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 <nr@cs.virginia.edu>
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 <gurari@cis.ohio-state.edu>
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 <norman@bellcore.com>
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 <leew@pilot.njin.net>
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 <a7971428@unet.univie.ac.at>
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 <greyham@research.canon.oz.au>
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 <Your Name>" (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 <lang@tu-harburg.d400.de>
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 <simmdan@kenya.isu.edu>
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 <bruce@liverpool.ac.uk>
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 <ddw@acm.org>
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 <bart@cs.tamu.edu>
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 <http_address>,
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 */
> <your email address> /* 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. <your_sys-
tem_type> 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.