1-Apr-1998 13:25:03-GMT,3790;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 GAA22357 for ; Wed, 1 Apr 1998 06:25:03 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Apr 1998 07:16:30 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Multiple languages in one noweb file (was: noweb language independance) Date: 31 Mar 1998 16:37:40 GMT Message-ID: <6fr64k$6i$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fpj59$hu$1@news.interlog.com>, Francky Leyn wrote: >I'm using noweb to maintain a library of filters (much the same >way noweb is operating) in multiple languages. These include: >C, Perl, AWK, sh, and ProLog. These filters are documented in >a SINGLE noweb file... >1) Executable code, yes/no > One has to be able to make the difference between exectutable > files and files that aren't. This is a Unix-ism, and in my opinion, a red herring. If your operating system is so broken that it can't recognize an executable script without being told chmod +x mumble, it's not noweb's job to fix it. >2) line directives [different for each language] >3) (optional) pretty printing [different for each language] and also 4) Indexing for each language. The architecture of noweb supports this, but nobody has gone the extra mile to make it work. Here's a sketch of what's needed: A) Identify the programming language used in each chunk. For preference I would do that as: A.1) Identify the languages used in each root chunk. A.2) Propagate the information from uses to defs For A.1, the cool way to do it is to look at the tokens in the chunk and identify the language that way. The easy way to do it is to develop a naming convention for root chunks. It would be sensible to use the same conventions that are used in Makefile, e.g., <>, <> C <>, <> Modula-3 <>, <> Standard ML <> Icon And for languages that don't have Makefile conventions, one could play a couple of games with naming: <> Perl Script named htmltoc <> Awk script named noidx <> Bourne Shell script named nocount And so on. If someone reading this group would care to coordinate an effort to develop a naming convention, I will enshrine it in the Hacker's guide. Then somebody has to write filters A.1 and A.2, which will decorate each code chunk with an @language directive. Then, to implement the desiderata above, we need For 2), a more intelligent version of the noweb script. I will try to include this as part of noweb 3, which should include support for making this lightning fast (ha ha ha). For 3), people who write prettyprinters should avoid touching chunks that are labelled with an incompatible @language directive. (By continuing to prettyprint unlabelled code chunks, they will preserve existing behavior in cases where the language hasn't been determined explicitly.) For 4), if somebody prods me, I will modify autodefs to avoid touching chunks that are labelled with an incompatible @language directive. In a more ambitious world, I should make finduses sensitive to @language as well---and if I have a really good day, I should combine all autodefs into a single filter (don't hold your breath). Note that I have no time for any of this :-) Norman 1-Apr-1998 14:33:18-GMT,2569;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 GAA22611 for ; Wed, 1 Apr 1998 06:35:21 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Apr 1998 07:16:01 EST From: Dan Schmidt Reply-To: LitProg@SHSU.edu, dfan@harmonixmusic.com Subject: Re: noweb language independance Date: 31 Mar 1998 16:19:02 GMT Message-ID: <6fr51m$sre$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Francky Leyn writes: | In my opinion, the following conditions have to fullfilled | to obtain true language independence: | | 1) Executable code, yes/no | One has to be able to make the difference between exectutable | files and files that aren't. One has to be able to make shell | scripts executable from within the literate programming source, | not with external scripts possibly part of a makefile. I see the chmod as something that would be better off in the makefile; I think noweb's only responsibility should be to create the documents. Why do you think it has to be done by noweb? | 2) line directives. | 3) (optional) pretty printing. I would add 4) indexing. Some of us brought this up a few months ago. Norman Ramsey introduced the @language keyword to the noweb intermediate representation for this purpose, though I don't believe anyone has done anything with it yet. See the noweb Hacker's Guide at . | Conclusion: in order to obtain language indepence within a single file | with multiple languages used, one has to be able to specify the language | of a specific chunk Agreed. | and one must be able to specify wether a chunk is executable or not. I think this is overkill, though, as I mentioned above. I should note that Norman seems to be rather against the idea of the noweb source explicitly naming what language each root chunk (and by implication each chunk) is in, I guess because of the complexity that introduces. I disagree, but hey, it's his system. :) -- Dan Schmidt -> dfan@harmonixmusic.com, dfan@alum.mit.edu Honest Bob & the http://www2.thecia.net/users/dfan/ Factory-to-Dealer Incentives -> http://www2.thecia.net/users/dfan/hbob/ Gamelan Galak Tika -> http://web.mit.edu/galak-tika/www/ 1-Apr-1998 18:19:38-GMT,1060;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 LAA03221 for ; Wed, 1 Apr 1998 11:19:33 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from x3.boston.juno.com by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Apr 1998 10:49:30 EST Received: (from mcclaine@juno.com) by x3.boston.juno.com (queuemail) id LVL14786; Wed, 01 Apr 1998 11:47:51 EST To: LISTSERV@SHSU.edu CC: LitProg@SHSU.edu Date: Tue, 31 Mar 1998 17:11:37 -0500 Message-ID: <19980401.114731.3254.0.McClaine@juno.com> From: mcclaine@juno.com (Mark F McClaine) Reply-To: LitProg@SHSU.edu, mcclaine@juno.com SIGNOFF LitProg _____________________________________________________________________ You don't need to buy Internet access to use free Internet e-mail. Get completely free e-mail from Juno at http://www.juno.com Or call Juno at (800) 654-JUNO [654-5866] 1-Apr-1998 22:13:11-GMT,1597;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 PAA13085 for ; Wed, 1 Apr 1998 15:13:09 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Apr 1998 15:12:55 EST From: "Gary Grinev" Reply-To: LitProg@SHSU.edu, rct@javanet.com Subject: write me a program please Date: 1 Apr 1998 20:11:26 GMT Message-ID: <01bd5da9$7f492c40$298c5ed1@spare> To: LitProg@SHSU.edu Can you write any of these problems using gwbasic, subscripted variables, and I need to time them so make them the most efficent. If so email me at rct@javanet.com thanks 1.Find the smallest number which leaves a remainder of 1 when divided by 2,3,4,5,6,7,8,9,10,11, and 12, but leaves a zero remainder when divided by 13. 2.Find the smallest number which leaves a remainder of 1 when divided by 2, 2 when divided by, 3 when divided by 4,..., 9 when divided 10. 3.Find he smallest number with exactly 32 divisors. 4.List the numbers less than 2000 that have at least 30 divisors. Tell how many each has. 5.Find the smallest integer that can be written as the sum of 2 cubes in two different ways. 6.Find a 5 digit number which when multiplied by 4 has its digits reversed. 7.Compute 10 pairs of random digits. Print them if they are both odd or both even. 8.Input a number. If it is 3, 7, or 9 print good otherwise print bad. 1-Apr-1998 22:56:50-GMT,4576;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 PAA14747 for ; Wed, 1 Apr 1998 15:56:41 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 01 Apr 1998 14:26:19 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: noweb language independance Date: 31 Mar 1998 16:02:35 GMT Message-ID: <6fr42r$sa8$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 31 Mar 1998, Francky Leyn wrote: > I'm a convinced noweb user, and I would like to address the language > independency issue: I'm wondering if noweb is really as language > independ as one claims. > > I'm using noweb to maintain a library of filters (much the same > way noweb is operating) in multiple languages. These include: > C, Perl, AWK, sh, and ProLog. These filters are documented in > a SINGLE noweb file, and I refuse to split them up according > to the language. I switch from language whenever I find it > appropriate. This makes that an examplary language sequence > looks like "C AWK C Perl C AWK ProLog C". As you can see the > C chunks occur at multiple places between other chunks. Isolating > them would require a separted noweb file for each of them, something > which hampers maintainability and introduces the mixing of formating > issues with the programming issue. > > In my opinion, the following conditions have to fullfilled > to obtain true language independence: > > 1) Executable code, yes/no > One has to be able to make the difference between exectutable > files and files that aren't. One has to be able to make shell > scripts executable from within the literate programming source, > not with external scripts possibly part of a makefile. I disagree here. The task tangling is deliberately separate from the task of compiling (or marking a shell script as executable), because they are two separate steps in the programming process. The purpose of make is to automate this process, so IMO the chmod belongs in the makefile, after the tangle step. BTW, there's no real reason you can't include your makefile as part of the web, too. I'll admit that it does lead to a philosophically interesting "chicken and egg" problem, but it's not really a problem in practice (much like writing the compiler for a new language in the language itself). > > 2) line directives. > Each language has a specific syntax to specify line directives. > One should be able to specify this within the literate programming > source and not through tangling (notangle) options that are valid for > the > complete literate programming source. Unless you use "noweb" instead of "notangle" to tangle your webs, this shouldn't be a problem (except for those languages that don't support any kind of #line equivalent). Again, this is a job for the makefile, and one that make handles quite well with rules. You can make a .nw.pl rule to change .nw files into .pl scripts, supplying the proper -L argument in the notangle command to generate the appropriate Perl directives. If you don't want .pl as an extension on your executable Perl scripts, you can have another rule that simply renames the .pl file without the extension (and, perhaps, chmod's it). It takes more steps, but the computer's doing the work, not you, and it won't mind (and human time is much more valuable than computer time). > 3) (optional) pretty printing. Suppose that literate programming > filters would be aviable for all the languages mentioned (leaving > us something to dream about). In that case one would need a method > to differentiate between the different languages of the code chunks. This is a tougher problem. The best solution, as you say, seems to be to put the name of the language into the chunk name, perhaps using the nocond syntax, i.e., ((Perl)). -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 2-Apr-1998 19:02:17-GMT,895;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 MAA07071 for ; Thu, 2 Apr 1998 12:02:16 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Apr 1998 11:26:12 EST From: "Robert" Subject: Import File! Date: 2 Apr 1998 17:10:57 GMT Message-ID: <01bd5e5a$f6e34900$0101a8c0@192.168.1.1> Reply-To: LitProg@SHSU.edu, rschagen@worldonline.nl To: LitProg@SHSU.edu Hi, Is there any program which lets you import values/keys in the windows'95 system registry(system/user.dat). Not the program regedit.exe. I don't want to push the OK button al the time. Thank you. And Greetings, Robert. 2-Apr-1998 22:05:18-GMT,2898;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 PAA11630 for ; Thu, 2 Apr 1998 15:05:17 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from gatekeeper.pmc.com (pm1-11.sdc.org) by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Apr 1998 14:53:04 EST Received: from pmc-inc.com (lestat.pmc.com [192.168.2.51]) by gatekeeper.pmc.com (8.6.12/8.6.9) with ESMTP id NAA16367; Thu, 2 Apr 1998 13:49:25 -0700 Message-ID: <3523FB32.24E0E2C3@pmc-inc.com> Date: Thu, 02 Apr 1998 13:55:16 -0700 From: Lori Dombrowski Reply-To: LitProg@SHSU.edu, lori@pmc-inc.com MIME-Version: 1.0 To: LitProg@SHSU.edu, rschagen@worldonline.nl Subject: Re: Import File! References: <01bd5e5a$f6e34900$0101a8c0@192.168.1.1> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Robert wrote: > Hi, > > Is there any program which lets you import values/keys in the > windows'95 system registry(system/user.dat). > Not the program regedit.exe. > I don't want to push the OK button al the time. > > Thank you. > And Greetings, > > Robert. This method still uses the regedit program but it may be a possible solution to your problem. >From the command line, either inside a DOS shell or from the Run dialog box enter the following: regedit.exe -s .reg Double clicking on the .reg file will also merge it with your registry. Both methods work silently as I remember, so there isn't a need to constantly press the OK button. The registry file should be in the format generated by Export function under regedit. To view this format just export a small portion of your registry to file and view it using Notepad or some other text editor. It's not that hard to recreate. One word of warning, double clicking on these files will merge their contents with your registry which may cause invalid entries in your registry. While your editing your import file it may be wise to change the extension to something else. A nice program to have around is RegClean. It removes invalid entries from your registry. I believe you can find it one of the Windows95 web sites. The following is a brief example of one of my registry files (foo.reg). REGEDIT HKEY_CLASSES_ROOT\Interface\{D9F57E40-BAC2-11cf-A3AA-00AA00A8AAB9} = FOO HKEY_CLASSES_ROOT\Interface\{D9F57E40-BAC2-11cf-A3AA-00AA00A8AAB9}\ProxyStubClsid32 = {D9F57E40-BAC2-11cf-A3AA-00AA00A8AAB9} HKEY_CLASSES_ROOT\CLSID\{D9F57E40-BAC2-11cf-A3AA-00AA00A8AAB9} = FOO HKEY_CLASSES_ROOT\CLSID\{D9F57E40-BAC2-11cf-A3AA-00AA00A8AAB9}\InprocServer32 = c:\bin\foo.dll I hope that made sense. Lori -- Lori Dombrowski Tel. (505)835-4800 Fax. (505)838-1735 E-mail lori@pmc-inc.com 3-Apr-1998 2:58:43-GMT,1519;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 TAA17653 for ; Thu, 2 Apr 1998 19:58:42 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Apr 1998 20:53:21 EST From: Dan Schmidt Reply-To: LitProg@SHSU.edu, dfan@harmonixmusic.com Subject: Re: noweb language independance Date: 2 Apr 1998 20:36:28 GMT Message-ID: <6g0ssc$etl$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Unregistered_Address@ford.com (Stephen Parker) writes: | I use both noweb and cweb, and find that the one feature of cweb that I | miss in noweb is the typeset comments. Is there any plan to | incorperate a comment typesetting facility into noweb? I don't want | full pretty-printing. dpp, my C/C++ pretty-printer for noweb, has an option to feed comments directly into TeX. It would not be hard to have yet another mode in which comments are TeX'ed but the rest of the source is not pretty-printed at all. I'll add it if there's demand. -- Dan Schmidt -> dfan@harmonixmusic.com, dfan@alum.mit.edu Honest Bob & the http://www2.thecia.net/users/dfan/ Factory-to-Dealer Incentives -> http://www2.thecia.net/users/dfan/hbob/ Gamelan Galak Tika -> http://web.mit.edu/galak-tika/www/ 2-Apr-1998 7:46:18-GMT,2722;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 AAA07202 for ; Thu, 2 Apr 1998 00:46:17 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 02 Apr 1998 01:40:28 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Literate Programming systems diversity Date: 1 Apr 1998 16:13:45 GMT Message-ID: <6ftp3p$h14$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 29 Mar 1998, Norman Ramsey wrote: > >I am not sure whether dpp and Pretzel hunt down header files for typedef > >(and class) definitions to aid typesetting, as CWEBx and mCWEB do; it is > >certainly not a trivial task, given the (entrirely useless) complication > >of the syntax of C declarations. > > This seems pretty useful. How do you know what header files to look > at? Do you look in /usr/include? For my Pretzel Java parser, I defined a TeX macro that allows me to specify that a particular identifier is a class (because Java, like C, and the Algols treat type names like keywords). This macro can be used in \input or \include files containing the "standard" Java types. With a little bit of work (which I haven't had time to do cleanly), this macro can be designed so that it will work properly whether or not prettyprinting is used. The prettyprinter also detects class declarations, and generates calls to this macro automatically (at least I think it does). On the other hand, a 2 pass system would be more convenient for the user. > >... One such thing might be to create an index > >for C++ that somehow reflects the class hierarchy, for instance > >discriminating equal identifiers when they refer to members of different > >classes (not that this is currently done in any CWEB variant, or other > >LP system for that matter). This *would* be wonderful, but I think Norman's right about having the compiler generate the complete cross-reference info that the LP (and other) tools can use. This is a non-trivial problem. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 3-Apr-1998 7:31:17-GMT,1860;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 AAA22423 for ; Fri, 3 Apr 1998 00:31:16 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 01:20:49 EST From: Martin Kraska Reply-To: LitProg@SHSU.edu, martin@c8m42.pi.tu-berlin.de Subject: Re: pretty-printing with noweb Date: 3 Apr 1998 07:19:32 GMT Message-ID: <6g22i4$4br$1@elna.ethz.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Diego Zamboni wrote: > "David R. Martin" writes: > > > What is the proper way to add a pretty-printing filter to > > noweb? All I want is bold C++ keywords. Do I have to > > filter the latex, or can noweb be extended somehow? > > There are two ways I know of pretty-printing with noweb. Pointers to > both of them can be found in the noweb WWW page. One is dpp > (http://www2.thecia.net/users/dfan/real/noweb.html), which does C > prettyprinting (may work partially for C++), and the other is Pretzel > (http://www.iti.informatik.th-darmstadt.de/~gaertner/pretzel/), a > generic pretty-printer generator. > > Cheers, > --Diego As I understand, it is not trivial to get pretzel to work. Has anybody set up the system for FORTRAN 77 or for Perl and could give some hints? -- Martin Kraska Institut fuer Mechanik Tel.: 0049 30 31421485 TU Berlin Fax : 0049 30 31421482 Strasse des 17. Juni D-10623 Berlin martin@c8m42.pi.tu-berlin.de ------------------------------------------------------------ 3-Apr-1998 12:05:32-GMT,1307;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 FAA26678 for ; Fri, 3 Apr 1998 05:05:31 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 05:52:09 EST From: Unregistered_Address@ford.com (Stephen Parker) Reply-To: LitProg@SHSU.edu, Unregistered_Address@ford.com Subject: Re: noweb language independance Date: 2 Apr 1998 20:09:26 GMT Message-ID: <6g0r9m$dqh$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I use both noweb and cweb, and find that the one feature of cweb that I miss in noweb is the typeset comments. Is there any plan to incorperate a comment typesetting facility into noweb? I don't want full pretty-printing. One idea that occurs to me is to create a noweb comment string such that (for instance @#) turns the rest of the line into a typeset comment; ie <<*>>= int x; @# Typeset comment to be placed to the right of the code. Where @#... could be ignored completely by the tangle, but processed and typeset by the weave. Is this a practical idea? Any other suggestions? stephen 3-Apr-1998 15:39:01-GMT,5664;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 IAA29982 for ; Fri, 3 Apr 1998 08:38:59 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 09:12:40 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Review of noweb+dpp word-count program Date: 3 Apr 1998 14:50:46 GMT Message-ID: <6g2t06$ino$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6g2qgj$h6i$1@murdoch.acc.Virginia.EDU>, Marc van Leeuwen wrote: >[an excellent review of wc program in noweb+dpp] >noweb: > >I really miss a clear indication of the beginning of documentation >chunks, and a visual clue to the fact that they comment on the next code >chunk, not the previous one. When designing noweb, I deliberately broke the WEB model that the unit of the document is a (documentation, definitions, code) triple. My primary reason for doing so was that I frequently found it useful to write commentary *following* a code chunk, so the user would already have seen the code. >In fact, the most visual indications of the >chunk division are the marginal notes at the beginning of code chunks, >and they give the wrong impression. I would argue that these chunk divisions are something WEB users have grown accustomed to, but perhaps they are not so important. If you want to divide a particular document into small, visually distinct units, then TeX or latex gives you the facilities you need to do so. A literate-programming tool should not. In other words, Marc's criticism should be taken as a criticism of this particular program, not of the tools. >I am not too happy with the Defines and Uses sections after each code >chunk; they are rather long and distracting (although I can see they >have some utility when browsing through the code), and mostly boring (I >can _see_ which identifiers are being used, no need to repeat them >alphabetically). I'm not too happy with them either. They're there because I was even less happy constantly paging back and forth from code to index in a 300-page document. (BTW, the uses enable you to find the definitions.) A better solution is to use per-page mini-indices, such as Knuth or Hanson have used in their books. The problem with mini-indices is that they require special external tools, multiple passes over the TeX, etc. So far, the tools have tended to be one-off for particular applications. I'd love to see somebody try to work something with LaTeX and makeindex. Incidentally, you can drop these sections by using the `noidentxref' option. >More seriously, they are not very accurate. Chunk 1d >claims to use |status|, but it only occurs as a word in the comments. It's debatable whether that should be considered an error or not, but Dan and I should do a better job letting dpp decide which identifiers should be considered uses and which shouldn't. Right now, there's no good way for Dan to replace the default mechanism with his own. >Then in chunk 1e it is said that |status| is used in chunks 1--3 and 7, >but there is no chunk 1, 2, or 3; these three pages contain 12 code >chunks altogether, and the information that |status| is used at least >once on each page seems less useful then indicating the exact chunks, as >is done in other cases. This is one of the places where I think noweb is >trying to be too cute; in fact I think I the whole idea of sub-page >references, though appealing when using xdvi, would bother me eventually >since adding one line of code or documentation could cause all chunk >references to change, and I can throw away my latest printout. Noweb chunks are numbered by page so that when you're trying to find chunk 297a, you know to look on page 297. It's no fun leafing through a 300-page document looking for chunk 761! It's interesting that in at least one of Don's books (Concrete Mathematics), the *figures* are numbered by page, for the same reason. It sounds like Marc is mixing pages from different printouts. I agree this made sense 10 years ago; printers are so fast today I'm not sure it still does. But if you wanted to, you could tell noweb to number chunks consecutively, by using the `webnumbering' option. >But what >I really miss is an indication where a code chunk just defined is >referenced (used)! How can one do without? I agree. Dan somehow seems to have eradicated *all* chunk cross-reference. I didn't know that was possible! By default noweb puts this information on the definition line, at the right margin. **************** This whole discussion illustrates what I think of as one of the more difficult problems of literate programming: different users have dramatically different ideas about how programs should look on the page. I designed noweb to avoid legislating a particular look (or even legislating TeX!), and that seems to have worked out fairly well. What has worked out less well is that there are a plethora of options that enable users to select different styles that someone has predefined for them. Something like this is necessary---not everybody can or should roll their own styles---but I'm very unhappy with the way things have worked out. The command-line options seem to be the single greatest barrier to learning or using noweb. I would like to try some different ideas for noweb 3. Does anybody have some? Norman 3-Apr-1998 18:39:08-GMT,3745;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 LAA04418 for ; Fri, 3 Apr 1998 11:39:07 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 12:21:16 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: noweb language independance Date: 3 Apr 1998 13:44:03 GMT Message-ID: <6g2p33$g50$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6g0r9m$dqh$1@murdoch.acc.Virginia.EDU>, Stephen Parker wrote: > I use both noweb and cweb, and find that the one feature of cweb that I > miss in noweb is the typeset comments. Is there any plan to > incorperate a comment typesetting facility into noweb? I don't want > full pretty-printing. Such a facility is relatively easy to incorporate using noweb filters. > One idea that occurs to me is to create a noweb comment string such > that (for instance @#) turns the rest of the line into a typeset > comment; ie > > <<*>>= > int x; @# Typeset comment to be placed to the right of the code. > > Where @#... could be ignored completely by the tangle, but processed > and typeset by the weave. I'm wildly opposed to this idea. Please use the standard comment syntax of your programming language. For example, if you're writing C, code something like the following awk filter might work: /^@begin docs / { code = 0 } /^@begin code / { code = 1 } code && /^@text .*\/\*.*\*\// { if match($0, /\/\*.*\*\//) { printf("%s\n", substr($0, 1, RSTART-1)) printf("@literal \\comment{%s}\n", substr($0, RSTART, RLENGTH)) printf("@text %s\n", substr($0, RSTART + RLENGTH)) next } } { print } Put a suitable definition of \comment in your TeX code and you're all set. Of course, you have to work harder if you want to avoid picking up comments in strings, comments split across multiple lines, etc. If anybody gets this to work, please let me know so I can put it in the noweb FAQ. Norman > I use both noweb and cweb, and find that the one feature of cweb that I > miss in noweb is the typeset comments. Is there any plan to > incorperate a comment typesetting facility into noweb? I don't want > full pretty-printing. Such a facility is relatively easy to incorporate using noweb filters. > One idea that occurs to me is to create a noweb comment string such > that (for instance @#) turns the rest of the line into a typeset > comment; ie > > <<*>>= > int x; @# Typeset comment to be placed to the right of the code. > > Where @#... could be ignored completely by the tangle, but processed > and typeset by the weave. I'm wildly opposed to this idea. Please use the standard comment syntax of your programming language. For example, if you're writing C, code something like the following awk filter might work: /^@begin docs / { code = 0 } /^@begin code / { code = 1 } code && /^@text .*\/\*.*\*\// { if match($0, /\/\*.*\*\//) { printf("%s\n", substr($0, 1, RSTART-1)) printf("@literal \\comment{%s}\n", substr($0, RSTART, RLENGTH)) printf("@text %s\n", substr($0, RSTART + RLENGTH)) next } } { print } Put a suitable definition of \comment in your TeX code and you're all set. Of course, you have to work harder if you want to avoid picking up comments in strings, comments split across multiple lines, etc. If anybody gets this to work, please let me know so I can put it in the noweb FAQ. Norman 3-Apr-1998 18:55:25-GMT,8757;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 LAA04780 for ; Fri, 3 Apr 1998 11:55:24 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 12:21:12 EST From: Dan Schmidt Reply-To: LitProg@SHSU.edu, dfan@harmonixmusic.com Subject: Re: Literate Programming systems diversity Date: 3 Apr 1998 17:57:28 GMT Message-ID: <6g37u8$p3v$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Marc van Leeuwen writes: | OK, so here's the review, based on visual inspection only (I don't have | the time to figure out just how dpp achieved its formatting; doing so | might reveal some subtleties that the eye might overlook; who cares?). Thanks for doing this review; it's quite useful. | I'll try to divide my comments into things I suspect are due to dpp, | things I suspect are due to noweb, and general remarks. Let me start | with saying though that this was a very simple example, which only uses | the most trivial constructions of C, so it does not show very clearly | all the capabilities (of lack thereof) of dpp. (One does not test a | compiler on a "Hello world" program, does one?) I did compare the output | to that produced by CWEB on its own version of the program (wc.w). Indeed. It was just the example closest to hand. For example, it doesn't show dpp's capability of typsetting user-defined typedefs and classes in boldface. | Naturally my comments will emphasise imperfections I perceive in dpp and | noweb. Please do not infer that I dislike them (although I don't use | them myself; indeed I do not much programming at all lately). No problem! | General impression: it does indeed look much like CWEB output; nice. For | instance: typefaces used are bold (types), italics (identifiers), | typewriter (strings), roman (comments); formulas resemble TeX math | setting, including math symbols for 'not equal' and 'logical and'; some | space before the left parenthesis in function calls. Exception: #define | lines are entirely verbatim after that keyword (not just the comments). The fact that comments are in #define lines are in typewriter is on the todo list. I specifically didn't typeset the definition part because it could be anything, and doesn't have to look a whole lot like C. I could be convinced out of that decision. I should point out that the space before the left parenthesis in function calls is only because the space is there in the source; dpp had nothing to do with it. dpp does very little to spacing. | There are some small differences though. The binary minus operation | appears as a hyphen (it probably escaped from math mode) at least the | one time it was used (this looks like a bug). Yes. | The |exit| function is set in bold face (this is probably | intentional, by analogy to |return|, which is however a keyword). Yes, intentional. | Unlike in CWEB, all-caps identifiers like |READ_ONLY| are set in | italics, while I think typewriter looks less distracting. Interesting point. That could obviously be changed. | Comments behave rather erratically: often they follow code (always | in case of declarations), sometimes they jump to a new line first, | as if they were themselves statements. Yes - dpp keeps the format of the original file. | I find the latter positively distracting, since (in this program at | least) the comments apply to the preceding statements. It would seem | that the distinction between the two cases depends on what is used | in the source, Yes. | but this is | not so (if the source is indeed the one supplied): the comment "visible | ASCII codes" in section 5a appears on the same line in the source, but | on a separate line in the output. That is weird. I just re-nowebbed the file and the comment came out on the same line. So I imagine that I accidentally changed the source file after my original run, sorry. | The octal constant |0177| is not typeset in a way that emphasises | its octal nature as in CWEB. Right, on the todo list. | No "visible spaces" are used in strings, as in CWEB (making it | easier to count multiple spaces). Way down on the todo list :) | The spacing before semicolons is too tight after certain (italic) | letters, and the same is true for postfix operators like |++|; seems | like the italic correction is missing. Yes, I have to deal with italic correction better. | Finally, the right margin is twice seriously violated by long | comments. This is again a result of dpp not changing line-breaking and indentation. You have to change things by hand in the source if comments go too long. This is unfortunate, but I don't know a better way to automate it. | I really miss a clear indication of the beginning of documentation | chunks, and a visual clue to the fact that they comment on the next code | chunk, not the previous one. In fact, the most visual indications of the | chunk division are the marginal notes at the beginning of code chunks, | and they give the wrong impression. As Norman pointed out, a lot of this is due to the format of the original source that he took. | I think I the whole idea of sub-page references, though appealing | when using xdvi, would bother me eventually since adding one line of | code or documentation could cause all chunk references to change, | and I can throw away my latest printout. I am ambivalent about that numbering scheme. It is an option. | But what I really miss is an indication where a code chunk just | defined is referenced (used)! How can one do without? As Norman noted, I seem to have destroyed the chunk cross-referencing. Oops! I'll have to look into what's going on. | One of the differences is that the dpp version omits this documentation | chunk, and indeed leaves out quite a few loose bits of documentation | further on too, as well as the code implementing a |-s| option to wc. I took the source from Norman's port, which used HTML as its target and so had some HTML embedded in the source. I didn't feel like translating all that HTML to LaTeX (and it was irrelevant to the purpose of presenting dpp's pretty-printing features), so I just took that section out. | The comments have been changed to C++ style trailing "//" comments, for | some reason, which looks rather strange in combination with the old | style (K&R) function headings; I didn't think C++ supported those any | longer. dpp's most serious limitiation right now is that it doesn't support multiple-line /* */ comments. I forget whether the original file had multiple-line comments or not, but I just changed them all to // style. | And one more thing: why was the circumflex (hat) removed from | wc's {\it raison d'\^etre} on page 5 ? (No, guarding the integrity of | the French language is not part of my job description :-) The HTML version just changed raison d'etre to all italics, which seemed silly. I should have put the circumflex back in, you're correct. | If the program is really Knuth's responsibility, it is surely one of | the silliest of his programs I ever saw. Ever seen a program that | checks its command line arguments in its output routine? Here you | have one! And while it complains about the "official" wc not | responding properly to strange options, it behaves very curiously | itself: for instance, the option |-claww| causes it to display a | usage message (because of the 'a'), AND to output character, line | and word counts, in that order, and the word count twice. I agree - to me, this program is an example of the bad side of Knuth's style. Thanks very much for the comments! dpp is still very much in progress, as you can see from the version number and all my "to do" items above. Seeing reviews like this helps me figure out what to do next. You should be aware that when I named dpp, the "d" stood for "dumb" :) It specifically does not try to clean up the user's idiosyncrasies in things like spacing. Since I code in a consistent and clean style, this does not affect me. But I have noticed that when I take others' code and run it through dpp, I have to massage their code first. That's perhaps a strike against dpp, but that's just the way the tool was designed to work. -- Dan Schmidt -> dfan@harmonixmusic.com, dfan@alum.mit.edu Honest Bob & the http://www2.thecia.net/users/dfan/ Factory-to-Dealer Incentives -> http://www2.thecia.net/users/dfan/hbob/ Gamelan Galak Tika -> http://web.mit.edu/galak-tika/www/ 3-Apr-1998 18:59:48-GMT,2301;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 LAA04871 for ; Fri, 3 Apr 1998 11:59:47 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 12:38:22 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: pretty-printing with noweb Date: 3 Apr 1998 18:04:24 GMT Message-ID: <6g38b8$pcl$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 3 Apr 1998, Martin Kraska wrote: > Diego Zamboni wrote: > > > There are two ways I know of pretty-printing with noweb. Pointers to > > both of them can be found in the noweb WWW page. One is dpp > > (http://www2.thecia.net/users/dfan/real/noweb.html), which does C > > prettyprinting (may work partially for C++), and the other is Pretzel > > (http://www.iti.informatik.th-darmstadt.de/~gaertner/pretzel/), a > > generic pretty-printer generator. > > As I understand, it is not trivial to get pretzel to work. Has anybody > set up the system for FORTRAN 77 or for Perl and could give some hints? Pretzel isn't really very difficult. In fact, the production version is much easier than the preliminary one I used to build a Java prettyprinter. The production version allows you to imbed C (C++?) code to handle parsing and lexical issues not easily handled otherwise. In fact, all of the really aggravating things about building the Java pp would have gone away if this feature had existed when I was doing my work. As I recall, it took me about a week (2?) of afternoons to get an acceptible grammar, and a few days of polishing. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 3-Apr-1998 20:40:23-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 NAA07497 for ; Fri, 3 Apr 1998 13:40:21 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 12:24:12 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 3 Apr 1998 12:25:47 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.edu Archive-name: literate-programming-faq Last-modified: 1997/08/15 Version: 1.1.18 The Literate Programming FAQ David B. Thompson 15 August 1997 This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. ______________________________________________________________________ Table of Contents: 1. Welcome 1.1. Disclaimer 1.2. Copyright 1.3. What's New? 2. Introduction or 3. How do I get the FAQ? 3.1. Literate Programming FAQ 3.2. FWEB FAQ 4. Is there a newsgroup? 5. What internet nodes are of interest to literate programmers? 6. What is Literate Programming? 7. How do I begin literate programming? 8. What literate programming tools are available? 8.1. APLWEB 8.2. AWEB 8.3. CLiP 8.4. CWEB 8.5. CWEBx3.0 8.6. mCWEB 8.7. FunnelWeb 8.8. FunnelWeb 3.0AC 8.9. FWEB 8.10. IMPACT 8.11. lit2x 8.12. Literate Programmer's Workshop (LPW) 8.13. MapleWEB 8.14. MWEB (Schrod/Detig) 8.15. MWEB (Sewell) 8.16. noweb 8.17. nuweb 8.18. ProTeX 8.19. RWEB 8.20. SchemeWEB 8.21. SpideryWEB 8.22. WEB 8.23. WinWordWEB 9. Are there other tools I should know about? 9.1. C2LaTeX 9.2. c2cweb 9.3. c2man 9.4. cnoweb 9.5. Fold2Web 9.6. Funnelweb Mode 9.7. noweb.el 9.8. nuweb.el 9.9. TIE 9.10. Web mode 10. What other resources are available? 10.1. World Wide Web 10.2. TeX Resources 11. Are there any code examples? 12. Bibliographies 13. How to anonymously ftp 14. Acknowledgements 15. End notes ______________________________________________________________________ 1. Welcome Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 1.1. Disclaimer Disclaimer: ``This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk.'' 1.2. Copyright Copyright 1993-1997 by David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: 1.3. What's New? o My email address has changed (once again). o Newsgroup is moderated. o Updated fweb entry. o Updated noweb entry. o Added mCWEB entry. o Updated c2cweb entry. o Updated nuweb.el entry. o Updated cLiP entry. o Updated Lee W's examples (from bart). o Last, but not least, new formatting of the FAQ. Many thanks go to Andrew Johnson for helping make this happen. 2. Introduction or ``What's this all about?'' This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson Comments and constructive criticisms are welcome. Direct flames to /dev/null (or nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is not complete, and probably will never be complete. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. 3. How do I get the FAQ? 3.1. Literate Programming FAQ You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled ``Internet Nodes of Interest to Literate Programmers''.) 3.2. FWEB FAQ David Coker maintains the FWEB FAQ. The current version number is 1.30a. It can be retrieved in the same way as this FAQ. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de 131.169.10.115 in directory /pub/faq/web/fweb/. It is also available from the literate programming archive in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). 4. Is there a newsgroup? One of the most important resources is the literate programming newsgroup, comp.programming.literate. Because of the amount of spamming and unrelated the posts, the newsgroup is now moderated. Posts to the newsgroup are now routed through litprog- mod@cs.virginia.edu. If your news reader does not post through this address, then you will be unable to post messages to the newgroup. You can read this newsgroup using your standard reader. 5. What internet nodes are of interest to literate programmers? The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. Participating hosts in the Comprehensive TeX Archive Network are: ftp.dante.de (Deutschland) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node sun.dante.de -- e-mail via ftpmail@dante.de -- Administrator: ftp.tex.ac.uk (England) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node gopher.tex.ac.uk -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive -- World Wide Web access on www.tex.ac.uk -- Administrator: The site ftp.shsu.edu used to be the American CTAN site. Apparently, that site has fallen into disrepair and should not be considered a primary source for either TeX related or literate programming related material. For the record, the address is: ftp.shsu.edu (Texas, USA) -- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive) -- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive -- e-mail via ftpmail@ftp.SHSU.edu -- World Wide Web access on www.SHSU.edu -- Administrator: A list of CTAN archive sites and their mirrors can be found on: ftp.dante.de:/tex-archive/CTAN.sites I presume that the other CTAN sites mirror this file, but have not checked. As of my last check (September 1994), it contains: "In order to reduce network load, it is recommended that you use the Comprehensive TeX Archive Network (CTAN) host which is located in the closest network proximity to your site." Known partial mirrors of the CTAN reside on (alphabetically): dongpo.math.ncu.edu.tw (Taiwan) /tex-archive ftp.adfa.oz.au (Australia) /pub/tex/ctan ftp.muni.cz (The Czech Republic) /pub/tex/CTAN ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive ftp.uu.net (Virginia, USA) /pub/text-processing/TeX nic.switch.ch (Switzerland) /mirror/tex Known mirrors of the CTAN reside on (alphabetically): ftp.center.osaka-u.ac.jp (Japan) /CTAN ftp.ccu.edu.tw (Taiwan) /pub/tex ftp.cs.rmit.edu.au (Australia) /tex-archive ftp.duke.edu (North Carolina, USA) /tex-archive ftp.germany.eu.net (Deutschland) /pub/packages/TeX ftp.gwdg.de (Deutschland) /pub/dante ftp.jussieu.fr (France) /pub4/TeX/CTAN ftp.loria.fr (France) /pub/unix/tex/ctan ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de ftp.uni-bielefeld.de (Deutschland) /pub/tex ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex) ftpserver.nus.sg (Singapore) /pub/zi/TeX src.doc.ic.ac.uk (England) /packages/tex/uk-tex sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX wuarchive.wustl.edu (Missouri, USA) /packages/TeX Other nodes and directories of interest include: Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ 6. What is Literate Programming? Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system pro- grammer, who wants to provide the best possible documenta- tion of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To docu- ment such a program we want to explain each individual part of the web and how it relates to its neighbours. The typo- graphic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combin- ing the two, we can develop a style of programming that max- imizes our ability to perceive the structure of a complex piece of software, and at the same time the documented pro- grams can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why. Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM ref. 1 plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References 1 Paul W. Oman and Curtus Cook. ``Typographical style is more than cosmetic.'' CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called ``informal rigour'', i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 Another author (Norman Ramsey) wrote me and asked that his opinions be included in the FAQ. What follows are Norman's comments verbatim. I see it's time for the ``how is literate programming dif- ferent from verbose commenting'' question. Perhaps David Thompson will get this into the FAQ. Alert! What follows are my opinions. In no way do I claim to speak for the (fractious) literate-programming community. How is literate programming different from verbose commenting? There are three distinguishing characteristics. In order of importance, they are: o flexible order of elaboration o automatic support for browsing o typeset documentation, especially diagrams and mathematics Flexible order of elaboration means being able to divide your source program into chunks and write the chunks in any order, independent of the order required by the compiler. In principle, you can choose the order best suited to explaining what you are doing. More subtly, this discipline encourages the author of a literate program to take the time to consider each fragment of the program in its proper sphere, e.g., not to rush past the error checking to get to the ``good parts.'' In its time and season, each part of the program is a good part. (This is the party line; your mileage may vary.) I find the reordering most useful for encapsulating tasks like input validation, error checking, and printing output fit for humans --- all tasks that tend to obscure ``real work'' when left inline. Reordering is less important when using languages like Modula-3, which has exceptions and permits declarations in any order, than when using languages like C, which has no exceptions and requires declaration before use. Automatic support for browsing means getting a table of contents, index, and cross-reference of your program. Cross-reference might be printed, so that you could consult an index to look up the definition of an identifier `foo'. With good tools, you might get a printed mini-index on every page if you wanted. Or if you can use a hypertext technology, cross-reference might be as simple as clicking on an identifier to reach its definition. Indexing is typically done automatically or `semi- automatically', the latter meaning that identifier definitions are marked by hand. Diligently done semi- automatic indexes seem to be best, because the author can mark only the identifiers he or she considers important, but automatic indexing can be almost as good and requires no work. Some tools allow a mix of the two strategies. Some people have applied literate-programming tools to large batches of legacy code just to get the table of contents, index, and cross-reference. I don't use diagrams and mathematics very often, but I wouldn't want to have to live without them. I have worked on one or two projects where the ability to use mathematical formulae to document the program was indispensible. I also wouldn't like to explain some of my concurrent programs without diagrams. Actually I write almost all of my literate programs using only sections headers, lists, and the occasional table. >Wouldn't it be easier to do one's literate programming using >a wysiwyg word processor (e.g. Word for Windows) and >indicate what is source code by putting it in a different >font? The data formats used in wysiwyg products are proprietary, and they tend to be documented badly if at all. They are subject to change at the whim of the manufacturer. (I'll go out on a limb and say there are no significant wysiwyg tools in the public domain. I hope the Andrew people will forgive me.) These conditions make it nearly impossible to write tools, especially tools that provide automatic indexing and cross-reference support. The CLiP people have a partial solution that works for tools that can export text --- they plant tags and delimiters throughout the document that enable the reordering transformation (``tangling''). People use TeX, roff, and HTML because free implementations of these tools are widely available on a variety of platforms. TeX and HTML are well documented, and TeX and roff are stable. TeX is the most portable. I think I have just answered the FAQ ``how come all these tools use TeX, anyway?'' :-) Norman Ramsey 7. How do I begin literate programming? A recommended book is D.E. Knuth's collection of articles (1992) Literate Programming. Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) Weaving a Program: Literate Programming in WEB. Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. 8. What literate programming tools are available? A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) 8.1. APLWEB Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. 8.2. AWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. 8.3. CLiP Developer: E.W. van Ammers and M.R. Kramer Versions: 2.0 and 2.4b (DOS only) Platform: Vax/VMS, Unix, DOS Languages: Any programming language Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, WinWord, Ami Pro, Word Pro, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos DOS sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b) sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS sun01.info.wau.nl:/CLIP/unix Unix CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicit commands to perform the extraction process. Rather it recognizes pseudostatements written as comments in the programming language in question. CLiP distinguishes pseudostatements from ordinary comments because the former comply with a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well. Some hypertext examples are at ftp://sun01.info.wau.nl/clip/html/queens.htm ftp://sun01.info.wau.nl/clip/html/pal1.htm Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentation my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segments. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail to Eric.vanAmmers@user.info.wau.nl 8.4. CWEB Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu 8.5. CWEBx3.0 Developer: Marc van Leeuwen Version: Unknown Hardware: Any system using ASCII code Languages: ANSI C Formatter: Plain TeX Availability: Anonymous ftp from: ftp.cwi.nl/pub/cweb Readme: Bundled with above Brief description: A modified implementation of CWEB, with some extensions. Provides a mode for full compatibility with Levy/Knuth CWEB. The most significant extras are: - Typedef declarations affect formatting througout source file - Include files are scanned for typedef definitions - Flexible selection of layout style - Possibility to refer to sections using symbolic labels - CTANGLE detects unbalanced braces and parentheses - CWEAVE can be made to report syntax errors more easily - Some additional mechanisms to avoid formatting problems - New and modular set of grammar rules, based on ANSI C syntax - Possibility to suppress #line directives - A new manual Support: bugs and remarks to M.van.Leeuwen@cwi.nl 8.6. mCWEB Developer: Markus Oellinger Version: 1.0 Hardware: Unix Languages: C/C++ Formatter: plainTeX Availability: anonymous ftp from ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz Readme: at same location Description: This is mCWEB 1.0, a descendant of the CWEB system of structured documentation by Donald E. Knuth and Silvio Levy. It adds some features that are indispensable when working in a team. mCWEB regards a project of a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface documentation is now also part of mCWEB. It is extracted into a second TeX file. This makes it possible to define well known interfaces between the individual parts of a project that will be implemented by different persons. In addition, mCWEB parses C header files to find out about all the datatypes defined there. mCWEB comes with a full completely rewritten user manual and is compatible with CWEB. Support: Institute of Software Technology moell@ist.tu-graz.ac.at 8.7. FunnelWeb Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. 8.8. FunnelWeb 3.0AC Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au) from FunnelWeb v3.0 by Ross N. Williams (ross@guest.adelaide.edu.au) Version: 3.0AC Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2. Languages: No restrictions. Formatter: Tex, LaTeX, or HTML. Availability: Anonymous ftp from ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz Readme: With bundle above; for FunnelWeb manual see WWW page http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html Description: FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry for FunnelWeb). FunnelWeb is designed to be typesetter independent, though FunnelWeb v3.0 only supports (La)TeX as the typesetter. FunnelWeb 3.0AC also supports HTML, and creates appropriate hypertext links within the document among the code sections. FunnelWeb 3.0AC also supports automatic and manual insertion of line directives, so that compiler errors can be flagged back to the original FunnelWeb source file. FunnelWeb 3.0AC is completely compatible with FunnelWeb v3.0 sources (with one minor exception; see the file README.ABC which comes with the FunnelWeb 3.0AC distribution). Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject to the time constraints imposed by his thesis. 8.9. FWEB Developer: John A. Krommes Version: 1.53 (1.60-beta for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: LaTeX. Plain TeX may work, but is no longer supported. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu 8.10. IMPACT Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. 8.11. lit2x Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown 8.12. Literate Programmer's Workshop (LPW) Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. 8.13. MapleWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown 8.14. MWEB (Schrod/Detig) Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.15. MWEB (Sewell) Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.16. noweb Developer: Norman Ramsey Version: 2.8 Hardware: Unix and DOS platforms (DOS binaries available for v2.7). Languages: All programming languages, singly or in combination. Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc Formatter: Plain TeX, LaTeX, and HTML formatters. Will convert LaTeX to HTML automatically. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent Last recourse, use ftp.cs.virginia.edu:pub/nr Readme: With bundle above, or see the noweb home page: http://www.cs.virginia.edu/~nr/noweb Those without ftp access can consult ``Literate Programming Simplified,'' IEEE Software, September 1994, pp97-105. Description: noweb is designed to meet the needs of literate programmers while retaining the simplest possible input format. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 3 pages; an additional page explains how to customize its LaTeX output. noweb works ``out of the box'' with any programming language, and supports TeX, latex, and HTML back ends. A back end to support full hypertext or indexing takes about 250 lines; a simpler one can be written in 40 lines of awk. The primary sacrifice relative to WEB is that code is not prettyprinted. noweb supports indexing and identifier cross-reference, including hypertext ``hot links.'' noweb includes a simple, efficient LaTeX-to-HTML converter, so you can use hypertext browsers on your legacy documents. noweb can also process nuweb programs, so you can use noweb to convert a standard nuweb program to HTML with one command. Support: email to the author 8.17. nuweb Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu 8.18. ProTeX Developer: Eitan Gurari Version: ProTeX 1.1, AlProTeX 1.4 Hardware: Any platform with (La)TeX Languages: Any language Formatter: TeX or LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: With bundle above Description: + Easy to use + Extensible + Language independent + Multiple output files + Fast (single compilation provides output and dvi files) + No installation is needed besides copying the files (written in TeX) Introduction of main features and examples in pub/tex/osu/gurari/LitProg Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and Literate Programming", McGraw-Hill, 1994 Support: gurari@cis.ohio-state.edu 8.19. RWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown 8.20. SchemeWEB Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. 8.21. SpideryWEB Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. 8.22. WEB Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. 8.23. WinWordWEB Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. 9. Are there other tools I should know about? First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. 9.1. C2LaTeX Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. 9.2. c2cweb Developer: Werner Lemberg Version: 1.5 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg 9.3. c2man language: C, nroff, texinfo, latex, html package: c2man version: 2.0 patchlevel 33 parts: documentation generator (C -> nroff -man, -> texinfo, ->latex, -> html) author: Graham Stoney location: ftp from any comp.sources.misc archive, in volume42 (the version in the comp.sources.reviewed archive is obsolete) ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from archie.au N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from ftp.wustl.edu Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* from ftp.irisa.fr Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* from ftp.iij.ad.jp Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se description: c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. conformance: supports both K&R and ISO/ANSI C coding styles features: + generates output in nroff -man, TeXinfo, LaTeX or HTML format + handles comments as part of the language grammar + automagically documents enum parameter & return values + handles C (/* */) and C++ (//) style comments - doesn't handle C++ grammar (yet) requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX. ports: Unix, OS/2, MSDOS, VMS. portability: very high for unix, via Configure status: actively developed; contributions by users are encouraged. discussion: via a mailing list: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au help: from the author and other users on the mailing list: c2man@research.canon.oz.au announcements: patches appear first in comp.sources.bugs, and then in comp.sources.misc. updated: 1994/10/07 9.4. cnoweb Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. 9.5. Fold2Web Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de 9.6. Funnelweb Mode Developer: Daniel Simmons Version: Unknown Availability: http://www.miscrit.be/~ddw Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown 9.7. noweb.el Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk 9.8. nuweb.el Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@acm.org 9.9. TIE Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown 9.10. Web mode Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown 10. What other resources are available? 10.1. World Wide Web An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html or use a WWW browser and access the URL ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to rtfm.mit.edu and retrieve the official Usenet resource file /pub/usenet/news.answers/www/resources/literate-programming 10.2. TeX Resources Another resource of interest to literate programmers is the comp.text.tex newsgroup. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this resource. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. 11. Are there any code examples? Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au 129.127.40.3 as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: ftp://samson.kean.edu/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is writ- ten in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb 12. Bibliographies Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu 128.110.198.2 in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says sev- eral times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. 13. How to anonymously ftp Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu 18.181.0.24, under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. 14. Acknowledgements This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. 15. End notes This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. 3-Apr-1998 21:59:33-GMT,7851;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 OAA09421 for ; Fri, 3 Apr 1998 14:59:31 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 15:29:30 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Literate Programming systems diversity Date: 3 Apr 1998 14:08:19 GMT Message-ID: <6g2qgj$h6i$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Dan Schmidt wrote: > Marc van Leeuwen writes: > | Norman Ramsey wrote: > | > > | > I haven't actually tried to prettyprint code using anything more > | > recent than CWEB. Has anybody compared CWEB to using noweb with dpp > | > or Pretzel? I would like to hear about the results. > | > | I haven't, but if anybody can supply me with examples of dpp or Pretzel > | output (preferably in dvi format) I'll be happy to make the comparison. > > I just ran Norman's noweb port of Knuth's wc program through dpp > (first massaging it a little), and put the results at > . > You can also get to that file from my main dpp page at > . > > It does show off the lack of a couple features in dpp, notably the > fact that comments on a #define line are printed verbatim as part of a > #define, not in a comment style. > > The whole idea of dpp was to look like CWEB, so hopefully it will not > suffer too much in the comparison. OK, so here's the review, based on visual inspection only (I don't have the time to figure out just how dpp achieved its formatting; doing so might reveal some subtleties that the eye might overlook; who cares?). I'll try to divide my comments into things I suspect are due to dpp, things I suspect are due to noweb, and general remarks. Let me start with saying though that this was a very simple example, which only uses the most trivial constructions of C, so it does not show very clearly all the capabilities (of lack thereof) of dpp. (One does not test a compiler on a "Hello world" program, does one?) I did compare the output to that produced by CWEB on its own version of the program (wc.w). Naturally my comments will emphasise imperfections I perceive in dpp and noweb. Please do not infer that I dislike them (although I don't use them myself; indeed I do not much programming at all lately). dpp: General impression: it does indeed look much like CWEB output; nice. For instance: typefaces used are bold (types), italics (identifiers), typewriter (strings), roman (comments); formulas resemble TeX math setting, including math symbols for 'not equal' and 'logical and'; some space before the left parenthesis in function calls. Exception: #define lines are entirely verbatim after that keyword (not just the comments). There are some small differences though. The binary minus operation appears as a hyphen (it probably escaped from math mode) at least the one time it was used (this looks like a bug). The |exit| function is set in bold face (this is probably intentional, by analogy to |return|, which is however a keyword). Unlike in CWEB, all-caps identifiers like |READ_ONLY| are set in italics, while I think typewriter looks less distracting. Comments behave rather erratically: often they follow code (always in case of declarations), sometimes they jump to a new line first, as if they were themselves statements. I find the latter positively distracting, since (in this program at least) the comments apply to the preceding statements. It would seem that the distinction between the two cases depends on what is used in the source, but this is not so (if the source is indeed the one supplied): the comment "visible ASCII codes" in section 5a appears on the same line in the source, but on a separate line in the output. The octal constant |0177| is not typeset in a way that emphasises its octal nature as in CWEB. No "visible spaces" are used in strings, as in CWEB (making it easier to count multiple spaces). The spacing before semicolons is too tight after certain (italic) letters, and the same is true for postfix operators like |++|; seems like the italic correction is missing. Finally, the right margin is twice seriously violated by long comments. noweb: I really miss a clear indication of the beginning of documentation chunks, and a visual clue to the fact that they comment on the next code chunk, not the previous one. In fact, the most visual indications of the chunk division are the marginal notes at the beginning of code chunks, and they give the wrong impression. I am not too happy with the Defines and Uses sections after each code chunk; they are rather long and distracting (although I can see they have some utility when browsing through the code), and mostly boring (I can _see_ which identifiers are being used, no need to repeat them alphabetically). More seriously, they are not very accurate. Chunk 1d claims to use |status|, but it only occurs as a word in the comments. Then in chunk 1e it is said that |status| is used in chunks 1--3 and 7, but there is no chunk 1, 2, or 3; these three pages contain 12 code chunks altogether, and the information that |status| is used at least once on each page seems less useful then indicating the exact chunks, as is done in other cases. This is one of the places where I think noweb is trying to be too cute; in fact I think I the whole idea of sub-page references, though appealing when using xdvi, would bother me eventually since adding one line of code or documentation could cause all chunk references to change, and I can throw away my latest printout. But what I really miss is an indication where a code chunk just defined is referenced (used)! How can one do without? general: This program differs somewhat from the version bundled with CWEB; I am not sure who or what caused the difference. In fact I am not sure who wrote the program; the CWEB version says in a TeX comment: % wc: An example of CWEB by Silvio Levy and Donald E. Knuth where the attribution seems to apply to CWEB, not to wc, in particular since it states in section 1: This example, based on a program by Klaus Guntermann and Joachim Schrod [{\sl TUGboat\/ \bf7} (1986), 135--137] presents the ``word count'' program... One of the differences is that the dpp version omits this documentation chunk, and indeed leaves out quite a few loose bits of documentation further on too, as well as the code implementing a |-s| option to wc. The comments have been changed to C++ style trailing "//" comments, for some reason, which looks rather strange in combination with the old style (K&R) function headings; I didn't think C++ supported those any longer. And one more thing: why was the circumflex (hat) removed from wc's {\it raison d'\^etre} on page 5 ? (No, guarding the integrity of the French language is not part of my job description :-) If the program is really Knuth's responsibility, it is surely one of the silliest of his programs I ever saw. Ever seen a program that checks its command line arguments in its output routine? Here you have one! And while it complains about the "official" wc not responding properly to strange options, it behaves very curiously itself: for instance, the option |-claww| causes it to display a usage message (because of the 'a'), AND to output character, line and word counts, in that order, and the word count twice. Marc van Leeuwen Universite de Poitiers 3-Apr-1998 23:29:52-GMT,2724;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 QAA11559 for ; Fri, 3 Apr 1998 16:29:51 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 17:24:43 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: noweb language independance Date: 3 Apr 1998 18:21:25 GMT Message-ID: <6g39b5$q2p$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 2 Apr 1998, Stephen Parker wrote: > I use both noweb and cweb, and find that the one feature of cweb that I > miss in noweb is the typeset comments. Is there any plan to > incorperate a comment typesetting facility into noweb? I don't want > full pretty-printing. > > One idea that occurs to me is to create a noweb comment string such > that (for instance @#) turns the rest of the line into a typeset > comment; ie > > <<*>>= > int x; @# Typeset comment to be placed to the right of the code. > > Where @#... could be ignored completely by the tangle, but processed > and typeset by the weave. > > Is this a practical idea? Any other suggestions? This is unnecessary. You don't have to fiddle with noweb at all, much less add extra features. All you need to do is write a fairly simple filter that replaces all comments in code chunks (@text's between @begin and @end code's) with @literal lines invoking whatever TeX macro you decide to create. For example, the (contrived) C code line @text dist = sqrt(dx*dx+dy*dy); /* Compute the distance ($\sqrt{\Delta x^2+\Delta y^2}$) */ would become @text ++count; @literal \C{Compute the distance ($\sqrt{\Delta x^2+\Delta y^2}$)} (assuming you use CWEB's \C macro for setting your comments), and will be typeset properly. Noweb's @nl's will take care of line breaks, as usual. If you want to get a bit more sophisticated, you can figure out out to deal with multi-line comments, but a simple filter should do the trick. You probably won't need more than a dozen lines of Awk, Perl, or Icon. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 4-Apr-1998 0:57:01-GMT,2724;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 RAA13142 for ; Fri, 3 Apr 1998 17:57:00 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 03 Apr 1998 17:24:43 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: noweb language independance Date: 3 Apr 1998 18:21:25 GMT Message-ID: <6g39b5$q2p$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 2 Apr 1998, Stephen Parker wrote: > I use both noweb and cweb, and find that the one feature of cweb that I > miss in noweb is the typeset comments. Is there any plan to > incorperate a comment typesetting facility into noweb? I don't want > full pretty-printing. > > One idea that occurs to me is to create a noweb comment string such > that (for instance @#) turns the rest of the line into a typeset > comment; ie > > <<*>>= > int x; @# Typeset comment to be placed to the right of the code. > > Where @#... could be ignored completely by the tangle, but processed > and typeset by the weave. > > Is this a practical idea? Any other suggestions? This is unnecessary. You don't have to fiddle with noweb at all, much less add extra features. All you need to do is write a fairly simple filter that replaces all comments in code chunks (@text's between @begin and @end code's) with @literal lines invoking whatever TeX macro you decide to create. For example, the (contrived) C code line @text dist = sqrt(dx*dx+dy*dy); /* Compute the distance ($\sqrt{\Delta x^2+\Delta y^2}$) */ would become @text ++count; @literal \C{Compute the distance ($\sqrt{\Delta x^2+\Delta y^2}$)} (assuming you use CWEB's \C macro for setting your comments), and will be typeset properly. Noweb's @nl's will take care of line breaks, as usual. If you want to get a bit more sophisticated, you can figure out out to deal with multi-line comments, but a simple filter should do the trick. You probably won't need more than a dozen lines of Awk, Perl, or Icon. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 4-Apr-1998 18:49:43-GMT,1930;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 LAA29532 for ; Sat, 4 Apr 1998 11:49:42 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 04 Apr 1998 12:46:57 EST From: Drew Csillag Reply-To: LitProg@SHSU.edu, drew_csillag@geocities.com Subject: [ANNOUNCE] LITWeb 0.1 Literate Programming Tool Date: 4 Apr 1998 18:22:10 GMT Message-ID: <6g5toi$o50$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Announcing LITWeb - The Language Independant Tangler/Weaver Main Features: ------------------ o Language Independant o Configurable o Can have specific language formatters/handlers (so it should be possible to mirror the output of CWeb if you wanted to). o Multiple ouptut formats (HTML, PDF, or whatever) o can handle more than one language in the same source file o written in python (you probably don't need a C compiler...) Main Detriments: ------------------ o isn't done yet (weaver doesn't even run) o bugs I'm mainly releasing it now because I'd like some help completing it. There is some documentation in the release, and LITWeb is written in itself, so it shouldn't be too hard getting started. The tangler is pretty much fully functional, but it doesn't handle mixed tabs/spaces too well yet so right now it's all spaces (donning tabs vs. spaces flamesuit...:) LITWeb home page: ------------------ http://www.geocities.com/SiliconValley/Peaks/7506/LITWeb.html Email me if you are interested in helping or if you use it and like it, or if you just want to say hi! Drew Csillag drew_csillag@geocities.com 4-Apr-1998 20:03:50-GMT,1378;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 NAA00831 for ; Sat, 4 Apr 1998 13:03:49 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 04 Apr 1998 13:59:26 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: noweb: f77 label macro? Date: 4 Apr 1998 19:31:10 GMT Message-ID: <6g61pu$7il$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6g5ka9$1o2$1@murdoch.acc.Virginia.EDU>, Ken Snyder wrote: >Does anyone know of any macros for f77 labels for use with noweb? >Specifically, I would like to simplify the following process: > ><>= > DO 100 i = 1,N > ... > >100 CONTINUE >@ Noweb hack of the day: You could try stealing and idea from the CSD assembler and writing, e.g., <>= DO <<1f>> i = 1,N ... <<1:>> CONTINUE @ You'd have to write a noweb filter that enforced rules like defn and use in the same chunk and replaced @use 1f, @use 1:, etc with appropriate @text. If all labels and refs must appear in the same chunk, this is pretty easy. N 5-Apr-1998 2:42:30-GMT,1374;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 TAA07560 for ; Sat, 4 Apr 1998 19:42:28 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 04 Apr 1998 20:39:58 EST From: jackal@bmdpc5.cbt.nist.gov (Ken Snyder) Subject: noweb: f77 label macro? Date: 4 Apr 1998 15:40:57 GMT Message-ID: <6g5ka9$1o2$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, kenneth.snyder@nist.gov To: LitProg@SHSU.edu Does anyone know of any macros for f77 labels for use with noweb? Specifically, I would like to simplify the following process: <>= DO 100 i = 1,N ... 100 CONTINUE @ without having to actually use the "100" labels and risk a "collision" with the same label in another chunk. I am constrained to FORTRAN 77, and I know that FORTRAN 90 removes the label requirement. I realize that this request borders on solving a problem in laziness. However, I think such a macro would be useful for writing nested chunks. Additionally, I think the output could be more esthetically pleasing. I appologize if this matter has been addressed previously. -Ken Snyder 5-Apr-1998 23:23:54-GMT,3919;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 RAA26224 for ; Sun, 5 Apr 1998 17:23:53 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from indy03.cs.monash.edu.au by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 05 Apr 1998 18:20:37 EST Received: from localhost (ajh@localhost) by indy03.cs.monash.edu.au (8.8.8/8.8.8) with SMTP id JAA03160; Mon, 6 Apr 1998 09:20:30 +1000 (EST) Message-ID: <199804052320.JAA03160@indy03.cs.monash.edu.au> To: LitProg@SHSU.edu, Unregistered_Address@ford.com Subject: Re: noweb language independance MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Mon, 06 Apr 1998 09:20:29 +1000 From: John Hurst Reply-To: LitProg@SHSU.edu, ajh@cs.monash.edu.au On 2 Apr at 20:9, Stephen Parker wrote: > I use both noweb and cweb, and find that the one feature of cweb that I > miss in noweb is the typeset comments. Is there any plan to > incorperate a comment typesetting facility into noweb? I don't want > full pretty-printing. > > One idea that occurs to me is to create a noweb comment string such > that (for instance @#) turns the rest of the line into a typeset > comment; ie > > <<*>>= > int x; @# Typeset comment to be placed to the right of the code. > > Where @#... could be ignored completely by the tangle, but processed > and typeset by the weave. > > Is this a practical idea? Any other suggestions? This has already been done, in my hacking of Preston Brigg's "nuweb" to my "nutweb". I've reported on nutweb before, but it is available from my web page through the "Research" and "literate programming" links (i.e., http://www.cs.monash.edu.au/~ajh/research/literate/index.html) I use the same "@|" marker that Preston uses for flagging identifier definitions. The overloading is handled by using "@{" "@}" pairs, which set off the code to be commented. The markup looks like this @{ mumble; thing := 34; more_code; @| this code is intended to demonstrate the use of nutweb comments @} which, when typeset appears as mumble; | this code is intended thing := 34; | to demonstrate the use more_code; | of nutweb comments when the stuff to the right of the vertical bars is typeset according to whatever TeX rules are in force, and hence can include anything you can do in normal documentation chunks. It is set off from the code by a continuous vertical bar (hence the mnemonic value of the marker "@|"). It's all in the manual part of the literate program available above, and indeed is used by that web itself! There are some hacks to control the positioning of this, since the code may have varying lengths and indentations, and the commentary text may need to be bigger than the code itself. The main control is over the fraction of line width used by the commentary, but the vertical length is automatically determined by the size of the two vboxes made to contain the code and comment material. I've found this wonderful as a way to add documentary comments without breaking a "chunk" sequence. It has the added advantage that it is language independent, and thus is consistent with the noweb/nuweb philosophy. --John Hurst -- Associate Dean (Teaching), Faculty of Information Technology -- Associate Professor, School of Computer Science and Software Engineering --rm 110/26, Computer Science, Monash, Clayton VIC 3168 ~ ~~~&#: --ajh@cs.monash.edu.au _..___ ---____@___H__ --+61 3 9905 5192 (fax +61 3 9905 5146) |_____[_|_________[__]_ --http://www.cs.monash.edu.au/~ajh oo oo oo O--O--O o=o 6-Apr-1998 18:05:24-GMT,1745;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 MAA16155 for ; Mon, 6 Apr 1998 12:05:22 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 06 Apr 1998 11:45:27 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: [ANNOUNCE] LITWeb 0.1 Literate Programming Tool Date: 6 Apr 1998 16:17:06 GMT Message-ID: <6gav62$mtg$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 4 Apr 1998, Drew Csillag wrote: > Announcing LITWeb - The Language Independant Tangler/Weaver > > Main Features: > ------------------ > o Language Independant > o Configurable > o Can have specific language formatters/handlers (so it should be > possible to mirror the output of CWeb if you wanted to). > o Multiple ouptut formats (HTML, PDF, or whatever) > o can handle more than one language in the same source file > o written in python (you probably don't need a C compiler...) Question (not a criticism): What does LITWeb provide that noweb doesn't? -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 7-Apr-1998 5:15:13-GMT,1873;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 XAA00117 for ; Mon, 6 Apr 1998 23:15:11 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 00:11:07 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Literate Programming systems diversity Date: 6 Apr 1998 16:09:24 GMT Message-ID: <6gaunk$mkt$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 3 Apr 1998, Dan Schmidt wrote: > Marc van Leeuwen writes: > > | No "visible spaces" are used in strings, as in CWEB (making it > | easier to count multiple spaces). > > Way down on the todo list :) This is actually quite easy to do with a TeX macro. I have a file (it may be in my contrib directory in the standard noweb distribution) designed for \input that works with the normal noweb to put visible spaces in strings (it simply redefines " to be an active character). It *should* work with dpp as well. If it's not in the noweb distribution, Dan, and you want to use it in dpp, let me know, and I'll send you a copy to include with your standard dpp macros. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 7-Apr-1998 5:15:17-GMT,6466;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 XAA00121 for ; Mon, 6 Apr 1998 23:15:16 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 00:10:58 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Type names and prettyprinting Date: 6 Apr 1998 13:50:29 GMT Message-ID: <6gamj5$fb4$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Lee Wittenberg wrote: > Marc van Leeuwen wrote: > >I am not sure whether dpp and Pretzel hunt down header files for typedef > >(and class) definitions to aid typesetting, as CWEBx and mCWEB do; > For my Pretzel Java parser, I defined a TeX macro that allows me to > specify that a particular identifier is a class (because Java, like C, > and the Algols treat type names like keywords). This macro can be > used in \input or \include files containing the "standard" Java types. > With a little bit of work (which I haven't had time to do cleanly), this > macro can be designed so that it will work properly whether or not > prettyprinting is used. The prettyprinter also detects class > declarations, and generates calls to this macro automatically (at > least I think it does). > > On the other hand, a 2 pass system would be more convenient for the > user. This remark, and similar remarks in the Pretzel manual, puzzled me quite a bit. How could you possibly define a TeX macro that affects Pretzel's parsing of Java programs? Does the Pretzel scanner do some intelligent scanning of TeX macros? Until suddenly, aided also by the curious emphasis I had seen in certain formulations on the _appearence_ of type names (boldface), I realised that of course nothing of the kind is being done: the macro simply changes the font used for this particular identifier, and the parser proceeds in complete ignorance of the distinction between type names and other identifiers. The reason in CWEBx for the mentioned hunting down of header files for typedefs is not primarily to change the appearence of type names (in CWEB you can change the appearence of any identifier fairly easily, like making |lambda| look like real Greek, and it would not be difficult to automate this for setting in boldface). The main reason is that not knowing about the status of type names causes the parser to choke on many kinds of code, producing truly awful results. Even if one manages to not have the parser fail completely, it is clear that one cannot expect decent results without knowing the status of type names. A simple example like |foo*bar;| in C or C++ indicates this: if |foo| is an ordinary identifier, then |*| is a binary operation (multiplication), while if |foo| is a type name, then |*| is a unary operation (indicating that |bar| is defined as a pointer to type |foo|), and the spacing requirement for these two cases is different. Since Pretzel uses a Bison-generated parser, it is probably even more sensitive to parsing errors than CWEB, unless one manages to do very sophisticated error-recovery (not usually a strong point of this type of parser). This might explain to some extent the difficulty in getting good Pretzel grammars for such languages as C and C++. So how does Lee's Pretzel Java parser cope? My guess is that it uses a grammar that is not very similar to the official Java grammar, and which is so permissive at the statement level (meaning roughly: sequences of symbols terminated by a semicolon) that it caters for both ordinary statements and declarations without really knowing which is which (since that would require knowing about type names). Effectively, I think that would reduce one's ability to define prettyprinting at the statement level to things that could also be done by entirely lexical means (i.e., without parsing). One might argue that in most cases this is acceptable (although the above example shows that it cannot always give the right result); however, to me it seems to defeat Pretzels goal of basing prettyprinting on the parse tree of the program. So what could one do to improve the situation? Unfortunately, I think this depends on the programming language (strengthening my initial conviction that this is a point where language-dependent tools are at an advantage). For some languages, the syntax might be so clear that it is always possible to detect type names by the way they are used; I think Pascal might be an example (type names are almost always preceded by a colon there). In that case, the parser may indeed proceed without knowing about type names, and if necessary emit formatting commands when it recognises type names (but note that special treatment of type names is not customary in Pascal: like parsers, humans do not need the additional visual clue). For languages like C however, it seems to me imperative to provide the parser with information about type names. Two factors complicate things when using a LP tool: since code might be reordered, uses of a type name might precede its declaration, and even more importantly, the declaration might be hidden in an external file (a header file or an imported module). For C/++ the best solution to me seems to be the following: as a separate task, run the tangled code through the preprocessor, and from its output extract a list of defined type names, which can then be used by the scanner to properly tag identifiers. A complication that is specific to C and its derivatives is that the syntax of typedef declarations assumes the identifier to be defined to be an _ordinary_ one (indeed, in a 1-pass system the identifier has not been tagged yet), so measures are required to ensure that the identifier already tagged as type name will not cause trouble (one can look at CWEBx's CWEAVE for an example how to cope; it is one of its ugliest, though not particularly complicated, parts of the program). For Pretzel this seems to be bad news, since the solution seems to be both language dependent, and to some extent system-dependent (as it requires direct access to the preprocessor). I wish I could think of a more elegant one. Marc van Leeuwen 7-Apr-1998 16:23:13-GMT,1588;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 KAA11452 for ; Tue, 7 Apr 1998 10:23:12 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 11:11:48 EST From: Michael Hobbs Subject: A question of style Date: 7 Apr 1998 15:46:42 GMT Message-ID: <6gdhp2$acf$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, mike.hobbs@ccmail.fingerhut.com MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu If one were to use literate programming to document a largish program, I can think of two ways to go about it, at the general level. The documentation could be laid out linearly, like a book where each section only references ideas and concepts that have been elaborated in previous sections. Or it could be laid out as a reference guide, where each section contains all the information that is needed to understand what is going on in that section, even if it is duplicated elsewhere. Is there a general consensus on which method works out the best? When people read literate documentation, presumably because they need to modify or somehow interface with the program, do they typically read the *entire* documentation front-to-back, or just the section they are interested in? - Michael Hobbs 7-Apr-1998 22:11:58-GMT,1634;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 QAA19504 for ; Tue, 7 Apr 1998 16:11:52 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 15:47:04 EST From: "Gary Grinev" Reply-To: LitProg@SHSU.edu, rct@javanet.com Subject: write me a program Date: 7 Apr 1998 20:06:12 GMT Message-ID: <01bd6260$69ea7f00$2a8c5ed1@spare> To: LitProg@SHSU.edu Can you write any of these problems using gwbasic, and I need to time them so make them the most efficent please. These programs aer for my class in school and the teacher said that we may have help on them. email me at rct@javanet.comThank you. 1.Find the smallest number which leaves a remainder of 1 when divided by 2,3,4,5,6,7,8,9,10,11, and 12, but leaves a zero remainder when divided by 13. 2.Find the smallest number which leaves a remainder of 1 when divided by 2, 2 when divided by, 3 when divided by 4,..., 9 when divided 10. 3.Find he smallest number with exactly 32 divisors. 4.List the numbers less than 2000 that have at least 30 divisors. Tell how many each has. 5.Find the smallest integer that can be written as the sum of 2 cubes in two different ways. 6.Find a 5 digit number which when multiplied by 4 has its digits reversed. 7.Compute 10 pairs of random digits. Print them if they are both odd or both even. email me at rct@javanet.com.thank you 7-Apr-1998 22:12:25-GMT,1744;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 QAA19524 for ; Tue, 7 Apr 1998 16:12:16 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 14:07:12 EST From: Felix Gaertner Reply-To: LitProg@SHSU.edu, felix@informatik.th-darmstadt.de Subject: Re: pretty-printing with noweb Date: 7 Apr 1998 00:58:52 GMT Message-ID: <6gbtoc$fsv$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Martin Kraska wrote: > As I understand, it is not trivial to get pretzel to work. Has anybody > set up the system for FORTRAN 77 or for Perl and could give some hints? I might repeat my standing offer from one of my recent postings here: If you want to use Pretzel with a programming language for which a Pretzel prettyprinting grammar doesn't exist, you can send me a piece of code together with a description what it should look like (prettyprinted) and I'll try to build a basic Pretzel input file that should do the job. I cannot promise excellent results but at least a level from which own polishing can continue. I do not know Fortran 77 but I know Perl. And regarding Perl, there are _a lot_ of ways to prettyprint it. Cheers Felix -- =========="=================================================== Felix C. Gartner felix@informatik.tu-darmstadt.de Computer Science Department TU Darmstadt, Germany 7-Apr-1998 22:20:05-GMT,1620;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 QAA19712 for ; Tue, 7 Apr 1998 16:20:04 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 15:46:53 EST From: "Gary Grinev" Reply-To: LitProg@SHSU.edu, rct@javanet.com Subject: help Date: 7 Apr 1998 20:05:06 GMT Message-ID: <01bd6260$42db6960$2a8c5ed1@spare> To: LitProg@SHSU.edu Can you write any of these problems using gwbasic, and I need to time them so make them the most efficent please. These programs aer for my class in school and the teacher said that we may have help on them. email me at rct@javanet.comThank you. 1.Find the smallest number which leaves a remainder of 1 when divided by 2,3,4,5,6,7,8,9,10,11, and 12, but leaves a zero remainder when divided by 13. 2.Find the smallest number which leaves a remainder of 1 when divided by 2, 2 when divided by, 3 when divided by 4,..., 9 when divided 10. 3.Find he smallest number with exactly 32 divisors. 4.List the numbers less than 2000 that have at least 30 divisors. Tell how many each has. 5.Find the smallest integer that can be written as the sum of 2 cubes in two different ways. 6.Find a 5 digit number which when multiplied by 4 has its digits reversed. 7.Compute 10 pairs of random digits. Print them if they are both odd or both even. email me at rct@javanet.com.thank you 7-Apr-1998 22:35:02-GMT,1620;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 QAA20090 for ; Tue, 7 Apr 1998 16:35:01 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 15:46:59 EST From: "Gary Grinev" Reply-To: LitProg@SHSU.edu, rct@javanet.com Subject: help Date: 7 Apr 1998 20:06:01 GMT Message-ID: <01bd6260$638847a0$2a8c5ed1@spare> To: LitProg@SHSU.edu Can you write any of these problems using gwbasic, and I need to time them so make them the most efficent please. These programs aer for my class in school and the teacher said that we may have help on them. email me at rct@javanet.comThank you. 1.Find the smallest number which leaves a remainder of 1 when divided by 2,3,4,5,6,7,8,9,10,11, and 12, but leaves a zero remainder when divided by 13. 2.Find the smallest number which leaves a remainder of 1 when divided by 2, 2 when divided by, 3 when divided by 4,..., 9 when divided 10. 3.Find he smallest number with exactly 32 divisors. 4.List the numbers less than 2000 that have at least 30 divisors. Tell how many each has. 5.Find the smallest integer that can be written as the sum of 2 cubes in two different ways. 6.Find a 5 digit number which when multiplied by 4 has its digits reversed. 7.Compute 10 pairs of random digits. Print them if they are both odd or both even. email me at rct@javanet.com.thank you 8-Apr-1998 1:47:11-GMT,1948;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 TAA24193 for ; Tue, 7 Apr 1998 19:47:10 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 20:40:34 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: A question of style Date: 8 Apr 1998 00:07:32 GMT Message-ID: <6gef44$im$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6gdhp2$acf$1@murdoch.acc.Virginia.EDU>, Michael Hobbs wrote: >If one were to use literate programming to document a largish program, I >can think of two ways to go about it, at the general level. The >documentation could be laid out linearly, like a book where each section >only references ideas and concepts that have been elaborated in previous >sections. We've had poor luck with this layout after 20--50 pages. Or it could be laid out as a reference guide, where each >section contains all the information that is needed to understand what >is going on in that section, even if it is duplicated elsewhere. We've never tried this layout. With large documents, we've had best luck with the following structure: a few introductory chapters cover the most basic material and are required reading. These might or might not include code. The rest is laid out as a car-repair manual: chapters are roughly independent. Because real software is more complex than cars, independence is only rough--sometimes chapters depend on earlier chapters. The intended model is: read the first few chapters to learn the basic assumptions, then look up only what you need to know. The table of contents is often very helpful. Norman 8-Apr-1998 3:35:42-GMT,2388;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 VAA25977 for ; Tue, 7 Apr 1998 21:35:41 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 07 Apr 1998 22:28:26 EST From: ptjm@interlog.com (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@interlog.com Subject: Re: A question of style Date: 8 Apr 1998 03:01:55 GMT Message-ID: <6gepb3$5i1$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6gdhp2$acf$1@murdoch.acc.Virginia.EDU>, Michael Hobbs wrote: [...] % Is there a general consensus on which method works out the best? When % people read literate documentation, presumably because they need to % modify or somehow interface with the program, do they typically read the % *entire* documentation front-to-back, or just the section they are % interested in? I try to put enough information to understand the chunk of code at hand, and to tie it in to the program as a whole, but I don't think it's a good idea to constantly explain the big picture, or to go into the details of the current code's place in it, provided that sort of thing is explained somewhere (which, I'm sad to say, isn't always the case...my fault, I'm afraid). One thing that I think should be repeated is assumptions and information about things that don't work in certain circumstances. If some bunch of code is manipulating data in such a way that certain routines which act on that data won't work correctly, I'll put a notice to that effect on every chunk in the hopes that it will discourage people from using those particular routines there. Sometimes, it seems that the world is a very sad place, however. It's valid to have some introductory material which everyone is supposed to understand, and I think it's valid to have pre-requisite bits of code that have to be understood, provided there are references in the chunk at hand. It's certainly not reasonable to expect people to have read and understood everything about the program before they can change any part of it, although it might be nice sometimes. -- Patrick TJ McPhee East York Canada ptjm@interlog.com 8-Apr-1998 7:42:54-GMT,4414;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 BAA00250 for ; Wed, 8 Apr 1998 01:42:53 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 02:37:26 EST From: Gregg Reynolds Subject: Re: How to organize analysis, design and implementation documentation Date: 8 Apr 1998 07:21:20 GMT Message-ID: <6gf8hg$f35$1@elna.ethz.ch> Reply-To: LitProg@SHSU.edu, greyno@mcs.com MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Marc van Leeuwen wrote: > . . . > (what I have done is studing/modifying existing literate > programs as well converting existing illiterate programs) I wonder if you could share your thoughts on how maintenance of literate programs works. I've always thought writing code was obviously a literary and aesthetic endeavor, so I'm a very strong supporter of the _idea_ behind literate programming. But I program for a living, and I hate to imagine what would happen if I suggested to anybody at work that we should do literate programming, under deadline, etc. And how often does an industrial coder get to write a program from scratch? So litprog - or I should say _proper_ literate programming - has always remained wishful thinking; the best one can do is write clear code with the human reader in mind. But I digress. A more basic problem with literate programming as practiced using WEB and its descendants is that maintenance of the source looks to be even more difficult than maintenance of plain (but well-written) code. What has your experience been in this regard? Even if management gave me approval to use literate programming for a project, I'm not so sure I would use it, since on-going maintenance of the code behind the code looks rather hairy. > It strikes me that in large programs there is often a gap between the > very global level, that is fairly well documented (how to install the > program, user documentation, even makefiles etc.), and the detailed > description of the implementation of the components. In principle, > literate programming gives us tools to document at each level (no just > at the statement level as traditional commenting), but in practice there > is a certain level of design often does not get documented, or at least > not together with the source code. Maybe we should expand our idea of literate programming beyond working source code. For example, shouldn't we consider both "The TeX Book" and "TeX the Program" to be part of the same literate programming essay? For the original poster: I recommend that you look into the Z language for formal specification as a good candidate for literate (and precise) specification of requirements. One book I have found particularly good is "Z, An Introduction to Formal Methods" by Antoni Diller, John Wiley & Sons, 1994. Unfortunately it is quite expensive even though it is a paperback. Another very good volume is "Software Engineering Mathematics" by Jim Woodcock and Martin Loomes, Addison-Wesely, 1988. In spite of its title it offers very good and concise coverage of Z. Finally, I will add only because I can't resist: I'm working on an SGML/DSSSL based set of tools that will allow literate programming of legacy systems, as well as translation among languages. I'm a few weeks (ok, a few months) away from unleashing it, but I've got enough working to feel confident. It operates on unmodified source code, tags it with to general DTD, and uses DSSSL (a scheme dialect specifically designed for printing SGML documents) to manipulate the resulting source tree. It has passed the first dogfood test: it operates on itself to reproduce itself. I wouldn't mention it since it isn't done yet; but to quote the Master, ". . . my enthusiasm is so great that I must warn the reader to discount much of what I shall say as the ravings of a fanatic who thinks he has just seen a great light." (Knuth, "Literate Programming", 1984). Should anybody out there with SGML, Scheme, DSSSL, and TeX experience so desire, I would be happy to make the early ugly code available (it will be GNUed when done). 8-Apr-1998 11:49:31-GMT,5452;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 FAA03739 for ; Wed, 8 Apr 1998 05:49:30 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 06:32:22 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Type names and prettyprinting Date: 7 Apr 1998 14:38:51 GMT Message-ID: <6gddpr$7mf$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 6 Apr 1998, Marc van Leeuwen wrote: > Lee Wittenberg wrote: > > Marc van Leeuwen wrote: > > >I am not sure whether dpp and Pretzel hunt down header files for typedef > > >(and class) definitions to aid typesetting, as CWEBx and mCWEB do; > > For my Pretzel Java parser, I defined a TeX macro that allows me to > > specify that a particular identifier is a class (because Java, like C, > > and the Algols treat type names like keywords). This macro can be > > used in \input or \include files containing the "standard" Java types. > > With a little bit of work (which I haven't had time to do cleanly), this > > macro can be designed so that it will work properly whether or not > > prettyprinting is used. The prettyprinter also detects class > > declarations, and generates calls to this macro automatically (at > > least I think it does). > > > > On the other hand, a 2 pass system would be more convenient for the > > user. > > This remark, and similar remarks in the Pretzel manual, puzzled me quite > a bit. How could you possibly define a TeX macro that affects Pretzel's > parsing of Java programs? You can't. But the parser can generate TeX code in its @literal output, and this can include \global macros, which affect the typesetting of identifiers later. My Java parser generates something like \javaid{identifier} whenever it sees an identifier. The \javaid macro is a very smart one. If \identifier is also defined (actually, I don't use \identifier, because real program identifiers -- i.e. 'section' -- might have real (La)TeX meanings, but the principle is the same), then the identifier is typeset as a keyword. It also deals with _ and $, and other TeX specials. [The current version of Pretzel, allows C code to be imbedded, so you can do symbol table lookups and escapes for TeX specials, but the prerelease version I was experimenting with didn't have these features.] When the parser sees a class declaration, it also emits a \javaclass{identifier} macro, which defines \identifier. You can put \javaclass's anywhere in your text chunks, and the identifier will be typeset as a keyword from then on. One of these days I plan to make up a java-lang.tex, java-awt.tex, etc. files containing the appropriate \javaclass's to \input. If I'd wanted to get really cute, I could have hadthe parser output stuff to the .aux file, so that even uses of the identifier earlier than its declaration would be typeset properly. I didn't bother doing that -- too much work for too little gain. I may write some C code to do this someday, and integrate it with the parser (now that Pretzel has that feature), but what I've got pretty well meets my needs, and no one else has complained (if, indeed, anyone else is using my parser). > So how does Lee's Pretzel Java parser cope? My guess is that it uses a > grammar that is not very similar to the official Java grammar, and which > is so permissive at the statement level (meaning roughly: sequences of > symbols terminated by a semicolon) that it caters for both ordinary > statements and declarations without really knowing which is which (since > that would require knowing about type names). Effectively, I think that > would reduce one's ability to define prettyprinting at the statement > level to things that could also be done by entirely lexical means (i.e., > without parsing). One might argue that in most cases this is acceptable > (although the above example shows that it cannot always give the right > result); however, to me it seems to defeat Pretzels goal of basing > prettyprinting on the parse tree of the program. This is somewhat correct. However, it is important to remember that a prettyprinting parser doesn't have to parse the official language (CWEB's certainly doesn't). It just has to look as if it does. In other words, as long as legal code is typeset correctly, who cares how illegal code is set? (I've found many a syntax error in CWEB before running the program through the compiler because the code confused the parser.) In point of fact, one of the major drawbacks of Pretzel is that it does require a complete grammar, as opposed to the incomplete grammars of CWEB and (more to the point) Spidery WEB. It's much easier to write a Spidery grammar than an Pretzel one. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 8-Apr-1998 12:42:13-GMT,1330;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 GAA04435 for ; Wed, 8 Apr 1998 06:42:12 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 07:27:51 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: Re: noweb language independance Date: 8 Apr 1998 12:04:53 GMT Message-ID: <6gfp55$i89$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 3 Apr 1998 13:44:03 GMT, Norman Ramsey wrote: [Suggestions for writing a script to identify comments in code chunks and apply special formatting to them] > Put a suitable definition of \comment in your TeX code and you're all set. I seem to understand that when the LaTeX commands generated by noweave typeset code chunks, they do so in a verbatim-like environment. How is it possible to temporarily disable such behavior to apply appropriate formatting - e.g. italics - to comments? Paolo -- Paolo Amoroso 8-Apr-1998 12:42:40-GMT,1034;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 GAA04447 for ; Wed, 8 Apr 1998 06:42:38 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 07:27:54 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: LaTeX indexing and identifier indexing with noweb Date: 8 Apr 1998 12:04:53 GMT Message-ID: <6gfp55$i87$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Is it possible with noweb to have both an identifier index (i.e. the one generated with \nowebindex) and a regular word index (i.e. with \index entries and \makeindex) in the same LaTeX document? Paolo -- Paolo Amoroso 8-Apr-1998 14:07:55-GMT,1965;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 IAA05866 for ; Wed, 8 Apr 1998 08:07:55 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 08:47:19 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: noweb language independance Date: 8 Apr 1998 13:17:33 GMT Message-ID: <6gftdd$kg6$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 8 Apr 1998, Paolo Amoroso wrote: > On 3 Apr 1998 13:44:03 GMT, Norman Ramsey wrote: > > [Suggestions for writing a script to identify comments in code chunks and > apply special formatting to them] > > Put a suitable definition of \comment in your TeX code and you're all set. > > I seem to understand that when the LaTeX commands generated by noweave > typeset code chunks, they do so in a verbatim-like environment. How is it > possible to temporarily disable such behavior to apply appropriate > formatting - e.g. italics - to comments? For dealing with comments, it's only necessary to turn off some of the environment features (i.e., \obeyspaces) within the confines of your \comment macro. For more complex fiddling, you can always redefine \nwbegincode and \nwendcode. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 8-Apr-1998 14:08:40-GMT,1560;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 IAA05875 for ; Wed, 8 Apr 1998 08:08:30 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 08:47:51 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: LaTeX indexing and identifier indexing with noweb Date: 8 Apr 1998 13:19:00 GMT Message-ID: <6gftg4$khb$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 8 Apr 1998, Paolo Amoroso wrote: > Is it possible with noweb to have both an identifier index (i.e. the one > generated with \nowebindex) and a regular word index (i.e. with \index > entries and \makeindex) in the same LaTeX document? Yes, but not combined (as far as I know). The noweb indexing mechanism does not interfere in any way (that I have found) with makeindex. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | Routine is the death of security. Kean University | Union, NJ 07083 | -- Donald Westlake | "Smoke" (1995) leew@samson.kean.edu | ------------------------------------------------------------------------ 8-Apr-1998 14:45:48-GMT,1513;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 IAA06747 for ; Wed, 8 Apr 1998 08:45:47 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 09:26:54 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: noweb language independance Date: 8 Apr 1998 14:08:45 GMT Message-ID: <6gg0dd$m76$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6gfp55$i89$1@murdoch.acc.Virginia.EDU>, Paolo Amoroso wrote: >On 3 Apr 1998 13:44:03 GMT, Norman Ramsey wrote: > >[Suggestions for writing a script to identify comments in code chunks and >apply special formatting to them] >> Put a suitable definition of \comment in your TeX code and you're all set. > >I seem to understand that when the LaTeX commands generated by noweave >typeset code chunks, they do so in a verbatim-like environment. How is it >possible to temporarily disable such behavior to apply appropriate >formatting - e.g. italics - to comments? Look at and imitate the macros used to set references to other code chunks. Something on the order of (from memory) \def\comment{\endgroup\donwcomment} \def\donwcomment#1{\textit{#1}\begingroup\setupcode} Norman 8-Apr-1998 22:59:18-GMT,909;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 QAA21068 for ; Wed, 8 Apr 1998 16:59:13 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 17:44:42 EST From: nr@cs.virginia.edu (Norman Ramsey) Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: pretty-printing with noweb Date: 8 Apr 1998 01:13:12 GMT Message-ID: <6geiv8$2c9$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6gbtoc$fsv$1@murdoch.acc.Virginia.EDU>, Felix Gaertner wrote: >And regarding Perl, there >are _a lot_ of ways to prettyprint it. Do you mean, There's More Than One Way To Do It? 9-Apr-1998 2:22:49-GMT,1037;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 UAA24679 for ; Wed, 8 Apr 1998 20:22:48 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 21:18:51 EST From: Drew Csillag Reply-To: LitProg@SHSU.edu, drew_csillag@geocities.com Subject: [ANNOUNCE] LITWeb-0.1 distribution split into smaller files Date: 7 Apr 1998 04:25:15 GMT Message-ID: <6gc9rb$g9h$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Because of reports of problems downloading LITWeb, I've divided the distribution into smaller chunks. LITWeb home page http://www.geocities.com/SiliconValley/Peaks/7506/LITWeb.html Drew Csillag drew_csillag@geocities.com 9-Apr-1998 4:44:29-GMT,1085;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 WAA27512 for ; Wed, 8 Apr 1998 22:44:28 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 08 Apr 1998 23:40:58 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: LaTeX indexing and identifier indexing with noweb Date: 8 Apr 1998 14:06:58 GMT Message-ID: <6gg0a2$m66$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6gfp55$i87$1@murdoch.acc.Virginia.EDU>, Paolo Amoroso wrote: >Is it possible with noweb to have both an identifier index (i.e. the one >generated with \nowebindex) and a regular word index (i.e. with \index >entries and \makeindex) in the same LaTeX document? Yes. What's not easy at this time is to combine the two. This embarrasses me :-( N 9-Apr-1998 21:35:39-GMT,891;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 PAA17204 for ; Thu, 9 Apr 1998 15:35:06 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 09 Apr 1998 15:38:20 EST From: "Furtune's Pariah" Reply-To: LitProg@SHSU.edu, robsmaze@ix.netcom.com Subject: CONTRACT PROGRAMMER WANTED Date: Thu, 9 Apr 1998 11:36:09 -0500 Message-ID: <6git5f$2f7@dfw-ixnews11.ix.netcom.com> To: LitProg@SHSU.edu Elevator monitoring system. 2 to 3 month project. Start immediately. Visual Basic or equivalent. Communications, Database, Data Replication. Please reply to mid-amer@ix.netcom.com ASAP 9-Apr-1998 21:57:01-GMT,1529;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 PAA18149 for ; Thu, 9 Apr 1998 15:57:00 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 09 Apr 1998 15:29:11 EST From: Thomas Gellekum Reply-To: LitProg@SHSU.edu, tg@ihf.rwth-aachen.de Subject: Multiple definitions from noweb docs Date: 9 Apr 1998 13:42:14 GMT Message-ID: <6gij7m$8gc$1@elna.ethz.ch> To: LitProg@SHSU.edu Moin, I have the following documents: -------master.tex: [...] \include{test} [...] -------test.tex: \chapter{Tests} \input{test1} \input{test2} -------test1.nw: \section{\File{test1.c}} <>= <> [...] -------test2.nw: \section{\File{test2.c}} <>= <> [...] latex complains about multiple definitions for labels like: LaTeX Warning: Label `NWtesx-tes7-1' multiply defined. LaTeX Warning: Label `NWtesx-IncT-1' multiply defined. LaTeX Warning: Label `NWtesx-**tO-1' multiply defined. It looks like noweave uses a combination of chunk name and the length of this name as a heuristic to determine the labels. This breaks even for short names like <> and <>; all the chunk refs point to the second set of chunks. Any way around this? tg 9-Apr-1998 22:05:41-GMT,1853;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 QAA18523 for ; Thu, 9 Apr 1998 16:05:35 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 09 Apr 1998 15:32:45 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: How to organize analysis, design and implementation documentation Date: 8 Apr 1998 20:28:19 GMT Message-ID: <6ggml3$69e$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6gf8hg$f35$1@elna.ethz.ch>, Gregg Reynolds wrote: >Marc van Leeuwen wrote: >And how often >does an industrial >coder get to write a program from scratch? People at Motorola, like Joseph Brothers and Mary Bos (hope I am getting this right), have done some interesting things with literate programming and legacy software. Perhaps they can comment. >A more basic problem with literate programming as >practiced using WEB and >its descendants is that maintenance of the source looks to be even more >difficult than >maintenance of plain (but well-written) code. What has your experience >been in this >regard? We found this to be a significant problem at Odyssey Research Associates. Formal code reviews and walkthroughs helped a lot. Eventually we moved away from WEB-based tools to Noweb, which offers some modest simplifications of the source codes, which we found worthwhile. It would be an excellent experiment to try to use Dick Lipton's notex program to eliminate TeX and LaTeX, leaving flat ASCII documentation and flat ASCII code. Dick's email address is rjl@cs.princeton.edu. Norman 9-Apr-1998 22:11:58-GMT,3641;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 QAA18708 for ; Thu, 9 Apr 1998 16:11:57 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 09 Apr 1998 15:26:59 EST From: Devon Prichard Reply-To: LitProg@SHSU.edu, prichard@rotari.larc.nasa.gov Subject: Re: A question of style Date: 8 Apr 1998 18:33:04 GMT Message-ID: <6ggft0$1n9$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Michael Hobbs wrote: > > If one were to use literate programming to document a largish program, I > can think of two ways to go about it, at the general level. The > documentation could be laid out linearly, like a book where each section > only references ideas and concepts that have been elaborated in previous > sections. Or it could be laid out as a reference guide, where each > section contains all the information that is needed to understand what > is going on in that section, even if it is duplicated elsewhere. > > Is there a general consensus on which method works out the best? When > people read literate documentation, presumably because they need to > modify or somehow interface with the program, do they typically read the > *entire* documentation front-to-back, or just the section they are > interested in? My experience in wrestling with nontrivial Fortran engineering codes (aerodynamic and aeroacoustic prediction codes, to be specific) is that is that the "reference manual" style is necessary beyond a certain point. One of the codes I mess with was written circa 1980, in an unholy mix of Fortran IV, Fortran 77, and VAX Fortran; it is about 50 klines total, of which I'm guessing 35k are executable. There is no way the "book style" would work, it would take a PhD about 5 years to go from start to finish. As for duplication, there are worse things under the sun. And with the concept of hypertext and hyperlinks, eventually LP will allow the reader to hit a hyperlink that transfers to the "big picture" section, then another hyperlink to a general description of a subsection, then on to the specific routine. Another thing that I have been trying to emphasize in the engineering code that I write is that every variable must be locally documented with units and coordinate system. Too often, when fixing other people's code, have I found that one routine is all metric while the caller is all english. The promise of LP, for me, is the ability to have a relatively seamless connection between a theoretical report, a programmer's guide, and the source code. In my field, there is rarely any connection between the 3 documents (hell, there often is only a cursory theoretical writeup and no programmer's guide). Thus, each user and code modifier end up going thru the process of connecting each theoretical equation with its equivalent line of code, and figuring out units, coordinate system, etc. Replacing this process with the up-front cost of doing LP is the next major improvement in engineering methods development. ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| | Dr. Devon Prichard, Lockheed Martin d.s.prichard@larc.nasa.gov | | starboard side, deck two, oar 14. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| 10-Apr-1998 3:40:59-GMT,3006;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 VAA26282 for ; Thu, 9 Apr 1998 21:40:58 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from mail3.mailsorter.net by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 09 Apr 1998 22:37:35 EST Received: from caliban ([204.157.101.189]) by mail3.mailsorter.net (Netscape Mail Server v2.02) with SMTP id AAA15061 for ; Thu, 9 Apr 1998 20:37:24 -0700 Message-ID: <3.0.32.19980409205808.00913260@mail.bumperkites.org> Date: Thu, 09 Apr 1998 20:58:11 -0700 To: LitProg@SHSU.edu From: mary bos Reply-To: LitProg@SHSU.edu, bos@bumperkites.org Subject: Re: How to organize analysis, design and implementation documentation MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Norman Ramsey wrote: >People at Motorola, like Joseph Brothers and Mary Bos (hope I am >getting this right), have done some interesting things with literate >programming and legacy software. Perhaps they can comment. > >>A more basic problem with literate programming as >>practiced using WEB and >>its descendants is that maintenance of the source looks to be even more >>difficult than >>maintenance of plain (but well-written) code. What has your experience >>been in this >>regard? > When I worked at Motorola, we were adding noweb items to modules we were working on at the time instead of trying to do all of the code. Usually as part of attempting to do a Fagan Inspection or just training other people on the code. Fortunately (?!?) most of our code was in K&R C using an embedded operating system. Joseph Brothers wrote some tools to give an initial framework for noweb but it was still a grind to add the details. We figured it would take quite an effort to do our 250-500 KALOC - so our biggest problem was more organization and how to tie the documentation for the semi-independent tasks together (this code was quite intertwined between tasks - so the interdependencies were interesting and sometimes quite surprising). Gary Young was working on a Great Books concept while all three of us (Gary, Joseph, and myself) were working at Motorola WDG. The documentation could be monolithic so just the organizational framework would be important. Again our emphasis was documenting code and trying to capture design and requirement decisions. Gary and I are still carrying on discussions on this topic, so at this point organization seems to be more along your corporate coding and design style. Unfortunately our project at Motorola was dropped when we all were laid-off. mary Mary Bos email: bos@bumperkites.org Team BumperKites http://www.bumperkites.org Sanity takes its toll and you must have exact change - so go fly a kite 10-Apr-1998 4:37:47-GMT,5463;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 WAA27267 for ; Thu, 9 Apr 1998 22:37:46 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 09 Apr 1998 23:35:49 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Type names and prettyprinting Date: 9 Apr 1998 15:37:58 GMT Message-ID: <6giq0m$aul$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Lee Wittenberg wrote: > > On 6 Apr 1998, Marc van Leeuwen wrote: > > So how does Lee's Pretzel Java parser cope? My guess is that it uses a > > grammar that is not very similar to the official Java grammar, and which > > is so permissive at the statement level that it caters for both ordinary > > statements and declarations without really knowing which is which (since > > that would require knowing about type names). Effectively, I think that > > would reduce one's ability to define prettyprinting at the statement > > level to things that could also be done by entirely lexical means (i.e., > > without parsing). One might argue that in most cases this is acceptable > > (although the above example shows that it cannot always give the right > > result); however, to me it seems to defeat Pretzels goal of basing > > prettyprinting on the parse tree of the program. > > This is somewhat correct. However, it is important to remember that > a prettyprinting parser doesn't have to parse the official language > (CWEB's certainly doesn't). It just has to look as if it does. In > other words, as long as legal code is typeset correctly, who cares > how illegal code is set? There are two points here: (1) the language recognised by the parser does not have to be limited to the official language; (2) the parse tree constructed for constructs that are in the official language does not have to agree with the one given by the official grammar. There is a relation between the two points, as a parser that constructs strange parse trees is unlikely to recognise exactly the official language(*). I agree that nobody cares about (1), as long as the language recognised contains the official language (which may be difficult to prove though). As to (2), not having the right parse tree limits your ability to attach formatting rules to grammatical constructs. As the |foo*bar;| example I gave shows, you may for instace be unable to distiguish unary from binary opertors. Whether this is really a problem depends on what kind of prettyprinting one wishes to do. A lot of rules can be formulated in a way that does not involve the grammar at all, for instance: a forced line break before each '{' followed be an increase of indentation level, the reverse for '}'; a space between adjacent identifiers or numbers; spaces around relations. But if these wre the _only_ kind of rules one uses, why bother using a parser in the first place. Looking at the rules I formulated in the CWEBx grammar, I see that quite a lot are of this limited kind, but there are also rules that dpend on the recognition of larger constructs (like a bit of vertical space being insterted between the declarations and the statements in a block in C. If you want to play around modifying a prettyprinting grammar to suit your favorite style, I think that one close the the official grammar is to be preferred. It is true that CWEB's grammar scores on both points (1) and (2), which I don't like, not so much because it results in uglyprinting, but because it makes it so hard to understand what happens, and what its limitations are; in any case I have found that legal but slightly complicated declarations fail to be prettyprinted correctly. In CWEBx one has (1) and (2) to a much lesser extent (and I would like to reduce this further if I could), and I am more confident of its robustness. > (I've found many a syntax error in CWEB before running the program > through the compiler because the code confused the parser.) I suppose you mean that the CWEB grammar could not be used directly in Pretzel. This is not surprising since the meaning of rules in the CWEB grammar is quite different than in Bison (CWEB has no problem at all with ambiguous grammars for instance, although it will make it a bit tricky to predict which parse one will actually get). > In point of fact, one of the major drawbacks of Pretzel is that it > does require a complete grammar, as opposed to the incomplete grammars > of CWEB and (more to the point) Spidery WEB. It's much easier to > write a Spidery grammar than an Pretzel one. Here I suppose "incomplete" means either too liberal (1) or ambiguous or both. However, I believe that with proper care the Pretzel parsers will be more reliable, exactly because the meaning of the grammar is much more precisely delimited. Experimentation is needed to find out though. Marc van Leeuwen (*) There is however a class of formal transformations of grammars that guarantee to recognise the same language under modified parse trees; these are often very useful to transform a grammar into one acceptable for a particular type of parser generator. 10-Apr-1998 13:00:11-GMT,2393;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 HAA26804 for ; Fri, 10 Apr 1998 07:00:10 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 10 Apr 1998 07:56:42 EST From: "ssenshi" Reply-To: LitProg@SHSU.edu, alexkong@tm.net.my Subject: Please Let Me Understand It Better... Date: Fri, 10 Apr 1998 17:53:46 +0800 Message-ID: <6gl2tc$rls$1@news.tm.net.my> To: LitProg@SHSU.edu Hi, I'm one of the student that study Programming and the first lesson is Pascal Programming. I need an explaination for the command below: Procedure 'XXX' ; VAR LOC 1 : integer ; LOC 2 : integer ; begin Read (input, LOC 1) ; Write (output, LOC 2) ; end ; This command is for the I/O console and below are follow by the file and temp command for I/O: Procedure 'XXX' ; VAR LOC 1 : integer ; LOC 2 : integer ; begin Write (infile, LOC 1) ; Read (outfile, LOC 1) ; end ; Procedure 'XXX' ; VAR LOC 1 : integer ; LOC 2 : integer ; begin LOC 1 : = 3 ; LOC 2 : = LOC 1 ; end ; Below is a data command and I aslo need some explaination for these VAR LOC 1 : integer ; LOC 2 : character ; CONST LOC 3 : A ; Procedure 'XXX' Begin LOC 1 : = 2 ; End ; The 'XXX' means whatever name/procedure are given. And finally I need to know what is data declaration??? (In full explaination also :P) I really need a full explaination for the command and question above. Thank you very much for those who help me or try to help me!!! Thank you.... 10-Apr-1998 14:34:41-GMT,1503;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 IAA29454 for ; Fri, 10 Apr 1998 08:34:41 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from mail.virginia.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 10 Apr 1998 09:31:26 EST Received: from ares.cs.virginia.edu by mail.virginia.edu id aa11460; 10 Apr 98 10:31 EDT Received: from labrador.cs.virginia.edu (nr@labrador.cs.Virginia.EDU [128.143.137.55]) by ares.cs.Virginia.EDU (8.8.5/8.8.5) with ESMTP id KAA13346; Fri, 10 Apr 1998 10:31:13 -0400 (EDT) Received: (from nr@localhost) by labrador.cs.virginia.edu (8.8.6/8.7.3) id KAA26523; Fri, 10 Apr 1998 10:31:12 -0400 Date: Fri, 10 Apr 1998 10:31:12 -0400 Message-ID: <199804101431.KAA26523@labrador.cs.virginia.edu> To: LitProg@SHSU.edu, bos@bumperkites.org From: Litprog moderation robot (replies dropped) Reply-To: LitProg@SHSU.edu, null@cs.virginia.edu Subject: Re: Re: How to organize analysis, design and implementation documentation Dear Poster, You sent mail to the submission address for the moderated Usenet newsgroup comp.programming.literate. Because you are not a regular contributor, this submission has been forwarded to a moderator for consideration. The Litprog moderation robot 11-Apr-1998 10:53:38-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 EAA00081 for ; Sat, 11 Apr 1998 04:53:37 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 11 Apr 1998 05:51:08 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: Re: LaTeX indexing and identifier indexing with noweb Date: 11 Apr 1998 10:23:45 GMT Message-ID: <6gngbh$psm$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 8 Apr 1998 14:06:58 GMT, Norman Ramsey wrote: > Yes. What's not easy at this time is to combine the two. > This embarrasses me :-( This may actually be a feature. Large and complex technical documents often provide several browsing tools. Consider, for example, the GNU Emacs manual, a book with over 400 pages. It contains two tables of contents, a key index, a command and function index, a variable index and a concept index. Most books also come with a list of tables and a list of figures. Literate programs just add a list of code chunks and an index of identifiers. Paolo -- Paolo Amoroso 11-Apr-1998 19:33:14-GMT,1916;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 NAA07510 for ; Sat, 11 Apr 1998 13:33:12 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 11 Apr 1998 14:28:22 EST From: Jane Anderson / Monty Zukowski Subject: Support for converting existing plain files to noweb in emacs Date: 10 Apr 1998 15:28:54 GMT Message-ID: <6gldrm$nob$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, jamz@cdsnet.net MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit To: LitProg@SHSU.edu I've written an emacs function for noweb mode to help convert plain source into noweb. The idea is that you can select a region of text and do "M-x chunk-text-to-end". You are prompted for a chunk name. The selected text is cut out and replaced with <>. At the end of the file a chunk definition <>= is created with the cut text following. This is my first emacs function ever, and it displays odd behavior when there is no region or selection but I'm clueless as to why that is. Caveat emptor. What follows is from my .emacs file, with the function defined in the noweb-mode-hook. (add-hook 'noweb-mode-hook '(lambda () (defun chunk-text-to-end (start end name) "Cut text out, insert a chunk reference, and put a chunk definition at end of document containing the cut text." (interactive "r\nsChunk name: ") (save-excursion (let ((text (buffer-substring start end))) (kill-region start end) (insert "<<" name ">>\n") (goto-char (point-max)) (insert "<<" name ">>=\n" text "\n") ) ) ) ) ) Enjoy, Monty 11-Apr-1998 20:54:27-GMT,1713;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 OAA08742 for ; Sat, 11 Apr 1998 14:54:26 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 11 Apr 1998 15:50:06 EST From: jamkari@aol.com (Jamkari) Reply-To: LitProg@SHSU.edu, jamkari@aol.com Subject: Need help for a class C++ problem "It looks simple, but I'm stuck !" Message-ID: <1998041120430901.QAA07198@ladder03.news.aol.com> Date: 11 Apr 1998 20:43:09 GMT To: LitProg@SHSU.edu Here is the problem, I appreciate any help ! Thank You ! Write a C++ program that shows the change remaining from a purchase in the following ways. a. Prompt for the price of an object and the amount paid for the object (Perhaps a ten dollars bill for an object that costs $ 3.67) b. Show the number of each kind of items returned (i.e. Number of Fives, Ones, 50 cent pieces, quarters, dimes, nickels and pennies) c. Make sure your program shows how to return the fewest number of items (i.e. a quarter is better than two dimes and a nickel) d. You can assume that the cost and the amount paid are never more than ten dollars. e. No 'loops and conditionals' are allowed. #include void main(void) { double p,a,c; //p is price of object //a is amount paid //c is change cout <<"Type the price of object and press enter"; cin >>p; cout <<"Type the amount paid and press enter"; cin >>a; c=a-p; cout <<"The change is"<; Sat, 11 Apr 1998 14:54:37 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 11 Apr 1998 15:48:26 EST From: mary bos Subject: Re: How to organize analysis, design and implementation documentation Date: 11 Apr 1998 19:46:42 GMT Message-ID: <6gohb2$k6i$1@news.interlog.com> Reply-To: LitProg@SHSU.edu, LitProg@SHSU.edu, bos@bumperkites.org MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" To: LitProg@SHSU.edu Norman Ramsey wrote: >People at Motorola, like Joseph Brothers and Mary Bos (hope I am >getting this right), have done some interesting things with literate >programming and legacy software. Perhaps they can comment. > >>A more basic problem with literate programming as >>practiced using WEB and >>its descendants is that maintenance of the source looks to be even more >>difficult than >>maintenance of plain (but well-written) code. What has your experience >>been in this >>regard? > When I worked at Motorola, we were adding noweb items to modules we were working on at the time instead of trying to do all of the code. Usually as part of attempting to do a Fagan Inspection or just training other people on the code. Fortunately (?!?) most of our code was in K&R C using an embedded operating system. Joseph Brothers wrote some tools to give an initial framework for noweb but it was still a grind to add the details. We figured it would take quite an effort to do our 250-500 KALOC - so our biggest problem was more organization and how to tie the documentation for the semi-independent tasks together (this code was quite intertwined between tasks - so the interdependencies were interesting and sometimes quite surprising). Gary Young was working on a Great Books concept while all three of us (Gary, Joseph, and myself) were working at Motorola WDG. The documentation could be monolithic so just the organizational framework would be important. Again our emphasis was documenting code and trying to capture design and requirement decisions. Gary and I are still carrying on discussions on this topic, so at this point organization seems to be more along your corporate coding and design style. Unfortunately our project at Motorola was dropped when we all were laid-off. mary Mary Bos email: bos@bumperkites.org Team BumperKites http://www.bumperkites.org Sanity takes its toll and you must have exact change - so go fly a kite 12-Apr-1998 0:30:08-GMT,1112;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 SAA11813 for ; Sat, 11 Apr 1998 18:30:07 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 11 Apr 1998 19:26:32 EST From: Diego Zamboni Reply-To: LitProg@SHSU.edu, zamboni@cs.purdue.edu Subject: Prettyprinting Perl? Date: 11 Apr 1998 23:59:40 GMT Message-ID: <6gp05c$f3j$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 (generated by tm-edit 7.106) Content-Type: text/plain; charset=US-ASCII To: LitProg@SHSU.edu Hi, I believe that this is asking for the impossible, but I will ask anyway: does anybody know if someone has tried to write a noweb prettyprinter for Perl? This would probably be a futile attempt, but maybe even something as what perl-mode/cperl-mode do in Xemacs when font-lock-mode is on could be nice. I'm just curious. Thanks, --Diego 12-Apr-1998 22:12:37-GMT,1469;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 QAA29638 for ; Sun, 12 Apr 1998 16:12:36 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 12 Apr 1998 17:09:16 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: "Incomplete" grammars Date: 11 Apr 1998 15:34:28 GMT Message-ID: <6go2i4$2mg$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu In a recent posting, I used the term "incomplete" grammar, because (in my senility), I could not remember the proper term. The proper term is, of course, "context-sensitive" grammar. I apologize for any inconvenience (or erroneous conclusions) my mistake may have caused. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 16-Apr-1998 8:35:09-GMT,1324;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 CAA05563 for ; Thu, 16 Apr 1998 02:35:08 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 16 Apr 1998 03:30:31 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: noweb postcards Date: 15 Apr 1998 17:53:24 GMT Message-ID: <6h2s6k$ief$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I'm finally getting a chance to scan the postcards that noweb users have sent me over the years, and I will soon be putting them on the web. (This way, the next time a repairman floods my office with air-conditioning coolant, I will have backups of the postcards.) If you have sent me a postcard, and if you prefer that your email address *not* appear on the web page, please let me know. Of course, if you have not sent me a postcard, and you wish you had, there will never be a better time :-) Norman Ramsey Department of Computer Science University of Virginia Charlottesville, VA 22903 N -- Norman Ramsey http://www.cs.virginia.edu/~nr 17-Apr-1998 4:25:17-GMT,2584;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 WAA11949 for ; Thu, 16 Apr 1998 22:25:16 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from indy03.cs.monash.edu.au by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 16 Apr 1998 23:20:55 EST Received: from localhost (ajh@localhost) by indy03.cs.monash.edu.au (8.8.8/8.8.8) with SMTP id OAA12856; Fri, 17 Apr 1998 14:20:48 +1000 (EST) Message-ID: <199804170420.OAA12856@indy03.cs.monash.edu.au> To: LitProg@SHSU.edu, jamz@cdsnet.net Subject: Re: Support for converting existing plain files to noweb in emacs MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Fri, 17 Apr 1998 14:20:47 +1000 From: John Hurst Reply-To: LitProg@SHSU.edu, ajh@cs.monash.edu.au On 10 Apr at 15:28, you wrote: > I've written an emacs function for noweb mode to help convert plain > source into noweb. The idea is that you can select a region of text > and do "M-x chunk-text-to-end". You are prompted for a chunk name. > The selected text is cut out and replaced with <>. At the > end of the file a chunk definition <>= is created with the > cut text following. > > This is my first emacs function ever, and it displays odd behavior when > there is no region or selection but I'm clueless as to why that is. > Caveat emptor. I have written a similar sort of function, and find that the behaviour is different between xemacs and emacs. You don't mention which one it is, but I found that emacs gives this behaviour, while xemacs works "as you'd expect". You might care to try it out on the opposite one to the one you are using: my guess is that there is either a bug in emacs, or some very subtle differences in behaviour, which I haven't as yet been able to suss out from the documentation. I was using (region-beginning) and (region-end), but I think the essence is much the same. Good luck! --John Hurst -- Associate Dean (Teaching), Faculty of Information Technology -- Associate Professor, School of Computer Science and Software Engineering --rm 110/26, Computer Science, Monash, Clayton VIC 3168 ~ ~~~&#: --ajh@cs.monash.edu.au _..___ ---____@___H__ --+61 3 9905 5192 (fax +61 3 9905 5146) |_____[_|_________[__]_ --http://www.cs.monash.edu.au/~ajh oo oo oo O--O--O o=o 17-Apr-1998 14:04:31-GMT,2646;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 IAA15115 for ; Fri, 17 Apr 1998 08:04:30 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 17 Apr 1998 08:50:31 EST From: "Markus.Oellinger" Reply-To: LitProg@SHSU.edu, ollinger@xenon.pseg.siemens.at Subject: I do not reorder! Date: 17 Apr 1998 11:15:35 GMT Message-ID: <6h7dkn$rj$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu As you all know, literate programming is distinct from programming with many comments. You can reorder code parts and present them in a way easier to understand for human beings. I have found that modern programming languages have made this reordering of code sections unnecessary or at least not so important than in former days. You need no <> and <> sections in Java, since there are none. Exceptions made it unnecessary to put the error handling (or otherwise uninteresting) stuff in a separate section. As for Java, I find it most often unnecessary to do any reordering. I can present the methods and instance variables in any order I want anyway without reordering. I almost never use those descriptor-type section names (i.e. collections of related code parts) with Java (although they would be pretty handy with a language like Pascal). I wonder if modern languages like Java will make literal programs and programs with exhaustive comments equal. Literate programming tools are reduced to cross-referencers and markup tools. For me, the most useful feature of the LP tools is to make it possible to present a program in a hierarchical way (@*1 in CWEB, \section{} in noweb) to group related parts. Still, it seems that for a modern programming language, the focus of literate programming should be more on the way of commenting (choice of proper names, cohesion, coupling, order in which information is presented in code, good general introduction, whole sentences, ...) and less on "reordering" tools. I think what Knuth called the "explanatory mode" you are in when writing a program is the real valuable point. Literate programming means: do more commenting, do better commenting; well, we always knew that (and we would if we had the time :-) ). Markus. There is no WEB anymore, things are straightforward. 18-Apr-1998 4:09:34-GMT,1216;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 WAA12820 for ; Fri, 17 Apr 1998 22:09:33 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 17 Apr 1998 23:06:17 EST From: pbewig@netcom.com (Phil Bewig) Reply-To: LitProg@SHSU.edu, pbewig@netcom.com Subject: Re: I do not reorder! Message-ID: Date: Sat, 18 Apr 1998 04:04:49 GMT To: LitProg@SHSU.edu Peter Hancock writes: >Haskell even has a so-called "Bird-style literate programming mode" >(named after Richard Bird, in which each line of code starts >with a `>' in column 1. By default, you are in the commentary. It >makes me wonder "Is that all there is to it?". That is, apart from the >small problem of deciding what exactly to say. >(Perhaps someone can hack up a perl script or Icon program >to automate this?) Does this untested sed program work? sed -n '/^>/s/.//p' Phil -- Phil Bewig ... pbewig@netcom.COM 20-Apr-1998 9:18:14-GMT,1201;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 DAA20747 for ; Mon, 20 Apr 1998 03:18:14 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from elvardien.southpoly.ac.nz by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Apr 1998 04:06:54 EST Received: from southpoly.ac.nz (b224-9.southpoly.ac.nz [202.50.90.209]) by elvardien.southpoly.ac.nz (8.8.5/8.8.5) with ESMTP id VAA03888 for ; Mon, 20 Apr 1998 21:10:07 +1200 Message-ID: <353B0FF5.781DE3BC@southpoly.ac.nz> Date: Mon, 20 Apr 1998 21:05:57 +1200 From: Your Name Reply-To: LitProg@SHSU.edu, user@southpoly.ac.nz MIME-Version: 1.0 To: LitProg@SHSU.edu Subject: QBasic Compiling Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit I too am interested in compiling some of my hard work done in QBasic.. if you get a reply would it be OK to let me in on it ? I'd appreciate it . Regards Kevin Harris. New Zealand Kevinh@southpoly.ac.nz 20-Apr-1998 13:17:07-GMT,2033;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 HAA26584 for ; Mon, 20 Apr 1998 07:17:06 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Apr 1998 08:02:18 EST From: Peter Hancock Subject: Re: I do not reorder! Date: 18 Apr 1998 02:24:21 GMT Message-ID: <6h92sl$sql$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, pgh@dcs.ed.ac.uk MIME-Version: 1.0 (generated by tm-edit 7.108) Content-Type: text/plain; charset=US-ASCII To: LitProg@SHSU.edu "Markus.Oellinger" writes: > I have found that modern programming languages have made this reordering > of code sections unnecessary or at least not so important than in former > days. A good example is Haskell (http://www.haskel.org/). Leaving modules out of it, there are no constraints on the order of definitions. Haskell even has a so-called "Bird-style literate programming mode" (named after Richard Bird, in which each line of code starts with a `>' in column 1. By default, you are in the commentary. It makes me wonder "Is that all there is to it?". That is, apart from the small problem of deciding what exactly to say. Of course most programming languages are much more tyrannical about the order of things in your program, and its nice to have simple tools that release you from the tyranny. Perhaps this is only slightly-less-encumbered programming rather than literate programming. > Literate programming means: do more commenting, do better commenting; > well, we always knew that (and we would if we had the time :-) ). Maybe its not only about the comments, but also the code. Write better, clearer, more obvious code. (Perhaps someone can hack up a perl script or Icon program to automate this?) Peter 20-Apr-1998 13:17:51-GMT,2475;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 HAA26619 for ; Mon, 20 Apr 1998 07:17:50 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Apr 1998 08:02:42 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: I do not reorder! Date: 18 Apr 1998 02:41:54 GMT Message-ID: <6h93ti$t8q$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6h7dkn$rj$1@murdoch.acc.Virginia.EDU>, Markus.Oellinger wrote: >As you all know, literate programming is distinct from programming with >many comments. You can reorder code parts and present them in a way >easier to understand for human beings. > >I have found that modern programming languages have made this reordering >of code sections unnecessary or at least not so important than in former >days. I have had similar experiences, which were especially noticeable when moving from C to Modula-3. M3 has exceptions and does not require declaration before use. I still find myself using the ability to reorder when writing large functions that compute by case analysis. When more than one or two cases are nontrivial, it is useful to present the case analysis in one chunk, then each individual case in its own chunk. I could do this using functions, but it feels odd to me to define a function the only conceivable use of which is to be called from a single place. (Functions that *are* only called once, but *might* one day be called from somewhere else, are OK.) In non-functinoal languages, I also find myself using the chunking mechanism for tiny `procedural' abstractions that aren't part of case analyses but for which procedures seem too heavyweight. Typical junks might include <> or <> In these cases, chunking is less for reordering; it is just another abstraction mechanism. When writing imperative code, I find it easier to come up with descriptive chunk names than function names. I won't write complainThatStorageWasPrevouslyDeclaredAt(c, loc) and some compilers don't care for it either. 20-Apr-1998 14:46:26-GMT,4829;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 IAA29508 for ; Mon, 20 Apr 1998 08:46:25 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Apr 1998 09:25:40 EST From: Balasubramanian Narasimhan Reply-To: LitProg@SHSU.edu, naras@stat.stanford.edu Subject: Re: I do not reorder! Date: 17 Apr 1998 17:03:06 GMT Message-ID: <6h820a$ch3$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu "Markus.Oellinger" writes: > > As you all know, literate programming is distinct from programming with > many comments. You can reorder code parts and present them in a way > easier to understand for human beings. > > I have found that modern programming languages have made this reordering > of code sections unnecessary or at least not so important than in former > days. You need no <> and <> sections in Java, > since there are none. Exceptions made it unnecessary to put the error > handling (or otherwise uninteresting) stuff in a separate section. > > As for Java, I find it most often unnecessary to do any reordering. I > can present the methods and instance variables in any order I want > anyway without reordering. I almost never use those descriptor-type > section names (i.e. collections of related code parts) with Java > (although they would be pretty handy with a language like Pascal). > > I wonder if modern languages like Java will make literal programs and > programs with exhaustive comments equal. Literate programming tools are > reduced to cross-referencers and markup tools. For me, the most useful > feature of the LP tools is to make it possible to present a program in a > hierarchical way (@*1 in CWEB, \section{} in noweb) to group related > parts. > > Still, it seems that for a modern programming language, the focus of > literate programming should be more on the way of commenting (choice of > proper names, cohesion, coupling, order in which information is > presented in code, good general introduction, whole sentences, ...) and > less on "reordering" tools. I think what Knuth called the "explanatory > mode" you are in when writing a program is the real valuable point. > > Literate programming means: do more commenting, do better commenting; > well, we always knew that (and we would if we had the time :-) ). > > Markus. > > > There is no WEB anymore, things are straightforward. The equality may be achieved for some code, not all. Also, if you think that reordering, commenting, meaningful variable and routine names are the main issues, you will be missing the forest for the trees. Freedom and clarity are some (in fact, the, IMHO) main issues, and others derive from them. This, hopefully, leads to programs comprehensible to humans and other good features follow. You are unfettered in the way you think your programs can be best presented. No more incomplete sentences---you can actually describe your code chunks in proper english or any other language, pepper your descriptions with bibliographic references and quotes if you are so inclined, use mathematical typesetting (I use this a lot since many of the algorithms I program are mathematical in nature), throw in pictures or snapshots of what your code does if that helps, and so on. JAVADOC does many of these things too, but for me math typesetting is essential. As a person who has written plenty of JAVA code, I actually find JAVA fits nicely into LP. JAVADOC is a useful tool and can be exploited in conjunction with Noweb. Lee Wittenberg will have plenty to add. LP tools and JAVADOC are fundamentally different. JAVADOC generates documentation from code while LP tools do the opposite. Here is something you cannot do with JAVADOC or your model of programming: inlining. There are cases where I have a piece of code that does a complicated calculation: an example can be seen in my software for dynamic graphics in Bayesian Survival Analysis (available from my web page). It is compute-intensive and so I want to inline it in several routines and not deal with the overhead of subroutines or methods. Noweb allows me to do precisely that, by defining a code chunk and lets me reuse it in several places. Thus, as Norman Ramsey says, verisimilitude is preserved; if the complicated formula changes, I change it one place and it is propagated. ________________________________________________________________ B. Narasimhan naras@stat.stanford.edu http://www-stat.stanford.edu/~naras 20-Apr-1998 23:00:57-GMT,1765;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 RAA18988 for ; Mon, 20 Apr 1998 17:00:56 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Apr 1998 17:56:32 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: Re: I do not reorder! Date: 18 Apr 1998 17:47:17 GMT Message-ID: <6haov5$jhj$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 17 Apr 1998 11:15:35 GMT, "Markus.Oellinger" wrote: > I have found that modern programming languages have made this reordering > of code sections unnecessary or at least not so important than in former > days. You need no <> and <> sections in Java, [...] > I wonder if modern languages like Java will make literal programs and > programs with exhaustive comments equal. Literate programming tools are A program with exhaustive comments is not much more than a potentially large and unstructured set of source files. The most productive order to read them for understanding the application is often not obvious, even for subsystems. A literate program based on the book paradigm may add value to such a set of files by putting each of them in context, and by offering a carefully crafted reading, understanding and learning path. In other words, it puts more emphasis on the big picture. Paolo -- Paolo Amoroso 21-Apr-1998 1:35:10-GMT,2407;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 TAA23687 for ; Mon, 20 Apr 1998 19:35:09 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 20 Apr 1998 20:27:14 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: How to apply GPL to literate programs Date: 18 Apr 1998 08:37:27 GMT Message-ID: <6h9oo7$89i$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu I'm wondering what is the best way of applying Free Software Foundation's General Public License - GPL - to literate programs. Consider for example an application developed with noweb whose documentation is typeset with LaTeX. If it's non trivial, the program probably comes with a makefile which extracts a set of source and LaTeX files from a number of web files. Applying GPL to the source files is trivial. The makefile can take care of adding at the beginning of each source file the standard message mentioned in the GPL (i.e. the one stating that the application is free software and referring to the file COPYING for the full licensing terms). Let's call this "GPL pointer" for later reference. Webs may include a similar notice, which can be automatically added to LaTeX sources by the makefile. But what about the _printed_ documentation? Since it is a printed document, it would make sense to include a copyright statement similar to the one found at the beginning of GNU manuals, which grants permissions for verbatim, modified and translated copies. We can call this "copying permissions list". But the printed documentation of a woven application contains the full source code, albeit rearranged with a different structure. So which copyright notice has to be included in the documentation? The GPL pointer? The copying permissions list? Both of them? If so, are they contradictory (I ask this question because I'm not a lawyer...)? What about your experience with GPL and literate programs? I would appreciate any suggestions or information. Thanks in advance. Paolo -- Paolo Amoroso 21-Apr-1998 6:27:47-GMT,2142;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 AAA05696 for ; Tue, 21 Apr 1998 00:27:46 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 21 Apr 1998 01:22:48 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: I do not reorder! Date: 20 Apr 1998 15:30:48 GMT Message-ID: <6hfpn8$prl$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 17 Apr 1998, Balasubramanian Narasimhan wrote: > As a person who has written plenty of JAVA code, I actually find JAVA > fits nicely into LP. JAVADOC is a useful tool and can be exploited in > conjunction with Noweb. Lee Wittenberg will have plenty to add. Not really :-) > LP tools and JAVADOC are fundamentally different. JAVADOC generates > documentation from code while LP tools do the opposite. Here is > something you cannot do with JAVADOC or your model of programming: > inlining. I agree completely with this. Actually, JAVADOC is a stripped-down version of a truly wonderful Eiffel utility called "short" (flat-short?), which not only shows the interface for a class, but can compress the inheritance hierarchy to show the client *all* the methods available for use. As you say, JAVADOC and short serve a different (but not unimportant) purpose than LP. It's always important to remember to choose the proper tool for the job. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 21-Apr-1998 21:47:30-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 PAA20518 for ; Tue, 21 Apr 1998 15:47:27 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 21 Apr 1998 16:17:07 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 19 Apr 1998 10:55:00 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.edu Archive-name: literate-programming-faq Last-modified: 1997/08/15 Version: 1.1.18 The Literate Programming FAQ David B. Thompson 15 August 1997 This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. ______________________________________________________________________ Table of Contents: 1. Welcome 1.1. Disclaimer 1.2. Copyright 1.3. What's New? 2. Introduction or 3. How do I get the FAQ? 3.1. Literate Programming FAQ 3.2. FWEB FAQ 4. Is there a newsgroup? 5. What internet nodes are of interest to literate programmers? 6. What is Literate Programming? 7. How do I begin literate programming? 8. What literate programming tools are available? 8.1. APLWEB 8.2. AWEB 8.3. CLiP 8.4. CWEB 8.5. CWEBx3.0 8.6. mCWEB 8.7. FunnelWeb 8.8. FunnelWeb 3.0AC 8.9. FWEB 8.10. IMPACT 8.11. lit2x 8.12. Literate Programmer's Workshop (LPW) 8.13. MapleWEB 8.14. MWEB (Schrod/Detig) 8.15. MWEB (Sewell) 8.16. noweb 8.17. nuweb 8.18. ProTeX 8.19. RWEB 8.20. SchemeWEB 8.21. SpideryWEB 8.22. WEB 8.23. WinWordWEB 9. Are there other tools I should know about? 9.1. C2LaTeX 9.2. c2cweb 9.3. c2man 9.4. cnoweb 9.5. Fold2Web 9.6. Funnelweb Mode 9.7. noweb.el 9.8. nuweb.el 9.9. TIE 9.10. Web mode 10. What other resources are available? 10.1. World Wide Web 10.2. TeX Resources 11. Are there any code examples? 12. Bibliographies 13. How to anonymously ftp 14. Acknowledgements 15. End notes ______________________________________________________________________ 1. Welcome Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 1.1. Disclaimer Disclaimer: ``This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk.'' 1.2. Copyright Copyright 1993-1997 by David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: 1.3. What's New? o My email address has changed (once again). o Newsgroup is moderated. o Updated fweb entry. o Updated noweb entry. o Added mCWEB entry. o Updated c2cweb entry. o Updated nuweb.el entry. o Updated cLiP entry. o Updated Lee W's examples (from bart). o Last, but not least, new formatting of the FAQ. Many thanks go to Andrew Johnson for helping make this happen. 2. Introduction or ``What's this all about?'' This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson Comments and constructive criticisms are welcome. Direct flames to /dev/null (or nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is not complete, and probably will never be complete. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. 3. How do I get the FAQ? 3.1. Literate Programming FAQ You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled ``Internet Nodes of Interest to Literate Programmers''.) 3.2. FWEB FAQ David Coker maintains the FWEB FAQ. The current version number is 1.30a. It can be retrieved in the same way as this FAQ. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de 131.169.10.115 in directory /pub/faq/web/fweb/. It is also available from the literate programming archive in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). 4. Is there a newsgroup? One of the most important resources is the literate programming newsgroup, comp.programming.literate. Because of the amount of spamming and unrelated the posts, the newsgroup is now moderated. Posts to the newsgroup are now routed through litprog- mod@cs.virginia.edu. If your news reader does not post through this address, then you will be unable to post messages to the newgroup. You can read this newsgroup using your standard reader. 5. What internet nodes are of interest to literate programmers? The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. Participating hosts in the Comprehensive TeX Archive Network are: ftp.dante.de (Deutschland) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node sun.dante.de -- e-mail via ftpmail@dante.de -- Administrator: ftp.tex.ac.uk (England) -- anonymous ftp /tex-archive (/pub/tex /pub/archive) -- gopher on node gopher.tex.ac.uk -- NFS mountable from nfs.tex.ac.uk:/public/ctan/tex-archive -- World Wide Web access on www.tex.ac.uk -- Administrator: The site ftp.shsu.edu used to be the American CTAN site. Apparently, that site has fallen into disrepair and should not be considered a primary source for either TeX related or literate programming related material. For the record, the address is: ftp.shsu.edu (Texas, USA) -- anonymous ftp and gopher /tex-archive (/pub/tex /pub/archive) -- NFS mountable from ftp.SHSU.edu:/pub/ftp/tex-archive -- e-mail via ftpmail@ftp.SHSU.edu -- World Wide Web access on www.SHSU.edu -- Administrator: A list of CTAN archive sites and their mirrors can be found on: ftp.dante.de:/tex-archive/CTAN.sites I presume that the other CTAN sites mirror this file, but have not checked. As of my last check (September 1994), it contains: "In order to reduce network load, it is recommended that you use the Comprehensive TeX Archive Network (CTAN) host which is located in the closest network proximity to your site." Known partial mirrors of the CTAN reside on (alphabetically): dongpo.math.ncu.edu.tw (Taiwan) /tex-archive ftp.adfa.oz.au (Australia) /pub/tex/ctan ftp.muni.cz (The Czech Republic) /pub/tex/CTAN ftp.cs.ruu.nl (The Netherlands) /pub/tex-archive ftp.uu.net (Virginia, USA) /pub/text-processing/TeX nic.switch.ch (Switzerland) /mirror/tex Known mirrors of the CTAN reside on (alphabetically): ftp.center.osaka-u.ac.jp (Japan) /CTAN ftp.ccu.edu.tw (Taiwan) /pub/tex ftp.cs.rmit.edu.au (Australia) /tex-archive ftp.duke.edu (North Carolina, USA) /tex-archive ftp.germany.eu.net (Deutschland) /pub/packages/TeX ftp.gwdg.de (Deutschland) /pub/dante ftp.jussieu.fr (France) /pub4/TeX/CTAN ftp.loria.fr (France) /pub/unix/tex/ctan ftp.mpi-sb.mpg.de (Deutschland) /pub4/tex/mirror/ftp.dante.de ftp.uni-bielefeld.de (Deutschland) /pub/tex ftp.uni-stuttgart.de (Deutschland) /tex-archive (/pub/tex) ftpserver.nus.sg (Singapore) /pub/zi/TeX src.doc.ic.ac.uk (England) /packages/tex/uk-tex sunsite.unc.edu (North Carolina, USA) /pub/packages/TeX wuarchive.wustl.edu (Missouri, USA) /packages/TeX Other nodes and directories of interest include: Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ 6. What is Literate Programming? Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system pro- grammer, who wants to provide the best possible documenta- tion of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To docu- ment such a program we want to explain each individual part of the web and how it relates to its neighbours. The typo- graphic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combin- ing the two, we can develop a style of programming that max- imizes our ability to perceive the structure of a complex piece of software, and at the same time the documented pro- grams can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why. Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM ref. 1 plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References 1 Paul W. Oman and Curtus Cook. ``Typographical style is more than cosmetic.'' CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called ``informal rigour'', i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 Another author (Norman Ramsey) wrote me and asked that his opinions be included in the FAQ. What follows are Norman's comments verbatim. I see it's time for the ``how is literate programming dif- ferent from verbose commenting'' question. Perhaps David Thompson will get this into the FAQ. Alert! What follows are my opinions. In no way do I claim to speak for the (fractious) literate-programming community. How is literate programming different from verbose commenting? There are three distinguishing characteristics. In order of importance, they are: o flexible order of elaboration o automatic support for browsing o typeset documentation, especially diagrams and mathematics Flexible order of elaboration means being able to divide your source program into chunks and write the chunks in any order, independent of the order required by the compiler. In principle, you can choose the order best suited to explaining what you are doing. More subtly, this discipline encourages the author of a literate program to take the time to consider each fragment of the program in its proper sphere, e.g., not to rush past the error checking to get to the ``good parts.'' In its time and season, each part of the program is a good part. (This is the party line; your mileage may vary.) I find the reordering most useful for encapsulating tasks like input validation, error checking, and printing output fit for humans --- all tasks that tend to obscure ``real work'' when left inline. Reordering is less important when using languages like Modula-3, which has exceptions and permits declarations in any order, than when using languages like C, which has no exceptions and requires declaration before use. Automatic support for browsing means getting a table of contents, index, and cross-reference of your program. Cross-reference might be printed, so that you could consult an index to look up the definition of an identifier `foo'. With good tools, you might get a printed mini-index on every page if you wanted. Or if you can use a hypertext technology, cross-reference might be as simple as clicking on an identifier to reach its definition. Indexing is typically done automatically or `semi- automatically', the latter meaning that identifier definitions are marked by hand. Diligently done semi- automatic indexes seem to be best, because the author can mark only the identifiers he or she considers important, but automatic indexing can be almost as good and requires no work. Some tools allow a mix of the two strategies. Some people have applied literate-programming tools to large batches of legacy code just to get the table of contents, index, and cross-reference. I don't use diagrams and mathematics very often, but I wouldn't want to have to live without them. I have worked on one or two projects where the ability to use mathematical formulae to document the program was indispensible. I also wouldn't like to explain some of my concurrent programs without diagrams. Actually I write almost all of my literate programs using only sections headers, lists, and the occasional table. >Wouldn't it be easier to do one's literate programming using >a wysiwyg word processor (e.g. Word for Windows) and >indicate what is source code by putting it in a different >font? The data formats used in wysiwyg products are proprietary, and they tend to be documented badly if at all. They are subject to change at the whim of the manufacturer. (I'll go out on a limb and say there are no significant wysiwyg tools in the public domain. I hope the Andrew people will forgive me.) These conditions make it nearly impossible to write tools, especially tools that provide automatic indexing and cross-reference support. The CLiP people have a partial solution that works for tools that can export text --- they plant tags and delimiters throughout the document that enable the reordering transformation (``tangling''). People use TeX, roff, and HTML because free implementations of these tools are widely available on a variety of platforms. TeX and HTML are well documented, and TeX and roff are stable. TeX is the most portable. I think I have just answered the FAQ ``how come all these tools use TeX, anyway?'' :-) Norman Ramsey 7. How do I begin literate programming? A recommended book is D.E. Knuth's collection of articles (1992) Literate Programming. Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) Weaving a Program: Literate Programming in WEB. Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. 8. What literate programming tools are available? A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) 8.1. APLWEB Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. 8.2. AWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. 8.3. CLiP Developer: E.W. van Ammers and M.R. Kramer Versions: 2.0 and 2.4b (DOS only) Platform: Vax/VMS, Unix, DOS Languages: Any programming language Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, HTML, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, WinWord, Ami Pro, Word Pro, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos DOS sun01.info.wau.nl:/CLIP/ms_dos_24b DOS (v. 2.4b) sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS sun01.info.wau.nl:/CLIP/unix Unix CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicit commands to perform the extraction process. Rather it recognizes pseudostatements written as comments in the programming language in question. CLiP distinguishes pseudostatements from ordinary comments because the former comply with a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well. Some hypertext examples are at ftp://sun01.info.wau.nl/clip/html/queens.htm ftp://sun01.info.wau.nl/clip/html/pal1.htm Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentation my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segments. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail to Eric.vanAmmers@user.info.wau.nl 8.4. CWEB Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu 8.5. CWEBx3.0 Developer: Marc van Leeuwen Version: Unknown Hardware: Any system using ASCII code Languages: ANSI C Formatter: Plain TeX Availability: Anonymous ftp from: ftp.cwi.nl/pub/cweb Readme: Bundled with above Brief description: A modified implementation of CWEB, with some extensions. Provides a mode for full compatibility with Levy/Knuth CWEB. The most significant extras are: - Typedef declarations affect formatting througout source file - Include files are scanned for typedef definitions - Flexible selection of layout style - Possibility to refer to sections using symbolic labels - CTANGLE detects unbalanced braces and parentheses - CWEAVE can be made to report syntax errors more easily - Some additional mechanisms to avoid formatting problems - New and modular set of grammar rules, based on ANSI C syntax - Possibility to suppress #line directives - A new manual Support: bugs and remarks to M.van.Leeuwen@cwi.nl 8.6. mCWEB Developer: Markus Oellinger Version: 1.0 Hardware: Unix Languages: C/C++ Formatter: plainTeX Availability: anonymous ftp from ist.tu-graz.ac.at:/pub/utils/litprog/mcweb/mcweb.tgz Readme: at same location Description: This is mCWEB 1.0, a descendant of the CWEB system of structured documentation by Donald E. Knuth and Silvio Levy. It adds some features that are indispensable when working in a team. mCWEB regards a project of a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface documentation is now also part of mCWEB. It is extracted into a second TeX file. This makes it possible to define well known interfaces between the individual parts of a project that will be implemented by different persons. In addition, mCWEB parses C header files to find out about all the datatypes defined there. mCWEB comes with a full completely rewritten user manual and is compatible with CWEB. Support: Institute of Software Technology moell@ist.tu-graz.ac.at 8.7. FunnelWeb Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. 8.8. FunnelWeb 3.0AC Developer: Enhanced by A.B.Coates (coates@physics.uq.edu.au) from FunnelWeb v3.0 by Ross N. Williams (ross@guest.adelaide.edu.au) Version: 3.0AC Hardware: MSDOS, Mac, VMS, Sun, OSF/1, Linux, Sys.V, OS/2. Languages: No restrictions. Formatter: Tex, LaTeX, or HTML. Availability: Anonymous ftp from ftp.physics.uq.oz.au:/pub/funnelwebAC30.tar.gz Readme: With bundle above; for FunnelWeb manual see WWW page http://www.physics.uq.oz.au:8001/people/coates/funnelweb.html Description: FunnelWeb 3.0AC is an enhanced version of FunnelWeb (see the entry for FunnelWeb). FunnelWeb is designed to be typesetter independent, though FunnelWeb v3.0 only supports (La)TeX as the typesetter. FunnelWeb 3.0AC also supports HTML, and creates appropriate hypertext links within the document among the code sections. FunnelWeb 3.0AC also supports automatic and manual insertion of line directives, so that compiler errors can be flagged back to the original FunnelWeb source file. FunnelWeb 3.0AC is completely compatible with FunnelWeb v3.0 sources (with one minor exception; see the file README.ABC which comes with the FunnelWeb 3.0AC distribution). Support: Supported by A.B.Coates (coates@physics.uq.edu.au), subject to the time constraints imposed by his thesis. 8.9. FWEB Developer: John A. Krommes Version: 1.53 (1.60-beta for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: LaTeX. Plain TeX may work, but is no longer supported. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu 8.10. IMPACT Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. 8.11. lit2x Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown 8.12. Literate Programmer's Workshop (LPW) Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. 8.13. MapleWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown 8.14. MWEB (Schrod/Detig) Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.15. MWEB (Sewell) Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. 8.16. noweb Developer: Norman Ramsey Version: 2.8 Hardware: Unix and DOS platforms (DOS binaries available for v2.7). Languages: All programming languages, singly or in combination. Automatic indexing for C, Icon, Pascal, Standard ML, TeX, Yacc Formatter: Plain TeX, LaTeX, and HTML formatters. Will convert LaTeX to HTML automatically. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent Last recourse, use ftp.cs.virginia.edu:pub/nr Readme: With bundle above, or see the noweb home page: http://www.cs.virginia.edu/~nr/noweb Those without ftp access can consult ``Literate Programming Simplified,'' IEEE Software, September 1994, pp97-105. Description: noweb is designed to meet the needs of literate programmers while retaining the simplest possible input format. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. The noweb manual is only 3 pages; an additional page explains how to customize its LaTeX output. noweb works ``out of the box'' with any programming language, and supports TeX, latex, and HTML back ends. A back end to support full hypertext or indexing takes about 250 lines; a simpler one can be written in 40 lines of awk. The primary sacrifice relative to WEB is that code is not prettyprinted. noweb supports indexing and identifier cross-reference, including hypertext ``hot links.'' noweb includes a simple, efficient LaTeX-to-HTML converter, so you can use hypertext browsers on your legacy documents. noweb can also process nuweb programs, so you can use noweb to convert a standard nuweb program to HTML with one command. Support: email to the author 8.17. nuweb Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu 8.18. ProTeX Developer: Eitan Gurari Version: ProTeX 1.1, AlProTeX 1.4 Hardware: Any platform with (La)TeX Languages: Any language Formatter: TeX or LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: With bundle above Description: + Easy to use + Extensible + Language independent + Multiple output files + Fast (single compilation provides output and dvi files) + No installation is needed besides copying the files (written in TeX) Introduction of main features and examples in pub/tex/osu/gurari/LitProg Complete manual in Eitan M. Gurari, "TeX and LaTeX: Drawing and Literate Programming", McGraw-Hill, 1994 Support: gurari@cis.ohio-state.edu 8.19. RWEB Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown 8.20. SchemeWEB Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. 8.21. SpideryWEB Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. 8.22. WEB Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. 8.23. WinWordWEB Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. 9. Are there other tools I should know about? First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. 9.1. C2LaTeX Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. 9.2. c2cweb Developer: Werner Lemberg Version: 1.5 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg 9.3. c2man language: C, nroff, texinfo, latex, html package: c2man version: 2.0 patchlevel 33 parts: documentation generator (C -> nroff -man, -> texinfo, ->latex, -> html) author: Graham Stoney location: ftp from any comp.sources.misc archive, in volume42 (the version in the comp.sources.reviewed archive is obsolete) ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from archie.au N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* from ftp.wustl.edu Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* from ftp.irisa.fr Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* from ftp.iij.ad.jp Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se description: c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. conformance: supports both K&R and ISO/ANSI C coding styles features: + generates output in nroff -man, TeXinfo, LaTeX or HTML format + handles comments as part of the language grammar + automagically documents enum parameter & return values + handles C (/* */) and C++ (//) style comments - doesn't handle C++ grammar (yet) requires: yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX. ports: Unix, OS/2, MSDOS, VMS. portability: very high for unix, via Configure status: actively developed; contributions by users are encouraged. discussion: via a mailing list: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au help: from the author and other users on the mailing list: c2man@research.canon.oz.au announcements: patches appear first in comp.sources.bugs, and then in comp.sources.misc. updated: 1994/10/07 9.4. cnoweb Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. 9.5. Fold2Web Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de 9.6. Funnelweb Mode Developer: Daniel Simmons Version: Unknown Availability: http://www.miscrit.be/~ddw Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown 9.7. noweb.el Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk 9.8. nuweb.el Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@acm.org 9.9. TIE Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown 9.10. Web mode Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown 10. What other resources are available? 10.1. World Wide Web An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html or use a WWW browser and access the URL ftp://rtfm.mit.edu/pub/usenet/news-answers/www/resources/literate-programming Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to rtfm.mit.edu and retrieve the official Usenet resource file /pub/usenet/news.answers/www/resources/literate-programming 10.2. TeX Resources Another resource of interest to literate programmers is the comp.text.tex newsgroup. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this resource. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. 11. Are there any code examples? Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au 129.127.40.3 as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: ftp://samson.kean.edu/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is writ- ten in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb 12. Bibliographies Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu 128.110.198.2 in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says sev- eral times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. 13. How to anonymously ftp Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu 18.181.0.24, under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. 14. Acknowledgements This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. 15. End notes This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. 22-Apr-1998 19:00:19-GMT,831;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 NAA17667 for ; Wed, 22 Apr 1998 13:00:18 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 22 Apr 1998 13:21:32 EST From: frank02131@aol.com (Frank02131) Reply-To: LitProg@SHSU.edu, frank02131@aol.com Subject: QBASIC Message-ID: <1998042218050000.OAA09392@ladder03.news.aol.com> Date: 22 Apr 1998 18:05:00 GMT To: LitProg@SHSU.edu Please could you help me. I have been looking for a copy of QBASIC 4.5 to download/buy for as long as I can remember now. Please help. Frank. frank02131@aol.com 23-Apr-1998 3:21:58-GMT,3244;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 VAA04521 for ; Wed, 22 Apr 1998 21:21:57 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 22 Apr 1998 22:15:57 EST From: "Markus.Oellinger" Reply-To: LitProg@SHSU.edu, ollinger@xenon.pseg.siemens.at Subject: Re: I do not reorder! Date: 20 Apr 1998 11:28:54 GMT Message-ID: <6hfbhm$ibo$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Paolo Amoroso wrote: > > On 17 Apr 1998 11:15:35 GMT, "Markus.Oellinger" > wrote: > > > I wonder if modern languages like Java will make literal programs and > > programs with exhaustive comments equal. Literate programming tools are > > A program with exhaustive comments is not much more than a potentially > large and unstructured set of source files. The most productive order to > read them for understanding the application is often not obvious, even for > subsystems. > > A literate program based on the book paradigm may add value to such a set > of files by putting each of them in context, and by offering a carefully > crafted reading, understanding and learning path. In other words, it puts > more emphasis on the big picture. I totally agree that providing a trail can be a great help when trying to figure out what a program is doing and how it works. Still, this is no argument in favor of a literate programming tool because it only implies that your program as well as your program documentation should be well structured and provide this introduction and learning path. However, this could also be done using ordinary comments or plain text. If you don't reorder, the order in which the information is presented is pretty much the same. To anticipate another argument: of course, literate programs can use mathematical formulae and figures which are generally not used in comment-only documentation. However, most companies will document the general design in separate documents which are full of figures (and sometimes also of formulas, depending on the domain). I would rather use cross references to external document sources than repeat the design in the program. From my point of view, a literate program should _reflect_ the design, not _be_ the design. The same applies for requirements. When a part of code is related to the implementation of a certain requirement, I would prefer to see a reference to that document in the source code. Note that the requirements document is presented to the customer and that the contract is based on it, so you cannot simply modify it (and add details the user wouldn't want to know, anyway). Markus. BTW, for noweb users, I recommend the following experiment: nountangle your program and try to read it, if the program is still quite easy to understand in the order in which the information is presented now, you did not use much reordering. 23-Apr-1998 7:08:39-GMT,2097;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 BAA21612 for ; Thu, 23 Apr 1998 01:08:38 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 02:04:27 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: I do not reorder! Date: 20 Apr 1998 16:55:13 GMT Message-ID: <6hfulh$sn5$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 18 Apr 1998, Norman Ramsey wrote: > In non-functinoal languages, I also find myself using the chunking > mechanism for tiny `procedural' abstractions that aren't part of case > analyses but for which procedures seem too heavyweight. Typical junks > might include > <> > or > <> > > In these cases, chunking is less for reordering; it is just another > abstraction mechanism. When writing imperative code, I find it easier > to come up with descriptive chunk names than function names. I won't > write > complainThatStorageWasPrevouslyDeclaredAt(c, loc) > and some compilers don't care for it either. I find that chunks are often a better means of abstraction in functional languages, as well (although, perhaps, not as often as in imperative languages). -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 23-Apr-1998 7:09:50-GMT,2809;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 BAA21878 for ; Thu, 23 Apr 1998 01:09:49 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 02:04:29 EST From: Wlodzimierz Bzyl Reply-To: LitProg@SHSU.edu, matwb@monika.univ.gda.pl Subject: Announcing: LP system for YACC/BISON Date: 20 Apr 1998 16:55:42 GMT Message-ID: <6hfume$sng$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu cV__ cV__ cV__ cV__ cV__ cV__ cV__ cV__ cV__ MM\ MM\ MM\ MM\ MM\ MM\ MM\ MM\ MM\ """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Announcing YWEB a literate programming system for YACC / BISON """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" YWEB is built upon CWEB. The main component of YWEB package is the set of change files. The YWEB is a minimalistic system. That means for a person knowing CWEB and YACC/BISON there is hardly anything to learn. All YWEB specific stuff is listed below. 1. New control code `@%' for ``control texts'', which end with the next `@>'. The control text that follow will be entered into the index in the font used for typesetting YACC/BISON symbols. 2. The `{|action|}' could be used to force `{action}' to be typeset on the same line as the preceding grammar rule. `ytangle' strips the `|' off the `{|' and `|}'. Use with care as it may invalidate the code. If the action code is typed in as `{action}', then the braces are typeset as lhs --> rhs { action } The control code `@+' could be used to cancel any line break above. 3. There is a new command line option for `yweave'. The user can decide on run-time whether actions embedded in productions should not be typeset. The command: yweave +a something.w creates something.tex with the actions omitted. In the CWEB/YWEB sources the following statement appears: ``The <> defined here should be changed whenever CWEAVE/CTANGLE is modified.'' But, updating the banner line in a change file makes it dependent on the version of CWEB/YWEB. Because I want to combine several change files (when making an internationalized version of CWEB/YWEB, for example) this and other non essential changes were delegated to separate change files. --Wlodek Bzyl. --------------------------------------------------------------- YWEB is available from the server of the Polish TeX User Group: ftp.gust.org.pl:/pub/TeX/GUST/contrib/web/yweb/yweb-1.1.tar.gz 23-Apr-1998 10:49:36-GMT,2241;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 EAA05189 for ; Thu, 23 Apr 1998 04:49:34 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 05:45:39 EST From: tony@ems.uq.edu.au Subject: Re: I do not reorder! Date: 22 Apr 1998 13:42:01 GMT Message-ID: <6hks39$gti$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, tony@ems.uq.edu.au To: LitProg@SHSU.edu I wrote some Java code recently, and I did reorder it. I couldn't see any reason why I would want the "package" and "import" statements at the start of the literate document. I defined all of the methods before the "public class ... {" line. Do as you feel most comfortable with, but I'm glad that literate programming tools *do* let me reorder Java, or anything else. Cheers, Tony. -- In <6h7dkn$rj$1@murdoch.acc.Virginia.EDU>, "Markus.Oellinger" writes: >... >I have found that modern programming languages have made this reordering >of code sections unnecessary or at least not so important than in former >days. You need no <> and <> sections in Java, >since there are none. Exceptions made it unnecessary to put the error >handling (or otherwise uninteresting) stuff in a separate section. > >As for Java, I find it most often unnecessary to do any reordering. I >can present the methods and instance variables in any order I want >anyway without reordering. I almost never use those descriptor-type >section names (i.e. collections of related code parts) with Java >(although they would be pretty handy with a language like Pascal). > >I wonder if modern languages like Java will make literal programs and >programs with exhaustive comments equal. Literate programming tools are >reduced to cross-referencers and markup tools. For me, the most useful >feature of the LP tools is to make it possible to present a program in a >hierarchical way (@*1 in CWEB, \section{} in noweb) to group related >parts. > >... 23-Apr-1998 22:12:00-GMT,2340;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 QAA28067 for ; Thu, 23 Apr 1998 16:11:58 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 15:53:45 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: I do not reorder! Date: 23 Apr 1998 19:52:03 GMT Message-ID: <6ho653$ev6$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 20 Apr 1998, Markus.Oellinger wrote: > I totally agree that providing a trail can be a great help when trying > to figure out what a program is doing and how it works. Still, this is > no argument in favor of a literate programming tool because it only > implies that your program as well as your program documentation should > be well structured and provide this introduction and learning path. > However, this could also be done using ordinary comments or plain text. > If you don't reorder, the order in which the information is presented is > pretty much the same. I'm afraid I don't agree with this at all. In-line program documentation is inadequate for the detailed explanations of *why* things are done, and more importantly, for explanations of ideas that did not work. External documentation tends to get "out of sync" with the program. These are precisely the problems that LP is aimed directly at. The added benefits of word processed documentation (table-of-contents, index, cross-references, chapters/sections/subsections, proportional fonts, etc.) make LP easier for humans to read than traditional documentation would be. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 23-Apr-1998 22:12:00-GMT,1488;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 QAA28068 for ; Thu, 23 Apr 1998 16:11:58 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 15:53:33 EST From: Joseph Osako Subject: Re: XML and Literate Programming Date: 23 Apr 1998 20:11:33 GMT Message-ID: <6ho79l$i8l$1@elna.ethz.ch> Reply-To: LitProg@SHSU.edu, s@s.net MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Anthony B. Coates wrote: > > Has anyone considered using XML (a tag based system for encoding > information, similar to SGML and HTML) for marking up literate > programming documents? Actually, I have been considering the possibility of designing an OSMIC based LP tool. Since I'm still learning OSMIC, I don't know what it would take yet, but by the nature of the Xanadu/OSMIC design it should be substantially more flexible than XML. Info on OSMIC can be found at www.xanadu.net/OSMIC/ -- Schol-R-LEA;2, ELF BiWM MGT POEE JAM LCF GS SMOF KCO First Speaker, Last Eristic Church of Finagle and Holy Bisexuality "Midge, do you have any dating tips for Cherry?" "Always remember to lock the door." || Now on Slip '.' Net as 'scholr' 23-Apr-1998 22:47:30-GMT,3213;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 QAA29303 for ; Thu, 23 Apr 1998 16:47:29 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 17:39:52 EST From: "Anthony B. Coates" Reply-To: LitProg@SHSU.edu, tony@ems.uq.edu.au Subject: XML and Literate Programming Date: 23 Apr 1998 02:17:47 GMT Message-ID: <6hm8cb$1kb$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Has anyone considered using XML (a tag based system for encoding information, similar to SGML and HTML) for marking up literate programming documents? As a part-time FunnelWeb maintainer, I know how religious the issue of how best to encode the beginning and end of code fragments can be. XML is a standard that is now supported by the W3C, the Web standards body, and it is gathering a lot of momentum. I have been planning to write something for XML, with at least the functionality of FunnelWeb, and haven't noticed anything suggesting that anyone has come this way before me. Am I wrong? In any case, I was asked to write a seminar about literate programming and XML, and I have put the Web pages for it at I would encourage those of you who write or maintain literate programming tools to have a look, because XML could be used to unite literate programming so that one general (but flexible) document syntax is understood by all of the different tools. Parsers for XML already exist, so much of the work is already done for you, compared to writing a tool from scratch for a non-standard document syntax. If you agree with me that literate programming would be well-served by passing parsing issues off to XML, and leaving tool authors to concentrate just on the LitProg-specific issues, then please e-mail me. I would like to try and organise a group of literate programming and XML people to see if we can't work something out. Just recently, the XML developers' list has successfully put together a defacto standard API for XML parsers, just on the basis of e-mail and goodwill. I'm sure that literate programming tool authors could do the same. Cheers, Tony. -- Educational Multimedia Services = reduced workloads for lecturers, teachers, and tutors = better results for students. -- Another 100% Pure Java e-mail. Is yours? -- Anthony B. Coates. Multimedia Developer (Software Design) Educational Multimedia Services TEDI, The University of Queensland. AJUG-QLD Steering Committee Member (Australian Java Users' Group ). QMUG Committee Member (Queensland Macromedia Users' Group ). E-mail: tony@ems.uq.edu.au WWW: http://www.ems.uq.edu.au/People/Tony/ UIN: 5191015 -- All opinions are mine, and may not represent those of The University of Queensland. -- 24-Apr-1998 1:37:33-GMT,1807;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 TAA04672 for ; Thu, 23 Apr 1998 19:37:32 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 23 Apr 1998 19:24:05 EST From: "Dr E. Buxbaum" Reply-To: LitProg@SHSU.edu, EB15@leicester.ac.uk Subject: Re: How to apply GPL to literate programs Date: 21 Apr 1998 13:49:56 GMT Message-ID: <6hi864$500$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Paolo Amoroso wrote: > > I'm wondering what is the best way of applying Free Software Foundation's > General Public License - GPL - to literate programs. Consider for example > an application developed with noweb whose documentation is typeset with > LaTeX. If I were writing a major application, the LaTeX files produced from weaving the various web sources would form chapters or sections in one single document, i. e. there would be a master file (ApplicationName.tex), which \inputs Module1Name.tex, Module2Name.tex and so on. It would also \input the GPL as an addendum. All that is then required for the Module files is a (LaTeX-) comment at the beginning, that this document comes under GPL (your GPL pointer). Only if the module files are also intended to be used seperately, I would use a footnote instead of a comment. Note also that under GPL you retain the copyright to your work (unlike freeware, were the copyright is signed away). Only some specified rights are transfered to the public domain. 24-Apr-1998 14:08:02-GMT,6305;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 IAA11173 for ; Fri, 24 Apr 1998 08:08:01 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 24 Apr 1998 08:48:13 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: "Incomplete" grammars Date: 23 Apr 1998 10:44:08 GMT Message-ID: <6hn61o$p87$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Lee Wittenberg wrote: > > In a recent posting, I used the term "incomplete" grammar, because (in > my senility), I could not remember the proper term. The proper term is, > of course, "context-sensitive" grammar. I apologize for any > inconvenience (or erroneous conclusions) my mistake may have caused. That is the phrase used in the Pretzel book as well. Indeed in the rules used by CWEAVE there appear some context conditions, in one of two ways: in certain reduction rules more than one category appears at the RHS (i.e., after the reduction), in which case all but one also appear at the LHS (before reduction) and are therefore context; there are also a few rules with a note attached to them, inhibiting that rule when followed by certain tokens. Nevertheless I think the use of this term is misleading, as this feature does in no way imply the awesome power of general context sensitive grammars: there is no hope at all of generating parsers for general context sensitive languages from their grammars. Moreover, I think the advantage (w.r.t bison) of allowing limited context conditions in CWEAVE is of much less importance than the drawback of having a state-less parser: in applying reductions, CWEAVE is completely ignorant of whether the resulting category makes any sense given the categories already accumulated (on the stack), with the very real danger of rogue reductions frustrating an otherwise possible parse (since reductions cannot be undone). Rather than saying more about his here, let me give a somewhat abridged quote of a private email exchange I had about this with Felix Gaertner (this was before I realised that the Pretzel scanner does not always correctly flag type names as such; the discussion supposes this point has been fixed). > As Pretzel internally uses Bison, the input grammar must be > context free (and not context sensitive as in CWEAVE). This has > been a major obstacle in getting ``good'' prettyprinting grammars > running, especially for C/C++ (where I've tried a lot). What you don't seem to realise is that your method of parsing is more powerful than the one used in WEB systems. Both are in a technical sense context free analysers, since they are implemented by a pushdown automaton (a machine using a stack, with a finite bound on how deep it ever looks down into the stack), and according to formal language theory any language recognised by a pushdown automaton is context free. The fact that the WEB grammar allows the parser to look at a bit of context does not fundamentally change their power, it's merely a convenience. In practice that convenience is used only to compensate for another great inconvenience: the WEB grammars are _interpreted_ by a machine that has no idea what part of speech it may expect to see based on the history of what it has seen already. This means that every rule you write can in principle apply at any time, regardless of whether the resulting category makes sense in that context or not; to compensate for this one can inspect a few categories that come before (these are on the stack and already reduced) and a few tokens ahead (these are probably not yet reduced). In the grammars I have written for CWEBx, very few context conditions are ever used (only about 10% of the rules, and not the most commonly used ones), and never more than one item of context is inspected. By the way, CWEBx uses a simpler model for the rules (no wildcard categories for instance) than WEB or CWEB do, which makes the grammar easier to understand, and easier to represent in tables for the parsing engine (on the other hand the WEB/CWEB parsers are compiled into code). To the contrary, a Bison parser is made by inspecting the entire grammar, and based on this a finite set of states is generated, where in every state it is known which categories man legally follow; this means that rules that are intended for other categories will not even be tried. In practice this allows for much more powerful disambiguation of grammar rules. I am sure that all the context conditions in the CWEBx grammar can be removed if the grammar is rewritten for Bison. Let me try to justify this claim a bit. [Discussion of how CWEBx uses context to recognise abstract declarators.] Using a Bison grammar, there would be hardly a problem here; [solution using an empty production]. Another case that is easy is [...] needed to avoid a line break between |x;| and |y;| in |for(x;y;z)|: the problem evaporates when you take account of the fact that you do not expect a list of statements after |for| (which would introduce line breaks), but rather a semicolon-separated list of expressions. [Other examples] The gist is: whatever can be said with WEB grammars can also be said with Bison grammars, and usually more easily. In fact, one great difficulty with WEB grammars is that I know no formal way to describe the language they actually recognise (and therefore to verify that this language contains the desired programming language), while for Bison grammars this is by definition the language generated by the grammar (note that I spoke about reductions for the WEB grammar, but productions for the Bison grammar). The latter is not quite true if Bison found it necessary to break ambiguities (conflicts), and I therefore always try to make my (Bison) grammars ambiguity-free; it sometimes is a bit tricky to do, but I have always succeeded, and it is rewarding since it gives me more confidence. Marc van Leeuwen Universite de Poitiers 25-Apr-1998 1:44:48-GMT,1180;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 TAA05239 for ; Fri, 24 Apr 1998 19:44:47 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Fri, 24 Apr 1998 20:40:56 EST From: Vincenzo De Florio Reply-To: LitProg@SHSU.edu, Vincenzo.DeFlorio@esat.kuleuven.ac.be Subject: CWEBtoHTML -- does such a beast exist?? Date: 22 Apr 1998 14:44:07 GMT Message-ID: <6hkvnn$ivb$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, I just wrote a nice piece of software using CWEB (the one which outputs TeX code) and now i'd like to get a nifty HTML equivalent of that. Any suggestions? Thanks in advance, ciao Vincenzo De Florio P.S. I would be grateful if you could mail me your replies at the following address: deflorio@esat.kuleuven.ac.be Thank you very much! 25-Apr-1998 19:21:36-GMT,1701;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 NAA17792 for ; Sat, 25 Apr 1998 13:21:35 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 25 Apr 1998 14:19:05 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Announcing: LP system for YACC/BISON Date: 23 Apr 1998 09:28:20 GMT Message-ID: <6hn1jk$ntl$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Wlodzimierz Bzyl wrote: > YWEB is built upon CWEB. The main component of YWEB package > is the set of change files. The YWEB is a minimalistic > system. That means for a person knowing CWEB and YACC/BISON > there is hardly anything to learn. All YWEB specific stuff is > listed below. [ three additions, two of which seem to be typesetting details, the third an option to suppress `actions' in the typeset document ] To my surprise there is nothing that deals directly with the syntax of yacc/bison grammars. Does this means that you treat the grammar rules as if they were C code (although the look rather differently), or did you in fact replace the parsing rules used by cweave by other ones in yweave? Another question is whether #line directives are inserted into the tangled file (and do yacc and bison handle such lines correctly?). -- Marc van Leeuwen Universite de Poitiers 26-Apr-1998 12:11:55-GMT,1514;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 GAA27722 for ; Sun, 26 Apr 1998 06:11:54 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 26 Apr 1998 07:04:35 EST From: Wlodzimierz Bzyl Reply-To: LitProg@SHSU.edu, matwb@monika.univ.gda.pl Subject: Re: Announcing: LP system for YACC/BISON Date: 23 Apr 1998 14:07:43 GMT Message-ID: <6hnhvf$298$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Marc van Leeuwen wrote: | To my surprise there is nothing that deals directly with the syntax of | yacc/bison grammars. Does this means that you treat the grammar rules as | if they were C code (although the look rather differently), or did you | in fact replace the parsing rules used by cweave by other ones in | yweave? No I did not replaced the cweave parsing rules. In yweave I have the special set of parsing rules which recognize yacc/bison code. In fact, there are two separate parsers -- the unchanged parser from CWEB and the yacc/bison parser. | Another question is whether #line directives are inserted into | the tangled file (and do yacc and bison handle such lines correctly?). I had to suppress the output of the #line directives, because BISON does not accept them. --Wlodek Bzyl. 26-Apr-1998 14:22:49-GMT,2848;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 IAA00351 for ; Sun, 26 Apr 1998 08:22:48 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sun, 26 Apr 1998 09:18:45 EST From: "Anthony B. Coates" Reply-To: LitProg@SHSU.edu, tony@ems.uq.edu.au Subject: Re: XML and Literate Programming Date: 24 Apr 1998 06:59:04 GMT Message-ID: <6hpd7o$3k6$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu An OSMIC-based LP tool would be great; I wish you luck (it would allow you to visit every past revision of the literate document, and to go back to any revision to branch off in a new direction; perhaps even to compare the use of a text fragment across versions). I saw Ted Nelson speak at WWW7 last week, and he is a captivating speaker, just as Project Xanadu has been a captivating idea for the last 30 years. It may still be ahead of its time though, so I'm going with XML, because I think there will be a much wider range of tools available for XML than for OSMIC. Cheers, Tony. -- Joseph Osako wrote: > Anthony B. Coates wrote: > > > > Has anyone considered using XML (a tag based system for encoding > > information, similar to SGML and HTML) for marking up literate > > programming documents? > > Actually, I have been considering the possibility of designing an OSMIC > based LP tool. Since I'm still learning OSMIC, I don't know what it > would take yet, but by the nature of the Xanadu/OSMIC design it should > be substantially more flexible than XML. > > Info on OSMIC can be found at www.xanadu.net/OSMIC/ > > -- > Schol-R-LEA;2, ELF BiWM MGT POEE JAM LCF GS SMOF KCO > First Speaker, Last Eristic Church of Finagle and Holy Bisexuality > "Midge, do you have any dating tips for Cherry?" "Always remember > to lock the door." || Now on Slip '.' Net as 'scholr' -- Educational Multimedia Services = reduced workloads for lecturers, teachers, and tutors = better results for students. -- Another 100% Pure Java e-mail. Is yours? -- Anthony B. Coates. Multimedia Developer (Software Design) Educational Multimedia Services TEDI, The University of Queensland. AJUG-QLD Steering Committee Member (Australian Java Users' Group ). QMUG Committee Member (Queensland Macromedia Users' Group ). E-mail: tony@ems.uq.edu.au WWW: http://www.ems.uq.edu.au/People/Tony/ UIN: 5191015 -- All opinions are mine, and may not represent those of The University of Queensland. -- 27-Apr-1998 18:52:45-GMT,3475;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 MAA01752 for ; Mon, 27 Apr 1998 12:52:44 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 27 Apr 1998 10:52:12 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: "Incomplete" grammars Date: 27 Apr 1998 14:34:47 GMT Message-ID: <6i2527$50r$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 23 Apr 1998, Marc van Leeuwen wrote: > The gist is: whatever can be said with WEB grammars can also be said > with Bison grammars, and usually more easily. In fact, one great > difficulty with WEB grammars is that I know no formal way to > describe the language they actually recognise (and therefore to > verify that this language contains the desired programming > language), while for Bison grammars this is by definition the > language generated by the grammar (note that I spoke about > reductions for the WEB grammar, but productions for the Bison > grammar). The latter is not quite true if Bison found it necessary > to break ambiguities (conflicts), and I therefore always try to make > my (Bison) grammars ambiguity-free; it sometimes is a bit tricky to > do, but I have always succeeded, and it is rewarding since it gives > me more confidence. While this is quite true, the reason I think that context-sensitive grammars are more appropriate for LP prettyprinting is that the LP parsers work on incomplete chunks rather than complete programs, and there is no way to guarantee that the programmer will construct the code chunks in such a way as to be unambiguous to the parser. For example, Knuth's code for TeX is something along the lines of (I'm working from memory here, so please pick no nits): <<*>>= program TeX; <<[[type]] declarations>> <<[[var]] declarations>> <> begin @ Some more stuff <<*>>+= (* code in the body of the pgm *) ... @ Even more stuff <<*>>+= (* yet more code *) end. [Yes, I know that Knuth doesn't use noweb notation, but the concept is the same.]] While I deplore this LP coding style (I believe that good LP style requires that both the beginning and end of a syntactic construct be in the same chunk), the parser still has to be able to do something reasonable with this code. After all, who am I to dictate to Don Knuth what is or isn't good LP style? And in my experience, it's much harder to get Pretzel (context-free) grammars than Spidery WEB (context-sensitive) grammars to deal with these contingencies. My Pretzel grammars work precisely because my LP style requires complete constructs in chunks. They fail miserably for Knuth-style coding practices. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 27-Apr-1998 23:24:58-GMT,1924;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 RAA07830 for ; Mon, 27 Apr 1998 17:24:57 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 27 Apr 1998 18:18:54 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: "Incomplete" grammars Date: 27 Apr 1998 21:59:51 GMT Message-ID: <6i2v4n$n3u$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6hn61o$p87$1@murdoch.acc.Virginia.EDU>, Marc van Leeuwen wrote: >The gist is: whatever can be said with WEB grammars can also be said >with Bison grammars, and usually more easily. In fact, one great >difficulty with WEB grammars is that I know no formal way to >describe the language they actually recognise (and therefore to >verify that this language contains the desired programming >language), while for Bison grammars this is by definition the >language generated by the grammar... What do you do about references to code chunks (modules) in Bison grammars? Do you allow a code chunk to represent some particular nonterminal? Any nonterminal? One great difficulty with Bison grammars is that it is easy to write literate programs that expand to syntactically correct programs, but the individual chunks cannot be parsed because it is not known how to treat references to other code chunks. Has anyone had the ambition to try to prettyprint a literate program by reading the whole thing into memory, starting at the beginning, and jumping to different chunks when references are made? (I am ignorant of how Pretzel works, but I have been assuming it processes one chunk at a time.) Norman 28-Apr-1998 2:32:45-GMT,1770;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 UAA11277 for ; Mon, 27 Apr 1998 20:32:44 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 27 Apr 1998 21:27:37 EST From: lippmann@cdc-ultra2.cdc.informatik.th-darmstadt.de (Jens Lippmann ) Reply-To: LitProg@SHSU.edu, lippmann@cdc-ultra2.cdc.informatik.th-darmstadt.de Subject: Re: CWEBtoHTML -- does such a beast exist?? Date: 27 Apr 1998 21:31:34 GMT Message-ID: <6i2tfm$m9j$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Hello Vincenzo, you wrote: > I just wrote a nice piece of software using CWEB (the one which outputs > TeX code) and now i'd like to get a nifty HTML equivalent of that. Yes, I have written such a converter. It works together with LaTeX2HTML. If you are interested in a demo, try http://www.cdc.informatik.tu-darmstadt.de/~lippmann/cweb2html You should use the LaTeX CWEB package by Joachim Schrod and Klaus Guntermann to LaTeXnify your CWEB files if you have not done this already. This is easy, simply install the package and plug some lines into each CWEB file. Then you'll need LaTeX2HTML, you can download it via some of the URLs that are on my demo page. Email me when you need any help, I'll answer but maybe it takes a few days. Kind regards, Jens Lippmann. -- # Jens Lippmann lippmann@cdc.informatik.tu-darmstadt.de # http://www.informatik.tu-darmstadt.de/TI # # Technische Hochschule Darmstadt http://www.tu-darmstadt.de 28-Apr-1998 13:16:29-GMT,1160;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 HAA13710 for ; Tue, 28 Apr 1998 07:16:28 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 28 Apr 1998 08:07:14 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Noweb postcards Date: 27 Apr 1998 19:01:03 GMT Message-ID: <6i2klf$gdt$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Thank you to all the kind people who have sent me postcards over the years. I'm now showing off your contributions at The noweb postcard gallery If you wish your name or email address not to appear on this page, please let me know. If you haven't sent a postcard, but would like to, my address is Norman Ramsey Department of Computer Science University of Virginia Charlottesville, VA 22903 USA 28-Apr-1998 15:00:12-GMT,9396;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 JAA16798 for ; Tue, 28 Apr 1998 09:00:11 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 28 Apr 1998 09:41:56 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: "Incomplete" grammars Date: 28 Apr 1998 09:16:12 GMT Message-ID: <6i46os$a19$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Lee Wittenberg wrote: > > On 23 Apr 1998, Marc van Leeuwen wrote: > > > The gist is: whatever can be said with WEB grammars can also be said > > with Bison grammars, and usually more easily. [...] > > While this is quite true, the reason I think that context-sensitive > grammars are more appropriate for LP prettyprinting is that the LP > parsers work on incomplete chunks rather than complete programs, and > there is no way to guarantee that the programmer will construct the > code chunks in such a way as to be unambiguous to the parser. For > example, Knuth's code for TeX is something along the lines of (I'm > working from memory here, so please pick no nits): > > <<*>>= > program TeX; > <<[[type]] declarations>> > <<[[var]] declarations>> > <> > begin > @ > Some more stuff > <<*>>+= > (* code in the body of the pgm *) > ... > @ > Even more stuff > <<*>>+= > (* yet more code *) > end. > > [Yes, I know that Knuth doesn't use noweb notation, but the concept is > the same.]] I get your point, but your example is exaggerated: in the program for TeX every matching begin-end pair occurs within a single section. Rather, the structure of the unnamed (root) module of the program is as follows: first an initial section (5) containing the |program| header followed by global label, ... variable declarations and a few procedure/function definitions, then umpteen sections containing further procedure/function definitions, and finally a section (1332) containing the main program, from its |begin| up to and including its |end.|. (Since WEB does not provide a list of sections contributing to the unnamed module, this structure is not easily revealed by inspection; in fact Knuth provided a special index entry to locate the main program.) The structure could have been made completely regular by introducing two more modules, namely @< Global function and procedure definitions @> and @< Body of the main program @> (then section 5 would be the only remaining unnamed section); it is not clear to me why Knuth did not do this. But this would really make no difference for our current discussion, since adding two module references to the end of section 5 does not essentially alter its structure for the purpose of parsing and prettyprinting. (Pedantically speaking there is one relevant question: does the period after the final |end| belong in the same section (5) as the |program| keyword, or in the @< Body of the main program @> ? I won't go into this here.) > While I deplore this LP coding style (I believe that good LP style > requires that both the beginning and end of a syntactic construct be > in the same chunk), the parser still has to be able to do something > reasonable with this code. After all, who am I to dictate to Don Knuth > what is or isn't good LP style? And in my experience, it's much > harder to get Pretzel (context-free) grammars than Spidery WEB > (context-sensitive) grammars to deal with these contingencies. > > My Pretzel grammars work precisely because my LP style requires complete > constructs in chunks. They fail miserably for Knuth-style coding > practices. Since literate programming was explicitly conceived as an extension of structured programming, I believe that it is not unreasonable to require from the programmer (even if his name is Don Knuth) that the division of the program into modules be compatible with its syntactic structure; at the very least this means that symbols belonging to the same syntactic construct (begin-end, if-then-else) appear in the same section. Violating this principle not only makes the program unreadable, it also frustrates prettyprinting, whether done with a Bison (context-free) or WEB (context-sensitive) style parser. Although I don't recall any details of the WEB grammar, I'm pretty sure it would fail to deal properly with code that is dissected as in your example (but I'll accept immediately that Pretzel grammars would fail even more miserably). It is true that the grammars of WEB and CWEB tend to recognise sytactic constructs in smaller parts than one would find in official grammars. For instance CWEB with combine |if (condition)| to category first, then proceed to combine this with a following (compound) statement and |else| or |else if| using some complicated logic. It is even so that certain rules will only increase the indentation level, while it is left to other rules to decrease that level again (making it somewhat unclear whether the indentation will always be properly balanced). It is not clear to me exactly why this was done, but it seems to have more to do with the specific requirements of prettyprinting than with the desire to handle for instance a module whose body consists of an isolated |if (condition)|. In any case I was able to simplify the logic considerably (and avoid isolated indentation changes) in CWEBx, without sacrificing in any way the quality of the prettyprinted output. There is one significant point where WEB-style parsing has an advantage in connection with literate programming: unlike a compiler, the parser has to start out without knowing what kind of syntactic construction it will be confronted with, either because it is an inline expression within the documentation, or because it is a module body. In the former case one may indeed expect almost any syntactic category, but in the latter case this is much more resticted (in CWEB I would for instance write "the |while|-loop below does such-and-so", whereas a naked 'while' is of course completely inacceptable as a module body). One might call this 'contextless parsing' (as far as I can see there is no direct connection with being or not being able to specify context in rules). For a stateless bottom-up parser like WEB's this presents no problem at all, since it always operates without knowing what it expects to get. For a Bison-parser, some special measures are required, since one has to specify a single goal categroy for the parser. There is however no reason why one could not write ::= | | | ... so that the parser would effectively start out in a state that expects any of the categories listed. The only requirement is that the mentioned categories are non-overlapping, for otherwise the parser generator would find ambiguities (so for instance the example above is not suitable for Pascal, since |f(x)| can be either an expression (function call) or a statement (procedure call)). In practice one should merge overlapping categories anyway, which avoids this problem. Provided the categories are non-overlapping, this should in principle work, since (unlike top-down parsers) bottom-up parser generators like Bison postpone deciding which reduction to apply until the complete construction has been seen. I must add though that I haven't actually tried this in practice, and I'm not sure whether one can handle the amount of uncertainty present in inline expressions. There is one other related difficulty, in that one does not know which category to attach to module _references_ either. This is however as much a problem for WEB parsers as it is for Bison parsers, and it has given rise to the curious invisible semicolon '@;' in (C)WEB. The "proper" solution would be to look up the module body and parse it to determine the category (partially tangling the program while weaving), but this does not seem partical. In practice the variation is so limited that a good guess and maybe a little help (@;) from the programmer should suffice. Let me add one remark that places Knuth's coding style in a somewhat more positive light (although I absolutely agree that it leaves room for improvement). When writing the compatibilty mode of CWEBx (for CWEB), I set myself the goal that it should be able to handle the whole of Knuth's Stanford GraphBase without problems. Sure this proved to be a lot more difficult than I had thought, but without having to take refuge to unnatural grammar rules, I eventually succeeded in bringing down the number of "irreducible scrap sequences" (representing incomplete syntactic constructions) down to six, all of which are two-token inline expressions in phrases like "we reject values |>limit|" (indeed these do not parse correctly in CWEB either, and the spacing is slightly wrong). So Knuth-style coding practices are maybe not quite as bad as you think. Marc van Leeuwen Universite de Poitiers 28-Apr-1998 22:48:34-GMT,1777;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 QAA04151 for ; Tue, 28 Apr 1998 16:48:33 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 28 Apr 1998 14:09:03 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: "Incomplete" grammars Date: 28 Apr 1998 14:43:57 GMT Message-ID: <6i4pvd$huq$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 27 Apr 1998, Norman Ramsey wrote: > Has anyone had the ambition to try to prettyprint a literate program > by reading the whole thing into memory, starting at the beginning, and > jumping to different chunks when references are made? (I am ignorant > of how Pretzel works, but I have been assuming it processes one chunk > at a time.) What a frightening, yet interesting thought. It will almost certainly require a 2-pass algorithm (not that that's necessarily a Bad Thing). Pretzel, like all the other systems I know of, processes one chunk at at time, as you assumed. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 28-Apr-1998 22:50:33-GMT,3688;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 QAA04443 for ; Tue, 28 Apr 1998 16:50:32 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 28 Apr 1998 14:10:26 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: "Incomplete" grammars Date: 28 Apr 1998 15:20:22 GMT Message-ID: <6i4s3m$j56$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: > What do you do about references to code chunks (modules) in Bison > grammars? Do you allow a code chunk to represent some particular > nonterminal? Any nonterminal? One great difficulty with Bison > grammars is that it is easy to write literate programs that expand to > syntactically correct programs, but the individual chunks cannot be > parsed because it is not known how to treat references to other code > chunks. As I just wrote in a reply to Lee Wittenberg's message, this problem is not specific to Bison grammars: it occurs in WEB and CWEB as well. The number of reasonable nonterminals is usually slightly larger than 1, depending on the programming language. In Pascal it would be 1 (namely a combined category, which might actually stand for a sequence of such separated (but not followed) by semicolons), if it weren't for the fact that the programmer sometimes does wish to include a final semicolon in the module body (so that if the module is defined in multiple sections, he doesn't have to remember which one is last and omit the semicolon there). It is (mostly) for this reason that WEB introduces the '@;' control code. In CWEBx I have so far needed only 3 nonterminals: (the default), and ; for these I decided to reuse '@;' code in a new role of magic wand: '@< Stuff @> @;' will be trated as a declaration, and similarly '@< Stuff @> @; @;' as an expression (a possible 4th category could be ). (In CWEB the default category for a module reference is which you can turn into by adding '@;'; there is no way to make it into a declaration.) As for other languages, people who use them are better judges of what is needed, but I expect similar answers. If you are willing to drop your objection to inserting codes into the program, this technique would work with Pretzel too. >From a brief inspection of Felix's example C grammar for Pretzel it appears that he uses no such extra codes, but instead allows several possibilities for the reduction of CHUNK (among which |exp| and |stmt|) apparently to be decided by the parser from the context in which CHUNK is used. However I cannot see how this is always possible, and the example grammar seems to be highly ambiguous. > Has anyone had the ambition to try to prettyprint a literate program > by reading the whole thing into memory, starting at the beginning, and > jumping to different chunks when references are made? (I am ignorant > of how Pretzel works, but I have been assuming it processes one chunk > at a time.) No, I don't think anybody has done that, though it would be an interesting experiment. Certainly Pretzel treats one chunk at the time (apparently feeding the pipeline representation into the scanner). -- Marc van Leeuwen Universite de Poitiers 28-Apr-1998 22:52:18-GMT,7305;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 QAA04476 for ; Tue, 28 Apr 1998 16:52:17 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 28 Apr 1998 14:09:13 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: "Incomplete" grammars Date: 28 Apr 1998 14:49:20 GMT Message-ID: <6i4q9g$i4q$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On Tue, 28 Apr 1998, Marc van Leeuwen wrote: > I get your point, but your example is exaggerated: in the program for > TeX every matching begin-end pair occurs within a single section. > Rather, the structure of the unnamed (root) module of the program is as > follows: first an initial section (5) containing the |program| header > followed by global label, ... variable declarations and a few > procedure/function definitions, then umpteen sections containing further > procedure/function definitions, and finally a section (1332) containing > the main program, from its |begin| up to and including its |end.|. > (Since WEB does not provide a list of sections contributing to the > unnamed module, this structure is not easily revealed by inspection; in > fact Knuth provided a special index entry to locate the main program.) > > The structure could have been made completely regular by introducing two > more modules, namely @< Global function and procedure definitions @> and > @< Body of the main program @> (then section 5 would be the only > remaining unnamed section); it is not clear to me why Knuth did not do > this. But this would really make no difference for our current > discussion, since adding two module references to the end of section 5 > does not essentially alter its structure for the purpose of parsing and > prettyprinting. (Pedantically speaking there is one relevant question: > does the period after the final |end| belong in the same section (5) as > the |program| keyword, or in the @< Body of the main program @> ? I > won't go into this here.) You are, of course, correct. The example was exaggerated. While I believe that the program, begin, and end (and probably the trailing period) are all part of the same syntactic unit, it's more an issue of personal preference (and belief), and not really worth arguing over. > Since literate programming was explicitly conceived as an extension of > structured programming, I believe that it is not unreasonable to require > from the programmer (even if his name is Don Knuth) that the division of > the program into modules be compatible with its syntactic structure; at > the very least this means that symbols belonging to the same syntactic > construct (begin-end, if-then-else) appear in the same section. > Violating this principle not only makes the program unreadable, it also > frustrates prettyprinting, whether done with a Bison (context-free) or > WEB (context-sensitive) style parser. Although I don't recall any > details of the WEB grammar, I'm pretty sure it would fail to deal > properly with code that is dissected as in your example (but I'll accept > immediately that Pretzel grammars would fail even more miserably). I agree that violation of this principle makes programs less readable, but I don't think I agree with requiring other programmers to abide by my rules. > For a stateless bottom-up parser like WEB's this presents no problem at > all, since it always operates without knowing what it expects to get. > For a Bison-parser, some special measures are required, since one has to > specify a single goal categroy for the parser. There is however no > reason why one could not write > > ::= | | | ... > > so that the parser would effectively start out in a state that expects > any of the categories listed. The only requirement is that the mentioned > categories are non-overlapping, for otherwise the parser generator would > find ambiguities (so for instance the example above is not suitable for > Pascal, since |f(x)| can be either an expression (function call) or a > statement (procedure call)). In practice one should merge overlapping > categories anyway, which avoids this problem. Provided the categories > are non-overlapping, this should in principle work, since (unlike > top-down parsers) bottom-up parser generators like Bison postpone > deciding which reduction to apply until the complete construction has > been seen. I must add though that I haven't actually tried this in > practice, and I'm not sure whether one can handle the amount of > uncertainty present in inline expressions. This is exactly what I've had to do in my Pretzel grammars. The interesting thing is that, until one's used the grammar extensively, one doesn't really know which non-terminals should be allowed as goals (and some of them turn out to be mutually exclusive). Usually, things like |f(x)| are typeset the same way whether they are a function or a procedure call -- this is certainly true in Pascal -- but I've come across situations (forgive me if I can't recall a specific example, but please believe me that they exist -- at least in Java) where the same code is typeset differently according to context, which may not be in the chunk in question. Maybe Norman's idea of a global parse is a Good Idea. > Let me add one remark that places Knuth's coding style in a somewhat > more positive light (although I absolutely agree that it leaves room for > improvement). When writing the compatibilty mode of CWEBx (for CWEB), I > set myself the goal that it should be able to handle the whole of > Knuth's Stanford GraphBase without problems. Sure this proved to be a > lot more difficult than I had thought, but without having to take refuge > to unnatural grammar rules, I eventually succeeded in bringing down the > number of "irreducible scrap sequences" (representing incomplete > syntactic constructions) down to six, all of which are two-token inline > expressions in phrases like "we reject values |>limit|" (indeed these do > not parse correctly in CWEB either, and the spacing is slightly wrong). > So Knuth-style coding practices are maybe not quite as bad as you think. Actually, since Knuth was the first literate programmer, there's no reason to expect his early webs to follow any of the guidelines we now follow from experience. The GraphBase shows much better LP style than his earlier programs. In fact, the only places I remember finding fault have more to do with his unfamiliarity with C idioms than anything else. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Computer Science Department | "I said I wanted you to save the world, I Kean University | never said it was worth saving." Union, NJ 07083 | | -- William Goldman leew@samson.kean.edu | "Brothers" (1986) ------------------------------------------------------------------------ 30-Apr-1998 6:37:23-GMT,912;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 AAA13872 for ; Thu, 30 Apr 1998 00:37:22 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 30 Apr 1998 01:34:18 EST From: "koruykin d." Reply-To: LitProg@SHSU.edu, koruykin@dk.mech.unn.runnet.ru Subject: plplot Date: Thu, 30 Apr 1998 09:40:25 +0300 Message-ID: <35481CD9.C35BFF8E@dk.mech.unn.runnet.ru> MIME-Version: 1.0 Content-Type: text/plain; charset=koi8-r Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Does anybody know something about plplot function plsKeyEH? If some plplot sources is known for somebody give a link, please. 30-Apr-1998 16:34:34-GMT,865;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 KAA12056 for ; Thu, 30 Apr 1998 10:34:33 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from amc.com by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 30 Apr 1998 11:21:50 EST Received: from cheetah.amc.com by amc.com (4.1/SMI-4.1) id AA02986; Thu, 30 Apr 98 09:19:23 PDT Received: by cheetah.amc.com (4.1/SMI-4.1) id AA08818; Thu, 30 Apr 98 09:19:23 PDT Date: Thu, 30 Apr 98 09:19:23 PDT From: maryb@amc.com (Mary Bos) Reply-To: LitProg@SHSU.edu, maryb@amc.com Message-ID: <9804301619.AA08818@cheetah.amc.com> To: LitProg@SHSU.edu Subject: unsubscribe unsubscribe LitProg 30-Apr-1998 16:42:11-GMT,903;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 KAA12375 for ; Thu, 30 Apr 1998 10:42:09 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 30 Apr 1998 11:22:47 EST From: Eric Reply-To: LitProg@SHSU.edu, ericliu@cs.pdx.edu Subject: Converting Web to NoWeb Date: 30 Apr 1998 02:21:46 GMT Message-ID: <6i8n7q$g1c$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Did anyone ever make a utility converting big Web files to NoWeb equivalent ones? What is the best way to approach this conversion? Thanks. Eric 1-May-1998 3:13:27-GMT,4632;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 VAA14569 for ; Thu, 30 Apr 1998 21:13:21 -0600 (MDT) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from MVB.SAIC.COM by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 30 Apr 1998 22:10:34 EST From: greyno@mcs.com Subject: Re: XML and Literate Programming Date: 1 May 1998 02:31:32 GMT Message-ID: <6ibc64$794$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, greyno@mcs.com To: LitProg@SHSU.edu In <6hm8cb$1kb$1@news.interlog.com>, "Anthony B. Coates" writes: >Has anyone considered using XML (a tag based system for encoding >information, similar to SGML and HTML) for marking up literate >programming documents? As a part-time FunnelWeb maintainer, I know how >religious the issue of how best to encode the beginning and end of code >fragments can be. XML is a standard that is now supported by the W3C, >the Web standards body, and it is gathering a lot of momentum. I have >been planning to write something for XML > >I would like to try and organise a group of literate programming and XML >people to see if we can't work something out. Just recently, the XML >developers' list has successfully put together a defacto standard API >for XML parsers, just on the basis of e-mail and goodwill. I'm sure >that literate programming tool authors could do the same. Tony - When you say you're planning to write something for XML, do you mean a tool to literate DTDs, or a tool to use XML for literate programming in languages like C? I took a look at the website; a good intro, and I definitely support what you're to do. However, I would recommend sticking with litprog for programming code and dropping the stuff about html and the spreadsheet. I think it confuses the issue, and in truth the examples you cite are easily (well, sort of easy) accomplished with SGML tools (or at least one, Jade) without specialized litprog tools. Here's a good mantra: "the document *is* the database." So boilerplate across a website is actually quite easy with DSSSL, although this is probably not widely understood. In fact, with the transformation capabilities of DSSSL you can generate pretty much whatever sort of html (or XML) you want out of any SGML \source. Example: I put together a prototype that resulted in a webpage for each system supported, with a list including hotlinks of all bug reports for the system. The source of the system doc page, however, was completely unrelated to the source for the bug reports. A simple batch job regenerates the entire site. One could create quite a sophisticated bug-tracking system using such techniques. XML will have the same problem xxxweb systems have always had: unnatural syntax. The Man himself calls (or called) (c)web a prototype system; it works great for him and some others, but I can assure you I will never have the time and energy to tackle the idiosyncratic syntax. I've been working for the past few months on an SGML/DSSSL based litprog system, and I'm just about convinced that any really useful literate programming tool must be a metaprogramming tool. Its the only way I can see to allow literate markup of program text without going outside of the programming language. In essence, the literate programming tool must work with the syntax tree (in some form), without imposing its own syntax on the user. I'm very optimistic that this will work with SGML, since shortrefs can be used as a kind of macro substitution mechanism. The Big Secret: stipulate that input code must be legal C, i.e. compilable; this allows forget us to virtually disregard the DTD, just make all non-container keywords such as "int" and "for" EMPTY elements, and everything else ANY. With shortrefs we can automatically markup elements with explicit delimiters (e.g. parenthesized expressions); the remaining syntactic elements can be handled programmatically without too much pain, since we already know it's legal code. Use a two-pass system: first pass receives a "naive" version of the program, and generates a markuped up file that reflects the abstract structure of the code. The second pass actually generates the formatted representation - or generates code in another language. The reaally cool part is that comments in the source code can contain SGML entity references, whose entities will be parsed etc as SGML source. An SGML #include, as it were.